gsd-pi 2.75.0 → 2.76.0

package/src/resources/extensions/gsd/prompts/scan.md

@@ -0,0 +1,79 @@
+You are performing a focused codebase scan.
+
+## Scan Parameters
+
+- **Focus:** {{focus}}
+- **Documents to produce:** {{documents}}
+- **Output directory:** `{{outputDir}}`
+
+## Working Directory
+
+`{{workingDirectory}}`
+
+## Instructions
+
+1. Explore the codebase to understand its structure, technology choices, and patterns
+2. For each document listed above, produce a well-structured Markdown file in `{{outputDir}}/`
+3. Use the document schemas below as a guide for each output file
+
+For this scan, only these documents are relevant: **{{documents}}**. Refer only to those schemas below and ignore the rest.
+
+### Document Schemas
+
+**STACK.md** — Technology stack overview
+- Languages, runtimes, and versions
+- Key frameworks and libraries (with versions where visible)
+- Build tools and bundlers
+- Package manager
+
+**INTEGRATIONS.md** — External dependencies and integrations
+- Third-party APIs and services
+- Database systems
+- Authentication providers
+- Infrastructure and deployment platforms
+- Communication services (email, messaging, etc.)
+
+**ARCHITECTURE.md** — Architectural patterns and design decisions
+- Overall architecture style (monolith, microservices, monorepo, etc.)
+- Core data flow
+- Key design patterns in use
+- Module/package boundaries
+
+**STRUCTURE.md** — Directory and code organization
+- Top-level directory layout with purpose
+- Source code organization
+- Test organization
+- Configuration file locations
+
+**CONVENTIONS.md** — Coding conventions and standards
+- Naming conventions (files, functions, variables)
+- Code style and formatting rules
+- Import/export patterns
+- Error handling patterns
+- TypeScript/language-specific conventions
+
+**TESTING.md** — Testing patterns and practices
+- Test framework(s) in use
+- Test file naming and location conventions
+- Test helper and fixture patterns
+- Coverage requirements (if any)
+- How to run tests
+
+**CONCERNS.md** — Technical debt and risks
+- Known areas of technical debt
+- Fragile or high-risk code areas
+- Missing test coverage
+- Outdated dependencies
+- Performance bottlenecks
+- Security considerations
+
+## Rules
+
+- Write only the documents listed in **Documents to produce** — do not generate extra files
+- Each document must be a clean, standalone Markdown file starting with a `# Heading`
+- Be factual: report what you observe in the code, not what might be ideal
+- Keep each document focused and scannable — use headers, bullet points, and code snippets
+- Do NOT modify any source files
+- After writing all documents, summarize what was produced (file names and line counts)
+
+{{skillActivation}}

package/src/resources/extensions/gsd/prompts/workflow-oneshot.md

@@ -0,0 +1,26 @@
+# Oneshot Workflow: {{displayName}}
+
+You are running a **oneshot** workflow called `{{name}}`. Oneshot workflows are
+prompt-only — there is no STATE.json, no phase tracking, no artifact directory,
+and no resume mechanism. Just execute the instructions below and return.
+
+## User Arguments
+
+`{{userArgs}}`
+
+(If empty, use sensible defaults from the workflow body.)
+
+## Workflow Instructions
+
+{{body}}
+
+## Execution Rules
+
+1. **No scaffolding.** Do not create `.gsd/workflows/` directories, STATE.json
+   files, or run directories unless the instructions explicitly tell you to
+   write a specific artifact.
+2. **No branch switching.** Work on the current branch.
+3. **Be concise.** Oneshot workflows produce a single focused output (a report,
+   a summary, a code change, a PR comment) — finish in this turn.
+4. **Ask only when blocked.** If the instructions need information you can't
+   discover, ask one clear question. Otherwise proceed.

package/src/resources/extensions/gsd/python-resolver.ts

@@ -0,0 +1,76 @@
+/**
+ * Cross-platform Python interpreter resolver.
+ *
+ * Provides utilities to detect the available Python interpreter on the current
+ * system and to normalize shell commands that reference `python`/`python3` so
+ * that they use whichever interpreter is actually installed.
+ *
+ * On Windows the canonical names differ (`py -3`, `python`, `python3`), so
+ * hard-coded `python3` invocations fail with exit 127. This module detects the
+ * working interpreter once (cached for the process lifetime) and rewrites
+ * commands accordingly.
+ *
+ * @module python-resolver
+ */
+
+import { spawnSync } from "node:child_process";
+
+/** Cached result of `detectPythonExecutable`. `undefined` means not yet probed. */
+let cached: string | null | undefined;
+
+/**
+ * Returns the first working Python invocation on this system, or `null` if no
+ * Python interpreter is found.
+ *
+ * Probe order:
+ * - Windows: `py -3` → `python` → `python3`
+ * - All other platforms: `python3` → `python`
+ *
+ * The result is cached for the lifetime of the process to avoid repeated
+ * `spawnSync` calls.
+ */
+export function detectPythonExecutable(): string | null {
+  if (cached !== undefined) return cached;
+  const candidates: string[] = process.platform === "win32"
+    ? ["py -3", "python", "python3"]
+    : ["python3", "python"];
+  for (const candidate of candidates) {
+    const [bin, ...args] = candidate.split(" ");
+    const r = spawnSync(bin, [...args, "--version"], { stdio: "ignore" });
+    if (!r.error && r.status === 0) {
+      cached = candidate;
+      return candidate;
+    }
+  }
+  cached = null;
+  return null;
+}
+
+/**
+ * Rewrites a shell command string so that leading `python`/`python3`/`py`
+ * tokens at command boundaries are replaced with the interpreter returned by
+ * `detectPythonExecutable`.
+ *
+ * Only tokens at command boundaries (start of string, or after `&&`, `||`,
+ * `;`) are rewritten — mid-string occurrences (e.g. file paths containing
+ * "python") are left intact.
+ *
+ * When no Python interpreter is detected, the command is returned unchanged so
+ * that the caller receives a meaningful "command not found" error rather than a
+ * silent no-op.
+ *
+ * @param command - The shell command string to normalize.
+ * @returns The command with Python interpreter tokens rewritten, or the
+ *   original command if no rewrite is needed.
+ */
+export function normalizePythonCommand(command: string): string {
+  const executable = detectPythonExecutable();
+  if (!executable) return command;
+
+  // Split on common shell separators to handle compound commands.
+  // We reconstruct the string preserving the original separators.
+  return command.replace(
+    /(^\s*|(?:&&|\|\||;)\s*)(?:python3?|py(?:\s+-\d+)?)(?=\s|$)/g,
+    (_match, pre: string) => `${pre}${executable}`,
+  );
+}

package/src/resources/extensions/gsd/run-manager.ts

@@ -16,8 +16,9 @@
 import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { stringify } from "yaml";
-import { loadDefinition, substituteParams } from "./definition-loader.js";
+import { loadDefinition, loadDefinitionFromFile, substituteParams } from "./definition-loader.js";
 import { initializeGraph, writeGraph, readGraph } from "./graph.js";
+import { resolvePlugin } from "./workflow-plugins.js";
 import type { WorkflowDefinition } from "./definition-loader.js";
 import type { WorkflowGraph } from "./graph.js";
 
@@ -67,48 +68,81 @@ function deriveStatus(graph: WorkflowGraph): "pending" | "running" | "complete"
 
 // ─── Public API ──────────────────────────────────────────────────────────
 
+/**
+ * Create a run directory from an explicit definition file path.
+ * Preferred over `createRun` when the caller has already resolved the file
+ * (e.g. via the plugin resolver).
+ */
+export function createRunFromDefinition(
+  basePath: string,
+  defName: string,
+  definitionFile: string,
+  overrides?: Record<string, string>,
+): string {
+  const rawDef = loadDefinitionFromFile(definitionFile);
+  const def: WorkflowDefinition = overrides
+    ? substituteParams(rawDef, overrides)
+    : substituteParams(rawDef);
+
+  const timestamp = makeTimestamp();
+  const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
+  mkdirSync(runDir, { recursive: true });
+
+  writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
+
+  const graph = initializeGraph(def);
+  writeGraph(runDir, graph);
+
+  if (overrides && Object.keys(overrides).length > 0) {
+    writeFileSync(
+      join(runDir, "PARAMS.json"),
+      JSON.stringify(overrides, null, 2),
+      "utf-8",
+    );
+  }
+
+  return runDir;
+}
+
 /**
  * Create a new isolated run directory for a workflow definition.
  *
- * 1. Loads the definition from `<basePath>/.gsd/workflow-defs/<defName>.yaml`
- * 2. Applies parameter substitution if overrides are provided
- * 3. Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/`
- * 4. Writes frozen DEFINITION.yaml, initialized GRAPH.yaml, and optional PARAMS.json
+ * Resolution order:
+ *   1. Plugin resolver (project → global → bundled), YAML format only.
+ *   2. Legacy `.gsd/workflow-defs/<defName>.yaml`.
  *
- * @param basePath — project root directory
- * @param defName — definition filename (without .yaml extension)
- * @param overrides — optional parameter overrides (merged with definition defaults)
- * @returns Full path to the created run directory
- * @throws Error if the definition file doesn't exist or is invalid
+ * Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/` containing
+ * DEFINITION.yaml (frozen), GRAPH.yaml (initialized), and optional PARAMS.json.
+ *
+ * @throws Error if no matching definition is found anywhere.
  */
 export function createRun(
   basePath: string,
   defName: string,
   overrides?: Record<string, string>,
 ): string {
-  const defsDir = join(basePath, ".gsd", DEFS_DIR);
+  // Try the unified plugin resolver first — honors project/global overrides.
+  const plugin = resolvePlugin(basePath, defName);
+  if (plugin && plugin.format === "yaml") {
+    return createRunFromDefinition(basePath, defName, plugin.path, overrides);
+  }
 
-  // Load and validate the definition
+  // Fall back to legacy `.gsd/workflow-defs/<defName>.yaml`.
+  const defsDir = join(basePath, ".gsd", DEFS_DIR);
   const rawDef = loadDefinition(defsDir, defName);
-
-  // Apply parameter substitution if overrides provided
   const def: WorkflowDefinition = overrides
     ? substituteParams(rawDef, overrides)
-    : substituteParams(rawDef); // still resolve default params if any
+    : substituteParams(rawDef);
 
-  // Create the run directory
   const timestamp = makeTimestamp();
   const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
   mkdirSync(runDir, { recursive: true });
 
-  // Freeze the definition as DEFINITION.yaml
   writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
 
-  // Initialize and write GRAPH.yaml
   const graph = initializeGraph(def);
   writeGraph(runDir, graph);
 
-  // Write PARAMS.json if overrides were provided
   if (overrides && Object.keys(overrides).length > 0) {
     writeFileSync(
       join(runDir, "PARAMS.json"),

package/src/resources/extensions/gsd/setup-catalog.ts

@@ -0,0 +1,105 @@
+// GSD — Setup catalog (single source of truth for onboarding steps + provider sub-views)
+//
+// Re-exports filtered views over PROVIDER_REGISTRY (key-manager.ts) and owns the
+// canonical ONBOARDING_STEPS list. Consumers (CLI wizard, /gsd setup hub,
+// onboarding handler, web alignment) all read from here so adding a step or
+// provider lands in one place. Keep this module thin: no behavior beyond
+// filters + lookup helpers, so it stays cycle-safe even though it depends on
+// key-manager for the provider catalog.
+
+import { PROVIDER_REGISTRY, type ProviderInfo } from "./key-manager.js"
+
+export type OnboardingStepId =
+  | "llm"
+  | "model"
+  | "search"
+  | "remote"
+  | "tool-keys"
+  | "prefs"
+  | "skills"
+  | "doctor"
+  | "project"
+
+export interface OnboardingStepDef {
+  id: OnboardingStepId
+  label: string
+  /** Required steps gate the "complete" flag. Skipped required steps mark the wizard incomplete. */
+  required: boolean
+  /** Short description shown in /gsd setup status hub. */
+  hint: string
+}
+
+/**
+ * Canonical ordered list of onboarding steps.
+ *
+ * To add a new step:
+ *   1. Append here (or insert at the right position).
+ *   2. Bump FLOW_VERSION in onboarding-state.ts so existing users get re-prompted.
+ *   3. Wire its CLI runner in src/onboarding.ts (and handlers/onboarding.ts for --step).
+ */
+export const ONBOARDING_STEPS: readonly OnboardingStepDef[] = [
+  { id: "llm",       label: "LLM provider & auth",      required: true,  hint: "Sign in or paste an API key" },
+  { id: "model",     label: "Default model",            required: false, hint: "Pick a default model for the chosen provider" },
+  { id: "search",    label: "Web search provider",      required: false, hint: "Brave, Tavily, or Anthropic built-in" },
+  { id: "remote",    label: "Remote questions",         required: false, hint: "Discord / Slack / Telegram notifications" },
+  { id: "tool-keys", label: "Tool API keys",            required: false, hint: "Context7, Jina, Groq voice, etc." },
+  { id: "prefs",     label: "Global preferences",       required: false, hint: "Mode, profile, notifications" },
+  { id: "skills",    label: "Skills install",           required: false, hint: "Browse and install skill plugins" },
+  { id: "doctor",    label: "Validate setup",           required: false, hint: "Run provider doctor checks" },
+  { id: "project",   label: "Project init",             required: false, hint: "Bootstrap .gsd/ in this repo" },
+]
+
+const STEP_INDEX = new Map(ONBOARDING_STEPS.map((s, i) => [s.id, i]))
+
+export function getStep(id: string): OnboardingStepDef | undefined {
+  const idx = STEP_INDEX.get(id as OnboardingStepId)
+  return idx === undefined ? undefined : ONBOARDING_STEPS[idx]
+}
+
+export function isValidStepId(id: string): id is OnboardingStepId {
+  return STEP_INDEX.has(id as OnboardingStepId)
+}
+
+/**
+ * Given a possibly-stale resume point, return the nearest next step that is
+ * still defined in the catalog. Falls back to the first step.
+ */
+export function nearestResumeStep(lastResumePoint: string | null, completedSteps: string[]): OnboardingStepId {
+  const completed = new Set(completedSteps)
+  // First incomplete step at or after the lastResumePoint
+  let startIdx = 0
+  if (lastResumePoint && STEP_INDEX.has(lastResumePoint as OnboardingStepId)) {
+    startIdx = STEP_INDEX.get(lastResumePoint as OnboardingStepId) ?? 0
+  }
+  for (let i = startIdx; i < ONBOARDING_STEPS.length; i++) {
+    if (!completed.has(ONBOARDING_STEPS[i].id)) return ONBOARDING_STEPS[i].id
+  }
+  // Everything from the resume point is complete — try from the start
+  for (const step of ONBOARDING_STEPS) {
+    if (!completed.has(step.id)) return step.id
+  }
+  return ONBOARDING_STEPS[0].id
+}
+
+// ─── Provider catalog views ───────────────────────────────────────────────────
+
+export function getLlmProviders(): ProviderInfo[] {
+  return PROVIDER_REGISTRY.filter(p => p.category === "llm")
+}
+
+export function getToolProviders(): ProviderInfo[] {
+  return PROVIDER_REGISTRY.filter(p => p.category === "tool")
+}
+
+export function getSearchProviders(): ProviderInfo[] {
+  return PROVIDER_REGISTRY.filter(p => p.category === "search")
+}
+
+export function getRemoteProviders(): ProviderInfo[] {
+  return PROVIDER_REGISTRY.filter(p => p.category === "remote")
+}
+
+/** Provider IDs that count as "the user has an LLM configured" for shouldRunOnboarding. */
+export function getLlmProviderIds(): string[] {
+  return Array.from(new Set([...getLlmProviders().map(p => p.id), "claude-code"]))
+}

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

@@ -44,6 +44,8 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { debugCount, debugTime } from './debug-logger.js';
 import { logWarning, logError } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
+import { loadEffectiveGSDPreferences } from './preferences.js';
+import { detectPendingEscalation } from './escalation.js';
 
 import {
   isDbAvailable,
@@ -60,6 +62,7 @@ import {
   updateSliceStatus,
   updateTaskStatus,
   getPendingGateCountForTurn,
+  autoHealSketchFlags,
   type MilestoneRow,
   type SliceRow,
   type TaskRow,
@@ -849,7 +852,15 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress);
   }
 
-  const activeSliceContext = resolveSliceDependencies(activeMilestoneSlices);
+  // ADR-011 auto-heal: if a slice has a PLAN on disk but is still flagged is_sketch=1
+  // (e.g. a crash between plan-slice write and the sketch flip), reconcile before
+  // running phase derivation so the flag doesn't misroute state.
+  autoHealSketchFlags(activeMilestone.id, (sid) =>
+    !!resolveSliceFile(basePath, activeMilestone.id, sid, "PLAN"),
+  );
+  // Re-read slices after auto-heal so downstream reads see fresh is_sketch values.
+  const healedSlices = getMilestoneSlices(activeMilestone.id);
+  const activeSliceContext = resolveSliceDependencies(healedSlices);
   if (!activeSliceContext.activeSlice) {
     // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked'
     if (process.env.GSD_SLICE_LOCK) {
@@ -869,10 +880,24 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
       progress: { milestones: milestoneProgress, slices: sliceProgress },
     };
   }
-  const { activeSlice } = activeSliceContext;
+  const { activeSlice, activeSliceRow } = activeSliceContext;
 
   const planFile = resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "PLAN");
   if (!planFile) {
+    // ADR-011: sketch slices with progressive_planning enabled enter the
+    // `refining` phase — a refine-slice unit expands the sketch into a full plan
+    // before execution. When the flag is off, sketches are indistinguishable
+    // from a missing plan and fall through to the normal `planning` phase.
+    const progressive = loadEffectiveGSDPreferences()?.preferences?.phases?.progressive_planning === true;
+    if (progressive && activeSliceRow?.is_sketch === 1) {
+      return {
+        activeMilestone, activeSlice, activeTask: null,
+        phase: 'refining', recentDecisions: [], blockers: [],
+        nextAction: `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
+        registry, requirements,
+        progress: { milestones: milestoneProgress, slices: sliceProgress },
+      };
+    }
     return {
       activeMilestone, activeSlice, activeTask: null,
       phase: 'planning', recentDecisions: [], blockers: [],
@@ -965,6 +990,29 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     }
   }
 
+  // ADR-011 Phase 2: pause-on-escalation takes precedence over dispatching the
+  // next task. `awaiting_review` tasks (continueWithDefault=true) are NOT
+  // surfaced here — they let the loop continue.
+  //
+  // We do NOT gate this on `phases.mid_execution_escalation` — creation of
+  // new escalations is gated at the write site (tools/complete-task.ts:315),
+  // but any escalation_pending row already persisted in the DB must be
+  // honored even if the user later toggles the flag off. Otherwise those
+  // rows would silently orphan, the loop would advance past the paused task,
+  // and the user's prior resolution never lands.
+  const escalatingTaskId = detectPendingEscalation(tasks, basePath);
+  if (escalatingTaskId) {
+    return {
+      activeMilestone, activeSlice, activeTask,
+      phase: 'escalating-task', recentDecisions: [],
+      blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
+      nextAction: `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
+      activeWorkspace: undefined,
+      registry, requirements,
+      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
+    };
+  }
+
   if (!blockerTaskId) {
     const isTriggered = checkReplanTrigger(basePath, activeMilestone.id, activeSlice.id);
     if (isTriggered) {

package/src/resources/extensions/gsd/templates/PREFERENCES.md

@@ -44,19 +44,19 @@ uok:
   legacy_fallback:
     enabled: false
   gates:
-    enabled: false
+    enabled: true
   model_policy:
-    enabled: false
+    enabled: true
   execution_graph:
-    enabled: false
+    enabled: true
   gitops:
-    enabled: false
-    turn_action: status-only
+    enabled: true
+    turn_action: commit
     turn_push: false
   audit_unified:
-    enabled: false
+    enabled: true
   plan_v2:
-    enabled: false
+    enabled: true
 auto_visualize:
 auto_report:
 parallel:

package/src/resources/extensions/gsd/tests/agent-end-retry.test.ts

@@ -2,8 +2,7 @@
  * agent-end-retry.test.ts — Regression checks for the agent_end model.
  *
  * The per-unit one-shot resolve function lives at module level in auto-loop.ts
- * (_currentResolve). handleAgentEnd is a thin compatibility wrapper around
- * resolveAgentEnd().
+ * (_currentResolve). agent_end is handled via resolveAgentEnd().
  */
 
 import test from "node:test";
@@ -62,38 +61,6 @@ test("legacy pendingAgentEndRetry state is gone", () => {
   );
 });
 
-test("handleAgentEnd is a thin compatibility wrapper", () => {
-  const source = getAutoTsSource();
-  const fnIdx = source.indexOf("export async function handleAgentEnd");
-  assert.ok(fnIdx > -1, "handleAgentEnd must exist in auto.ts");
-  const fnBlock = source.slice(fnIdx, source.indexOf("\n// ─── ", fnIdx + 100));
-
-  assert.ok(
-    fnBlock.includes("resolveAgentEnd("),
-    "handleAgentEnd must delegate to resolveAgentEnd",
-  );
-  assert.ok(
-    !fnBlock.includes("pendingAgentEndRetry"),
-    "handleAgentEnd must not use legacy retry state",
-  );
-  assert.ok(
-    !fnBlock.includes("dispatchNextUnit"),
-    "handleAgentEnd must not dispatch recursively",
-  );
-});
-
-test("handleAgentEnd early return calls resolveAgentEndCancelled", () => {
-  const source = getAutoTsSource();
-  const fnIdx = source.indexOf("export async function handleAgentEnd");
-  assert.ok(fnIdx > -1, "handleAgentEnd must exist in auto.ts");
-  const fnBlock = source.slice(fnIdx, source.indexOf("\n// ─── ", fnIdx + 100));
-
-  assert.ok(
-    fnBlock.includes("resolveAgentEndCancelled()"),
-    "handleAgentEnd must call resolveAgentEndCancelled on early return to prevent orphaned promises",
-  );
-});
-
 test("pauseAuto calls resolveAgentEndCancelled to unblock the loop", () => {
   const source = getAutoTsSource();
   const fnIdx = source.indexOf("export async function pauseAuto");

package/src/resources/extensions/gsd/tests/artifact-corruption-2630.test.ts

@@ -46,6 +46,8 @@ function makeSliceRow(overrides?: Partial<SliceRow>): SliceRow {
     observability_impact: '',
     sequence: 4,
     replan_triggered_at: null,
+    is_sketch: 0,
+    sketch_scope: '',
     ...overrides,
   };
 }
@@ -77,6 +79,11 @@ function makeTaskRow(overrides?: Partial<TaskRow>): TaskRow {
     expected_output: [],
     observability_impact: '',
     sequence: 0,
+    blocker_source: '',
+    escalation_pending: 0,
+    escalation_awaiting_review: 0,
+    escalation_artifact_path: null,
+    escalation_override_applied_at: null,
     ...overrides,
   };
 }

package/src/resources/extensions/gsd/tests/auto-dashboard.test.ts

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
 
 import {
   unitVerb,
@@ -15,6 +16,10 @@ import {
   getWidgetMode,
   cycleWidgetMode,
   _resetWidgetModeForTests,
+  _resetLastCommitCacheForTests,
+  _refreshLastCommitForTests,
+  _getLastCommitForTests,
+  _getLastCommitFetchedAtForTests,
 } from "../auto-dashboard.ts";
 
 const autoSource = readFileSync(join(process.cwd(), "src", "resources", "extensions", "gsd", "auto.ts"), "utf-8");
@@ -215,6 +220,50 @@ test("auto progress widget renders RTK savings under the footer stats line", ()
   assert.match(dashboardSource, /lines\.push\(rightAlign\("", theme\.fg\("dim", cachedRtkLabel\), width\)\);/);
 });
 
+test("last commit refresh backs off cleanly when base path is not a git repo", (t) => {
+  const dir = makeTempDir("non-git");
+  mkdirSync(dir, { recursive: true });
+
+  t.after(() => {
+    cleanup(dir);
+    _resetLastCommitCacheForTests();
+  });
+
+  _resetLastCommitCacheForTests();
+  _refreshLastCommitForTests(dir);
+
+  assert.equal(_getLastCommitForTests(dir), null);
+  assert.ok(
+    _getLastCommitFetchedAtForTests() > 0,
+    "non-git refresh should still advance fetchedAt to avoid render-loop retries",
+  );
+});
+
+test("last commit refresh still returns commit info for a valid git repo", (t) => {
+  const dir = makeTempDir("git");
+  mkdirSync(dir, { recursive: true });
+
+  execFileSync("git", ["init", "-b", "main"], { cwd: dir, stdio: "pipe" });
+  execFileSync("git", ["config", "user.name", "GSD Test"], { cwd: dir, stdio: "pipe" });
+  execFileSync("git", ["config", "user.email", "gsd@example.com"], { cwd: dir, stdio: "pipe" });
+  writeFileSync(join(dir, "README.md"), "hello\n", "utf-8");
+  execFileSync("git", ["add", "README.md"], { cwd: dir, stdio: "pipe" });
+  execFileSync("git", ["commit", "-m", "test: seed dashboard repo"], { cwd: dir, stdio: "pipe" });
+
+  t.after(() => {
+    cleanup(dir);
+    _resetLastCommitCacheForTests();
+  });
+
+  _resetLastCommitCacheForTests();
+  _refreshLastCommitForTests(dir);
+
+  const lastCommit = _getLastCommitForTests(dir);
+  assert.ok(lastCommit, "git repo should produce last commit metadata");
+  assert.match(lastCommit!.message, /test: seed dashboard repo/);
+  assert.ok(lastCommit!.timeAgo.length > 0, "relative time should be populated");
+});
+
 // ─── extractUatSliceId ───────────────────────────────────────────────────
 
 test("extractUatSliceId extracts slice ID from M001/S01 format", () => {