gsd-pi 2.74.0-dev.28a6415 → 2.74.0-dev.658744a

package/src/resources/extensions/gsd/auto/phases.ts

@@ -29,6 +29,8 @@ import { debugLog } from "../debug-logger.js";
 import { PROJECT_FILES } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
+import { pauseAutoForProviderError } from "../provider-error-pause.js";
+import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.js";
 import { join, basename, dirname, parse as parsePath } from "node:path";
 import { existsSync, cpSync, readdirSync } from "node:fs";
 import {
@@ -59,6 +61,15 @@ import {
   getRequiredWorkflowToolsForAutoUnit,
 } from "../workflow-mcp.js";
 
+// ─── Session timeout auto-resume state ────────────────────────────────────────
+
+let consecutiveSessionTimeouts = 0;
+const MAX_SESSION_TIMEOUT_AUTO_RESUMES = 3;
+
+export function resetSessionTimeoutState(): void {
+  consecutiveSessionTimeouts = 0;
+}
+
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 
 /**
@@ -1502,24 +1513,75 @@ export async function runUnitPhase(
       debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient });
       return { action: "break", reason: "provider-pause" };
     }
-    // Session creation timeout (not a structural error): pause auto-mode
-    // and let the provider-error-resume timer handle recovery (#3767). This
-    // matches the provider-pause path — break out cleanly, don't hard-stop.
+    // Timeout category covers two distinct scenarios:
+    //   1. Session creation timeout (120s) — transient, auto-resume with backoff
+    //   2. Unit hard timeout (30min+) — stuck agent, pause for manual review
     // Structural errors (TypeError, is not a function) are NOT transient
     // and must hard-stop to avoid infinite retry loops.
     if (
       unitResult.errorContext?.isTransient &&
       unitResult.errorContext?.category === "timeout"
     ) {
+      const isSessionCreationTimeout = unitResult.errorContext.message?.includes("Session creation timed out");
+
+      if (isSessionCreationTimeout) {
+        consecutiveSessionTimeouts += 1;
+        const baseRetryAfterMs = 30_000;
+        const retryAfterMs = baseRetryAfterMs * 2 ** Math.max(0, consecutiveSessionTimeouts - 1);
+        const allowAutoResume = consecutiveSessionTimeouts <= MAX_SESSION_TIMEOUT_AUTO_RESUMES;
+
+        if (!allowAutoResume) {
+          ctx.ui.notify(
+            `Session creation timed out ${consecutiveSessionTimeouts} consecutive times for ${unitType} ${unitId}. Pausing for manual review.`,
+            "warning",
+          );
+        }
+
+        debugLog("autoLoop", {
+          phase: "session-timeout-pause",
+          unitType, unitId,
+          consecutiveSessionTimeouts,
+          retryAfterMs,
+          allowAutoResume,
+        });
+
+        const errorDetail = ` for ${unitType} ${unitId}`;
+        await pauseAutoForProviderError(
+          ctx.ui,
+          errorDetail,
+          () => deps.pauseAuto(ctx, pi),
+          {
+            isRateLimit: false,
+            isTransient: allowAutoResume,
+            retryAfterMs,
+            resume: allowAutoResume
+              ? () => {
+                  void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    ctx.ui.notify(
+                      `Session timeout recovery failed: ${message}`,
+                      "error",
+                    );
+                  });
+                }
+              : undefined,
+          },
+        );
+        await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+        await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+        return { action: "break", reason: "session-timeout" };
+      }
+
+      // Unit hard timeout (30min+): pause without auto-resume — stuck agent
       ctx.ui.notify(
-        `Session creation timed out for ${unitType} ${unitId}. Pausing auto-mode (recoverable).`,
+        `Unit timed out for ${unitType} ${unitId} (supervision may have failed). Pausing auto-mode.`,
         "warning",
       );
-      debugLog("autoLoop", { phase: "session-timeout-pause", unitType, unitId });
+      debugLog("autoLoop", { phase: "unit-hard-timeout-pause", unitType, unitId });
       await deps.pauseAuto(ctx, pi);
       await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
       await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
-      return { action: "break", reason: "session-timeout" };
+      return { action: "break", reason: "unit-hard-timeout" };
     }
     // All other cancelled states (structural errors, non-transient failures): hard stop
     if (s.currentUnit) {
@@ -1549,6 +1611,8 @@ export async function runUnitPhase(
   // Guard: stopAuto() may have nulled s.currentUnit via s.reset() while
   // this coroutine was suspended at `await runUnit(...)` (#2939).
   if (s.currentUnit) {
+    // Reset session timeout counter — any successful unit clears the slate
+    consecutiveSessionTimeouts = 0;
     await deps.closeoutUnit(
       ctx,
       s.basePath,

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -535,10 +535,10 @@ export function buildFlatRateContext(
   prefs?: { flat_rate_providers?: readonly string[] },
 ): FlatRateContext {
   let authMode: FlatRateContext["authMode"];
-  const getAuthMode = ctx?.modelRegistry?.getProviderAuthMode;
-  if (typeof getAuthMode === "function") {
+  const registry = ctx?.modelRegistry;
+  if (registry && typeof registry.getProviderAuthMode === "function") {
     try {
-      const mode = getAuthMode(provider);
+      const mode = registry.getProviderAuthMode(provider);
       if (mode === "apiKey" || mode === "oauth" || mode === "externalCli" || mode === "none") {
         authMode = mode;
       }

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -1121,11 +1121,15 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
           });
         }
 
-        // Notify UI
+        // Notify UI — surface actionable details (#4259)
         if (result.status === "fail") {
-          const blockingCount = result.checks.filter(c => !c.passed && c.blocking).length;
+          const blockingChecks = result.checks.filter(c => !c.passed && c.blocking);
+          const blockingCount = blockingChecks.length;
+          const details = blockingChecks.slice(0, 3).map(c => `  \u2022 ${c.message}`).join("\n");
+          const suffix = blockingChecks.length > 3 ? `\n  \u2022 ...and ${blockingChecks.length - 3} more` : "";
+          const evidenceNote = `\nSee ${sid}-PRE-EXEC-VERIFY.json for full details.`;
           ctx.ui.notify(
-            `Pre-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found`,
+            `Pre-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found\n${details}${suffix}${evidenceNote}`,
             "error",
           );
           preExecPauseNeeded = true;

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -264,18 +264,30 @@ export function verifyExpectedArtifact(
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
   // For unit types with no verifiable artifact (null path), the parent directory
   // is missing on disk — treat as stale completion state so the key gets evicted (#313).
-  if (!absPath) return false;
-  if (!existsSync(absPath)) return false;
+  if (!absPath) {
+    logWarning("recovery", `verify-fail ${unitType} ${unitId}: resolveExpectedArtifactPath returned null (parent dir missing)`);
+    return false;
+  }
+  if (!existsSync(absPath)) {
+    logWarning("recovery", `verify-fail ${unitType} ${unitId}: existsSync false for ${absPath}`);
+    return false;
+  }
 
   if (unitType === "validate-milestone") {
     const validationContent = readFileSync(absPath, "utf-8");
-    if (!isValidationTerminal(validationContent)) return false;
+    if (!isValidationTerminal(validationContent)) {
+      logWarning("recovery", `verify-fail ${unitType} ${unitId}: validation not terminal (len=${validationContent.length}) at ${absPath}`);
+      return false;
+    }
   }
 
   if (unitType === "plan-milestone") {
     try {
       const roadmap = parseLegacyRoadmap(readFileSync(absPath, "utf-8"));
-      if (roadmap.slices.length === 0) return false;
+      if (roadmap.slices.length === 0) {
+        logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${absPath}`);
+        return false;
+      }
     } catch (err) {
       logWarning("recovery", `plan-milestone roadmap verification failed: ${err instanceof Error ? err.message : String(err)}`);
       return false;
@@ -292,7 +304,10 @@ export function verifyExpectedArtifact(
     // Accept checkbox-style (- [x] **T01: ...) or heading-style (### T01 -- / ### T01: / ### T01 —)
     const hasCheckboxTask = /^- \[[xX ]\] \*\*T\d+:/m.test(planContent);
     const hasHeadingTask = /^#{2,4}\s+T\d+\s*(?:--|—|:)/m.test(planContent);
-    if (!hasCheckboxTask && !hasHeadingTask) return false;
+    if (!hasCheckboxTask && !hasHeadingTask) {
+      logWarning("recovery", `verify-fail ${unitType} ${unitId}: plan has no task checkbox/heading (len=${planContent.length}) at ${absPath}`);
+      return false;
+    }
   }
 
   // execute-task: DB status is authoritative. Fall back to checked-checkbox
@@ -349,10 +364,15 @@ export function verifyExpectedArtifact(
 
         if (taskIds && taskIds.length > 0) {
           const tasksDir = resolveTasksDir(base, mid, sid);
-          if (tasksDir) {
-            for (const tid of taskIds) {
-              const taskPlanFile = join(tasksDir, `${tid}-PLAN.md`);
-              if (!existsSync(taskPlanFile)) return false;
+          if (!tasksDir) {
+            logWarning("recovery", `verify-fail ${unitType} ${unitId}: resolveTasksDir returned null for ${mid}/${sid}`);
+            return false;
+          }
+          for (const tid of taskIds) {
+            const taskPlanFile = join(tasksDir, `${tid}-PLAN.md`);
+            if (!existsSync(taskPlanFile)) {
+              logWarning("recovery", `verify-fail ${unitType} ${unitId}: task plan missing ${taskPlanFile}`);
+              return false;
             }
           }
         }

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -102,6 +102,7 @@ function isSamePath(a: string, b: string): boolean {
   try {
     return realpathSync(a) === realpathSync(b);
   } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return false;
     logWarning("worktree", `isSamePath failed: ${(e as Error).message}`);
     return false;
   }

package/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts

@@ -6,6 +6,7 @@ import type {
 
 import { getAutoDashboardData, startAuto, type AutoDashboardData } from "../auto.js";
 import { resetTransientRetryState } from "./agent-end-recovery.js";
+import { resetSessionTimeoutState } from "../auto/phases.js";
 
 type AutoResumeSnapshot = Pick<AutoDashboardData, "active" | "paused" | "stepMode" | "basePath">;
 
@@ -43,10 +44,11 @@ export async function resumeAutoAfterProviderDelay(
     return "missing-base";
   }
 
-  // Reset the transient retry counter before restarting — without this,
-  // consecutiveTransientCount accumulates across pause/resume cycles and
-  // permanently locks out auto-resume after MAX_TRANSIENT_AUTO_RESUMES errors.
+  // Reset retry counters before restarting — without this, counters
+  // accumulate across pause/resume cycles and permanently lock out
+  // auto-resume after their respective MAX thresholds.
   resetTransientRetryState();
+  resetSessionTimeoutState();
 
   await deps.startAuto(
     ctx as ExtensionCommandContext,

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -4,6 +4,8 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 
 import { registerExitCommand } from "../exit-command.js";
 import { registerWorktreeCommand } from "../worktree-command.js";
+import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
+import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
@@ -65,6 +67,10 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
 
   installEpipeGuard();
 
+  // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
+  // GSD-owned `before_agent_start` dispatch step (#3338).
+  const ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[] = [];
+
   pi.registerCommand("kill", {
     description: "Exit GSD immediately (no cleanup)",
     handler: async (_args: string, _ctx: ExtensionCommandContext) => {
@@ -80,7 +86,15 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     ["journal-tools", () => registerJournalTools(pi)],
     ["query-tools", () => registerQueryTools(pi)],
     ["shortcuts", () => registerShortcuts(pi)],
-    ["hooks", () => registerHooks(pi)],
+    ["hooks", () => registerHooks(pi, ecosystemHandlers)],
+    ["ecosystem", () => {
+      void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {
+        logWarning(
+          "ecosystem",
+          `loader failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }],
   ];
 
   for (const [name, register] of nonCriticalRegistrations) {

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -3,6 +3,10 @@ import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 
+import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
+import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
+import { getEcosystemReadyPromise } from "../ecosystem/loader.js";
+
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
@@ -35,7 +39,10 @@ async function syncServiceTierStatus(ctx: ExtensionContext): Promise<void> {
   ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
 
-export function registerHooks(pi: ExtensionAPI): void {
+export function registerHooks(
+  pi: ExtensionAPI,
+  ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
+): void {
   pi.on("session_start", async (_event, ctx) => {
     initNotificationStore(process.cwd());
     installNotifyInterceptor(ctx);
@@ -45,8 +52,12 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
     await syncServiceTierStatus(ctx);
-    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-    prepareWorkflowMcpForProject(ctx, process.cwd());
+    // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
+    const { isInAutoWorktree } = await import("../auto-worktree.js");
+    if (!isInAutoWorktree(process.cwd())) {
+      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, process.cwd());
+    }
 
     // Apply show_token_cost preference (#1515)
     try {
@@ -87,13 +98,63 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetAskUserQuestionsCache();
     clearDiscussionFlowState();
     await syncServiceTierStatus(ctx);
-    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-    prepareWorkflowMcpForProject(ctx, process.cwd());
+    // Skip MCP auto-prep when running inside an auto-worktree. The worktree
+    // already has .mcp.json from createAutoWorktree, and re-running the writer
+    // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
+    // CLI path resolution), dirtying the tree and breaking the milestone merge.
+    const { isInAutoWorktree } = await import("../auto-worktree.js");
+    if (!isInAutoWorktree(process.cwd())) {
+      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, process.cwd());
+    }
     loadToolApiKeys();
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
-    return buildBeforeAgentStartResult(event, ctx);
+    // Wait for ecosystem loader to finish (no-op after first turn).
+    await getEcosystemReadyPromise();
+
+    // GSD's own context injection (existing behavior — unchanged).
+    const gsdResult = await buildBeforeAgentStartResult(event, ctx);
+
+    // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
+    // deriveState has its own ~100ms cache so this is cheap on repeat calls.
+    try {
+      const state = await deriveState(process.cwd());
+      updateSnapshot(state);
+    } catch {
+      updateSnapshot(null);
+    }
+
+    // Chain ecosystem handlers using pi's runner.ts chaining protocol:
+    // each handler sees the systemPrompt mutated by prior handlers.
+    let currentSystemPrompt = gsdResult?.systemPrompt ?? event.systemPrompt;
+    // `any` because pi's BeforeAgentStartEventResult.message uses an internal
+    // CustomMessage type that's not re-exported (see ecosystem/gsd-extension-api.ts).
+    let lastMessage: any = gsdResult?.message;
+
+    for (const handler of ecosystemHandlers) {
+      try {
+        const r = await handler(
+          { ...event, systemPrompt: currentSystemPrompt },
+          ctx,
+        );
+        if (r?.systemPrompt !== undefined) currentSystemPrompt = r.systemPrompt;
+        if (r?.message) lastMessage = r.message;
+      } catch (err) {
+        safetyLogWarning(
+          "ecosystem",
+          `before_agent_start handler failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    // Compose result. Return undefined if nothing changed (preserves runner contract).
+    if (currentSystemPrompt === event.systemPrompt && !lastMessage) return undefined;
+    return {
+      systemPrompt: currentSystemPrompt !== event.systemPrompt ? currentSystemPrompt : undefined,
+      message: lastMessage,
+    };
   });
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
@@ -125,7 +186,10 @@ export function registerHooks(pi: ExtensionAPI): void {
     await ensureDbOpen();
     const state = await deriveState(basePath);
     if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
-    if (state.phase !== "executing") return;
+    // Write checkpoint for ALL phases, not just "executing" — discuss, research,
+    // and planning also carry in-memory state (user answers, gate verification)
+    // that would be lost on compaction (#4258).
+    // if (state.phase !== "executing") return;
 
     const sliceDir = resolveSlicePath(basePath, state.activeMilestone.id, state.activeSlice.id);
     if (!sliceDir) return;
@@ -261,7 +325,7 @@ export function registerHooks(pi: ExtensionAPI): void {
   // ── Safety harness: evidence collection + destructive command warnings ──
   pi.on("tool_call", async (event, ctx) => {
     if (!isAutoActive()) return;
-    safetyRecordToolCall(event.toolName, event.input as Record<string, unknown>);
+    safetyRecordToolCall(event.toolCallId, event.toolName, event.input as Record<string, unknown>);
 
     // Destructive command classification (warn only, never block)
     if (isToolCallEventType("bash", event)) {

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

@@ -1,6 +1,6 @@
 // GSD Extension — Unified Cache Invalidation
 //
-// Three module-scoped caches exist across the GSD extension:
+// Three module-scoped read caches exist across the GSD extension:
 //   1. State cache (state.ts)  — memoized deriveState() result
 //   2. Path cache  (paths.ts)  — directory listing results (readdirSync)
 //   3. Parse cache (files.ts)  — parsed markdown file results
@@ -8,22 +8,33 @@
 // After any file write that changes .gsd/ contents, all three must be
 // invalidated together to prevent stale reads. This module provides a
 // single function that clears all three atomically.
+//
+// NOTE: The DB `artifacts` table is NOT included here. Earlier versions
+// called clearArtifacts() as part of this bundle (#793), intending to
+// force deriveState() to re-parse from disk when files were edited
+// out-of-band. But invalidateAllCaches() fires on every post-unit pass,
+// so bundling a DESTRUCTIVE `DELETE FROM artifacts` with routine cache
+// invalidation meant every row written by saveArtifactToDb / writeAndStore
+// was wiped within seconds — leaving the milestone completed on disk but
+// the `artifacts` table empty and the agent looping on "file exists but
+// DB record missing" recovery calls. If a call site genuinely needs the
+// artifact table cleared after an out-of-band file mutation, it should
+// invoke clearArtifacts() from gsd-db.js explicitly — do not add it back
+// here.
 
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
-import { clearArtifacts } from './gsd-db.js';
 
 /**
- * Invalidate all GSD runtime caches in one call.
+ * Invalidate all GSD runtime read caches in one call.
  *
  * Call this after file writes, milestone transitions, merge reconciliation,
  * or any operation that changes .gsd/ contents on disk. Forgetting to clear
- * any single cache causes stale reads (see #431, #793).
+ * any single cache causes stale reads (see #431).
  */
 export function invalidateAllCaches(): void {
   invalidateStateCache();
   clearPathCache();
   clearParseCache();
-  clearArtifacts();
 }

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|language";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -80,6 +80,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "backlog", desc: "Manage backlog items (add, promote, remove, list)" },
   { cmd: "pr-branch", desc: "Create clean PR branch filtering .gsd/ commits" },
   { cmd: "add-tests", desc: "Generate tests for completed slices" },
+  { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -269,6 +270,10 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "--dry-run", desc: "Preview what would be filtered" },
     { cmd: "--name", desc: "Custom branch name" },
   ],
+  language: [
+    { cmd: "off",   desc: "Clear the language preference (revert to default)" },
+    { cmd: "clear", desc: "Alias for off — clear the language preference" },
+  ],
 };
 
 function filterOptions(

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -4,7 +4,7 @@ import type { GSDState } from "../../types.js";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
-import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard } from "../../commands-prefs-wizard.js";
+import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard, handleLanguage } from "../../commands-prefs-wizard.js";
 import { runEnvironmentChecks } from "../../doctor-environment.js";
 import { deriveState } from "../../state.js";
 import { handleCmux } from "../../commands-cmux.js";
@@ -395,6 +395,10 @@ export async function handleCoreCommand(
     await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
     return true;
   }
+  if (trimmed === "language" || trimmed.startsWith("language ")) {
+    await handleLanguage(trimmed.replace(/^language\s*/, "").trim(), ctx);
+    return true;
+  }
   if (trimmed === "cmux" || trimmed.startsWith("cmux ")) {
     await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx);
     return true;

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -756,8 +756,8 @@ export async function handlePrefsWizard(
 /** Wrap a YAML value in double quotes if it contains special characters. */
 export function yamlSafeString(val: unknown): string {
   if (typeof val !== "string") return String(val);
-  if (/[:#{\[\]'"`,|>&*!?@%]/.test(val) || val.trim() !== val || val === "") {
-    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  if (/[:#{\[\]'"`,|>&*!?@%\r\n]/.test(val) || val.trim() !== val || val === "") {
+    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n")}"`;
   }
   return val;
 }
@@ -825,7 +825,7 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "dynamic_routing", "uok", "token_profile", "phases", "parallel",
     "auto_visualize", "auto_report",
     "verification_commands", "verification_auto_fix", "verification_max_retries",
-    "search_provider", "context_selection",
+    "search_provider", "context_selection", "language",
   ];
 
   const seen = new Set<string>();
@@ -862,3 +862,57 @@ export async function ensurePreferencesFile(
     ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
   }
 }
+
+/**
+ * Handle `/gsd language [code]` — set or clear the global language preference.
+ * Without an argument, shows the current setting.
+ * Project-level override can be set by editing `.gsd/preferences.md` directly
+ * (project language overrides global when both are set).
+ */
+export async function handleLanguage(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const path = getGlobalGSDPreferencesPath();
+  const lang = args.trim();
+
+  // Show current setting when called without argument
+  if (!lang) {
+    const loaded = loadGlobalGSDPreferences();
+    const current = loaded?.preferences.language;
+    if (current) {
+      ctx.ui.notify(`Current language preference: ${current}\nUse /gsd language <name> to change, or /gsd language off to clear.`, "info");
+    } else {
+      ctx.ui.notify("No language preference set. Use /gsd language <name> to set one (e.g. /gsd language Chinese).", "info");
+    }
+    return;
+  }
+
+  // Ensure preferences file exists with the canonical template
+  await ensurePreferencesFile(path, ctx, "global");
+
+  // Read via the same validated path as other handlers
+  const existing = loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : { version: 1 };
+
+  if (lang === "off" || lang === "none" || lang === "clear") {
+    delete prefs.language;
+    ctx.ui.notify("Language preference cleared. GSD will use the default language.", "info");
+  } else {
+    // Validate before writing — reject values that would fail on next load
+    if (lang.length > 50 || /[\r\n]/.test(lang)) {
+      ctx.ui.notify(
+        "Language value must be 50 characters or fewer with no newlines (e.g. /gsd language Chinese).",
+        "warning",
+      );
+      return;
+    }
+    prefs.language = lang;
+    ctx.ui.notify(`Language preference set to: ${lang}\nGSD will now respond in ${lang} across all sessions.`, "info");
+  }
+
+  const rawContent = existsSync(path) ? readFileSync(path, "utf-8") : `---\nversion: 1\n---\n`;
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  const body = extractBodyAfterFrontmatter(rawContent)
+    ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  await saveFile(path, `---\n${frontmatter}---${body}`);
+  await ctx.waitForIdle();
+  await ctx.reload();
+}

package/src/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