gsd-pi 2.71.0-dev.977c553 → 2.71.0-dev.e17e0ce

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

@@ -27,7 +27,7 @@ import {
   runFinalize,
 } from "./phases.js";
 import { debugLog } from "../debug-logger.js";
-import { isInfrastructureError } from "./infra-errors.js";
+import { isInfrastructureError, isTransientCooldownError, getCooldownRetryAfterMs, COOLDOWN_FALLBACK_WAIT_MS, MAX_COOLDOWN_RETRIES } from "./infra-errors.js";
 import { resolveEngine } from "../engine-resolver.js";
 
 /**
@@ -48,6 +48,7 @@ export async function autoLoop(
   let iteration = 0;
   const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
   let consecutiveErrors = 0;
+  let consecutiveCooldowns = 0;
   const recentErrorMessages: string[] = [];
 
   while (s.active) {
@@ -203,6 +204,7 @@ export async function autoLoop(
 
         deps.clearUnitTimeout();
         consecutiveErrors = 0;
+        consecutiveCooldowns = 0;
         recentErrorMessages.length = 0;
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
         debugLog("autoLoop", { phase: "iteration-complete", iteration });
@@ -265,6 +267,7 @@ export async function autoLoop(
       if (finalizeResult.action === "continue") continue;
 
       consecutiveErrors = 0; // Iteration completed successfully
+      consecutiveCooldowns = 0;
       recentErrorMessages.length = 0;
       deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } });
       debugLog("autoLoop", { phase: "iteration-complete", iteration });
@@ -300,6 +303,47 @@ export async function autoLoop(
         break;
       }
 
+      // ── Credential cooldown: wait and retry with bounded budget ──
+      // A 429 triggers a 30s credential backoff in AuthStorage. If the SDK's
+      // getApiKey() retries couldn't outlast the window, the error surfaces
+      // here. Wait for the cooldown to clear rather than counting it as a
+      // consecutive failure — but cap retries so we don't spin for hours
+      // on persistent quota exhaustion.
+      if (isTransientCooldownError(loopErr)) {
+        consecutiveCooldowns++;
+        const retryAfterMs = getCooldownRetryAfterMs(loopErr);
+        debugLog("autoLoop", {
+          phase: "cooldown-wait",
+          iteration,
+          consecutiveCooldowns,
+          retryAfterMs,
+          error: msg,
+        });
+
+        if (consecutiveCooldowns > MAX_COOLDOWN_RETRIES) {
+          ctx.ui.notify(
+            `Auto-mode stopped: ${consecutiveCooldowns} consecutive credential cooldowns — rate limit or quota may be persistently exhausted.`,
+            "error",
+          );
+          await deps.stopAuto(
+            ctx,
+            pi,
+            `${consecutiveCooldowns} consecutive credential cooldowns exceeded retry budget`,
+          );
+          break;
+        }
+
+        const waitMs = (retryAfterMs !== undefined && retryAfterMs > 0 && retryAfterMs <= 60_000)
+          ? retryAfterMs + 500 // Use structured hint + small buffer
+          : COOLDOWN_FALLBACK_WAIT_MS;
+        ctx.ui.notify(
+          `Credentials in cooldown (${consecutiveCooldowns}/${MAX_COOLDOWN_RETRIES}) — waiting ${Math.round(waitMs / 1000)}s before retrying.`,
+          "warning",
+        );
+        await new Promise(resolve => setTimeout(resolve, waitMs));
+        continue; // Retry iteration without incrementing consecutiveErrors
+      }
+
       consecutiveErrors++;
       recentErrorMessages.push(msg.length > 120 ? msg.slice(0, 120) + "..." : msg);
       debugLog("autoLoop", {

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

@@ -1183,6 +1183,8 @@ export async function runUnitPhase(
     s.verbose,
     s.autoModeStartModel,
     sidecarItem ? undefined : { isRetry, previousTier },
+    undefined,
+    s.manualSessionModelOverride,
   );
   s.currentUnitRouting =
     modelResult.routing as AutoSession["currentUnitRouting"];

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

@@ -87,6 +87,10 @@ export class AutoSession {
   previousProjectRootEnv: string | null = null;
   hadProjectRootEnv = false;
   projectRootEnvCaptured = false;
+  previousMilestoneLockEnv: string | null = null;
+  hadMilestoneLockEnv = false;
+  milestoneLockEnvCaptured = false;
+  sessionMilestoneLock: string | null = null;
   gitService: GitServiceImpl | null = null;
 
   // ── Dispatch counters ────────────────────────────────────────────────────
@@ -107,6 +111,8 @@ export class AutoSession {
 
   // ── Model state ──────────────────────────────────────────────────────────
   autoModeStartModel: StartModel | null = null;
+  /** Explicit /gsd model pin captured at bootstrap (session-scoped policy override). */
+  manualSessionModelOverride: StartModel | null = null;
   currentUnitModel: Model<Api> | null = null;
   /** Fully-qualified model ID (provider/id) set after selectAndApplyModel + hook overrides (#2899). */
   currentDispatchedModelId: string | null = null;
@@ -200,6 +206,10 @@ export class AutoSession {
     this.previousProjectRootEnv = null;
     this.hadProjectRootEnv = false;
     this.projectRootEnvCaptured = false;
+    this.previousMilestoneLockEnv = null;
+    this.hadMilestoneLockEnv = false;
+    this.milestoneLockEnvCaptured = false;
+    this.sessionMilestoneLock = null;
     this.gitService = null;
 
     // Dispatch
@@ -214,6 +224,7 @@ export class AutoSession {
 
     // Model
     this.autoModeStartModel = null;
+    this.manualSessionModelOverride = null;
     this.currentUnitModel = null;
     this.currentDispatchedModelId = null;
     this.originalModelId = null;

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

@@ -6,7 +6,13 @@
  * or AutoContext dependency. State accessors are passed as callbacks.
  */
 
-import type { ExtensionContext, ExtensionCommandContext, SessionMessageEntry } from "@gsd/pi-coding-agent";
+import type {
+  ExtensionContext,
+  ExtensionCommandContext,
+  SessionMessageEntry,
+  ReadonlyFooterDataProvider,
+  Theme,
+} from "@gsd/pi-coding-agent";
 import type { GSDState } from "./types.js";
 import { getCurrentBranch } from "./worktree.js";
 import { getActiveHook } from "./post-unit-hooks.js";
@@ -17,7 +23,6 @@ import {
   resolveSliceFile,
 } from "./paths.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { formatShortcut } from "./files.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
@@ -38,6 +43,7 @@ import {
   type RtkSessionSavings,
 } from "../shared/rtk-session-stats.js";
 import { logWarning } from "./workflow-logger.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
 
 // ─── UAT Slice Extraction ─────────────────────────────────────────────────────
 
@@ -358,12 +364,23 @@ function getLastCommit(basePath: string): { timeAgo: string; message: string } |
 // ─── Footer Factory ───────────────────────────────────────────────────────────
 
 /**
- * Footer factory that renders zero lines — hides the built-in footer entirely.
- * All footer info (pwd, branch, tokens, cost, model) is shown inside the
- * progress widget instead, so there's no gap or redundancy.
+ * Footer factory used by auto-mode.
+ * Keep footer minimal but preserve extension status context from setStatus().
  */
-export const hideFooter = () => ({
-  render(_width: number): string[] { return []; },
+function sanitizeFooterStatus(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+export const hideFooter = (_tui: unknown, theme: Theme, footerData: ReadonlyFooterDataProvider) => ({
+  render(width: number): string[] {
+    const extensionStatuses = footerData.getExtensionStatuses();
+    if (extensionStatuses.size === 0) return [];
+    const statusLine = Array.from(extensionStatuses.entries())
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([, text]) => sanitizeFooterStatus(text))
+      .join(" ");
+    return [truncateToWidth(theme.fg("dim", statusLine), width, theme.fg("dim", "..."))];
+  },
   invalidate() {},
   dispose() {},
 });
@@ -646,14 +663,6 @@ export function updateProgressWidget(
           : "";
         lines.push(rightAlign(headerLeft, headerRight, width));
 
-        // Worktree/branch right-aligned below header
-        const branchLabel = worktreeName && cachedBranch
-          ? `${worktreeName} (${cachedBranch})`
-          : cachedBranch ?? "";
-        if (branchLabel) {
-          lines.push(rightAlign("", theme.fg("dim", branchLabel), width));
-        }
-
         // Show health signal details when degraded (yellow/red)
         if (score.level !== "green" && score.signals.length > 0 && widgetMode !== "min") {
           // Show up to 3 most relevant signals in compact form
@@ -917,15 +926,17 @@ export function updateProgressWidget(
         // Hints line
         const hintParts: string[] = [];
         hintParts.push("esc pause");
-        hintParts.push(`${formatShortcut("Ctrl+Alt+G")} dashboard`);
+        hintParts.push(`${formattedShortcutPair("dashboard")} dashboard`);
+        hintParts.push(`${formattedShortcutPair("parallel")} parallel`);
         const hintStr = theme.fg("dim", hintParts.join(" | "));
         const commitStr = lastCommit
           ? theme.fg("dim", `${lastCommit.timeAgo} ago: ${commitMsg}`)
           : "";
+        const locationStr = theme.fg("dim", widgetPwd);
         if (commitStr) {
-          lines.push(rightAlign(`${pad}${commitStr}`, hintStr, width));
+          lines.push(rightAlign(`${pad}${locationStr} · ${commitStr}`, hintStr, width));
         } else {
-          lines.push(rightAlign("", hintStr, width));
+          lines.push(rightAlign(`${pad}${locationStr}`, hintStr, width));
         }
 
         lines.push(...ui.bar());

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

@@ -14,6 +14,7 @@ import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js";
 import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabilityOverrides, adjustToolSet, filterToolsForProvider } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
+import { getSessionModelOverride } from "./session-model-override.js";
 
 export interface ModelSelectionResult {
   /** Routing metadata for metrics recording */
@@ -72,8 +73,15 @@ export async function selectAndApplyModel(
   /** When false (interactive/guided-flow), skip dynamic routing and use the session model.
    *  Dynamic routing only applies in auto-mode where cost optimization is expected. (#3962) */
   isAutoMode = true,
+  /** Explicit /gsd model pin captured at bootstrap for long-running auto loops. */
+  sessionModelOverride?: { provider: string; id: string } | null,
 ): Promise<ModelSelectionResult> {
-  const modelConfig = resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
+  const effectiveSessionModelOverride = sessionModelOverride === undefined
+    ? getSessionModelOverride(ctx.sessionManager.getSessionId())
+    : (sessionModelOverride ?? undefined);
+  const modelConfig = effectiveSessionModelOverride
+    ? undefined
+    : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
   let routing: { tier: string; modelDowngraded: boolean } | null = null;
   let appliedModel: Model<Api> | null = null;
 

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

@@ -85,6 +85,7 @@ import { sep as pathSep } from "node:path";
 import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js";
 import { resolveDefaultSessionModel, resolveDynamicRoutingConfig } from "./preferences-models.js";
 import type { WorktreeResolver } from "./worktree-resolver.js";
+import { getSessionModelOverride } from "./session-model-override.js";
 
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: () => boolean;
@@ -266,12 +267,17 @@ export async function bootstrapAutoSession(
   // Capture the user's session model before guided-flow dispatch can apply a
   // phase-specific planning model for a discuss turn (#2829).
   //
-  // GSD PREFERENCES.md takes priority over the session model from settings.json
-  // (#3517).  The session model (ctx.model) comes from findInitialModel() which
-  // reads defaultProvider/defaultModel from ~/.gsd/agent/settings.json.  When
-  // the user has explicit model preferences in PREFERENCES.md, those should win.
+  // Precedence:
+  // 1) Explicit session override via /gsd model (this session)
+  // 2) GSD model preferences from PREFERENCES.md
+  // 3) Current session model from settings/session restore
+  //
+  // This preserves #3517 defaults while honoring explicit runtime model
+  // selection for subsequent /gsd runs in the same session.
+  const manualSessionOverride = getSessionModelOverride(ctx.sessionManager.getSessionId());
   const preferredModel = resolveDefaultSessionModel(ctx.model?.provider);
-  const startModelSnapshot = preferredModel
+  const startModelSnapshot = manualSessionOverride
+    ?? preferredModel
     ?? (ctx.model
       ? { provider: ctx.model.provider, id: ctx.model.id }
       : null);
@@ -678,7 +684,7 @@ export async function bootstrapAutoSession(
     }
 
     // ── DB lifecycle ──
-    const gsdDbPath = join(s.basePath, ".gsd", "gsd.db");
+    const gsdDbPath = resolveProjectRootDbPath(s.basePath);
     const gsdDirPath = join(s.basePath, ".gsd");
     if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
       const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));
@@ -731,6 +737,7 @@ export async function bootstrapAutoSession(
         id: startModelSnapshot.id,
       };
     }
+    s.manualSessionModelOverride = manualSessionOverride ?? null;
 
     // Apply worker model override from parallel orchestrator (#worker-model).
     // GSD_WORKER_MODEL is injected by the coordinator when parallel.worker_model

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -92,7 +92,7 @@ export function clearInFlightTools(): void {
  * handler. When these errors occur, retrying the same unit will produce the same
  * failure, so the retry loop must be broken.
  */
-const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}' in JSON|Unexpected end of JSON|Unexpected token.*in JSON/i;
+const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON/i;
 
 /**
  * Returns true if the error message indicates a tool invocation failure due to

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

@@ -2043,7 +2043,7 @@ export function mergeMilestoneToMain(
   // 12. Remove worktree directory first (must happen before branch deletion)
   try {
     removeWorktree(originalBasePath_, milestoneId, {
-      branch: null as unknown as string,
+      branch: milestoneBranch,
       deleteBranch: false,
     });
   } catch (err) {

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

@@ -165,6 +165,7 @@ import {
   reconcileMergeState,
 } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
+import { getErrorMessage } from "./error-utils.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent, type JournalEntry } from "./journal.js";
 import {
@@ -272,6 +273,53 @@ function restoreProjectRootEnv(): void {
   s.projectRootEnvCaptured = false;
 }
 
+function captureMilestoneLockEnv(milestoneId: string | null): void {
+  if (!s.milestoneLockEnvCaptured) {
+    s.hadMilestoneLockEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_MILESTONE_LOCK");
+    s.previousMilestoneLockEnv = process.env.GSD_MILESTONE_LOCK ?? null;
+    s.milestoneLockEnvCaptured = true;
+  }
+
+  if (milestoneId) {
+    process.env.GSD_MILESTONE_LOCK = milestoneId;
+  } else {
+    delete process.env.GSD_MILESTONE_LOCK;
+  }
+}
+
+function restoreMilestoneLockEnv(): void {
+  if (!s.milestoneLockEnvCaptured) return;
+
+  if (s.hadMilestoneLockEnv && s.previousMilestoneLockEnv !== null) {
+    process.env.GSD_MILESTONE_LOCK = s.previousMilestoneLockEnv;
+  } else {
+    delete process.env.GSD_MILESTONE_LOCK;
+  }
+
+  s.previousMilestoneLockEnv = null;
+  s.hadMilestoneLockEnv = false;
+  s.milestoneLockEnvCaptured = false;
+}
+
+export function startAutoDetached(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  base: string,
+  verboseMode: boolean,
+  options?: {
+    step?: boolean;
+    interrupted?: InterruptedSessionAssessment;
+    milestoneLock?: string | null;
+  },
+): void {
+  void startAuto(ctx, pi, base, verboseMode, options).catch((err) => {
+    const message = getErrorMessage(err);
+    ctx.ui.notify(`Auto-start failed: ${message}`, "error");
+    logWarning("engine", `auto start error: ${message}`, { file: "auto.ts" });
+    debugLog("auto-start-failed", { error: message });
+  });
+}
+
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
   if (prefs?.isolation === "worktree") return true;
@@ -549,11 +597,13 @@ function buildSnapshotOpts(
   _unitType: string,
   _unitId: string,
 ): {
+  autoSessionKey?: string;
   continueHereFired?: boolean;
   promptCharCount?: number;
   baselineCharCount?: number;
 } & Record<string, unknown> {
   return {
+    ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
     promptCharCount: s.lastPromptCharCount,
     baselineCharCount: s.lastBaselineCharCount,
     ...(s.currentUnitRouting ?? {}),
@@ -574,6 +624,7 @@ function handleLostSessionLock(
   s.paused = false;
   clearUnitTimeout();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
   deregisterSigtermHandler();
   clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
   const base = lockBase();
@@ -610,6 +661,7 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.active = false;
   clearUnitTimeout();
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
 
   // Clear crash lock and release session lock so the next `/gsd next` does
   // not see a stale lock with the current PID and treat it as a "remote"
@@ -880,6 +932,7 @@ export async function stopAuto(
     ctx?.ui.setWidget("gsd-progress", undefined);
     ctx?.ui.setFooter(undefined);
     restoreProjectRootEnv();
+    restoreMilestoneLockEnv();
 
     // Reset all session state in one call
     s.reset();
@@ -933,6 +986,7 @@ export async function pauseAuto(
       activeEngineId: s.activeEngineId,
       activeRunDir: s.activeRunDir,
       autoStartTime: s.autoStartTime,
+      milestoneLock: s.sessionMilestoneLock ?? undefined,
     };
     const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
     mkdirSync(runtimeDir, { recursive: true });
@@ -971,6 +1025,7 @@ export async function pauseAuto(
   s.active = false;
   s.paused = true;
   restoreProjectRootEnv();
+  restoreMilestoneLockEnv();
   s.pendingVerificationRetry = null;
   s.verificationRetryCount.clear();
   ctx?.ui.setStatus("gsd-auto", "paused");
@@ -1154,6 +1209,7 @@ export async function startAuto(
   options?: {
     step?: boolean;
     interrupted?: InterruptedSessionAssessment;
+    milestoneLock?: string | null;
   },
 ): Promise<void> {
   if (s.active) {
@@ -1163,6 +1219,12 @@ export async function startAuto(
 
   const requestedStepMode = options?.step ?? false;
   const interruptedAssessment = options?.interrupted ?? null;
+  if (options?.milestoneLock !== undefined) {
+    s.sessionMilestoneLock = options.milestoneLock ?? null;
+  }
+  if (s.sessionMilestoneLock) {
+    captureMilestoneLockEnv(s.sessionMilestoneLock);
+  }
 
   // Escape stale worktree cwd from a previous milestone (#608).
   base = escapeStaleWorktree(base);
@@ -1194,6 +1256,7 @@ export async function startAuto(
         s.originalBasePath = meta.originalBasePath || base;
         s.stepMode = meta.stepMode ?? requestedStepMode;
         s.autoStartTime = meta.autoStartTime || Date.now();
+        s.sessionMilestoneLock = meta.milestoneLock ?? null;
         s.paused = true;
         try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); }
         ctx.ui.notify(
@@ -1228,6 +1291,7 @@ export async function startAuto(
             s.pausedUnitType = meta.unitType ?? null;
             s.pausedUnitId = meta.unitId ?? null;
             s.autoStartTime = meta.autoStartTime || Date.now();
+            s.sessionMilestoneLock = meta.milestoneLock ?? null;
             s.paused = true;
             try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); }
             ctx.ui.notify(
@@ -1247,6 +1311,10 @@ export async function startAuto(
     if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now();
   }
 
+  if (s.sessionMilestoneLock) {
+    captureMilestoneLockEnv(s.sessionMilestoneLock);
+  }
+
   if (!s.paused) {
     s.stepMode = requestedStepMode;
   }

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

@@ -121,6 +121,8 @@ export function registerHooks(pi: ExtensionAPI): void {
       return { cancel: true };
     }
     const basePath = process.cwd();
+    const { ensureDbOpen } = await import("./dynamic-tools.js");
+    await ensureDbOpen();
     const state = await deriveState(basePath);
     if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return;
     if (state.phase !== "executing") return;

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

@@ -1,79 +1,101 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { Key } from "@gsd/pi-tui";
 
 import { GSDDashboardOverlay } from "../dashboard-overlay.js";
 import { GSDNotificationOverlay } from "../notification-overlay.js";
 import { ParallelMonitorOverlay } from "../parallel-monitor-overlay.js";
+import { GSD_SHORTCUTS } from "../shortcut-defs.js";
 import { projectRoot } from "../commands/context.js";
 import { shortcutDesc } from "../../shared/mod.js";
 
 export function registerShortcuts(pi: ExtensionAPI): void {
-  pi.registerShortcut(Key.ctrlAlt("g"), {
-    description: shortcutDesc("Open GSD dashboard", "/gsd status"),
-    handler: async (ctx) => {
-      const basePath = projectRoot();
-      if (!existsSync(join(basePath, ".gsd"))) {
-        ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
-        return;
-      }
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
+  const overlayOptions = {
+    width: "90%",
+    minWidth: 80,
+    maxHeight: "92%",
+    anchor: "center",
+  } as const;
+
+  const openDashboardOverlay = async (ctx: ExtensionContext) => {
+    const basePath = projectRoot();
+    if (!existsSync(join(basePath, ".gsd"))) {
+      ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
+      return;
+    }
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)),
+      {
+        overlay: true,
+        overlayOptions,
+      },
+    );
+  };
+
+  const openNotificationsOverlay = async (ctx: ExtensionContext) => {
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
+      {
+        overlay: true,
+        overlayOptions: {
+          width: "80%",
+          minWidth: 60,
+          maxHeight: "88%",
+          anchor: "center",
+          backdrop: true,
         },
-      );
-    },
+      },
+    );
+  };
+
+  const openParallelOverlay = async (ctx: ExtensionContext) => {
+    const basePath = projectRoot();
+    const parallelDir = join(basePath, ".gsd", "parallel");
+    if (!existsSync(parallelDir)) {
+      ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
+      return;
+    }
+    await ctx.ui.custom<boolean>(
+      (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true), basePath),
+      {
+        overlay: true,
+        overlayOptions,
+      },
+    );
+  };
+
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.dashboard.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.dashboard.action, GSD_SHORTCUTS.dashboard.command),
+    handler: openDashboardOverlay,
   });
 
-  pi.registerShortcut(Key.ctrlAlt("n"), {
-    description: shortcutDesc("Open notification history", "/gsd notifications"),
-    handler: async (ctx) => {
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "80%",
-            minWidth: 60,
-            maxHeight: "88%",
-            anchor: "center",
-            backdrop: true,
-          },
-        },
-      );
-    },
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.dashboard.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.dashboard.action} (fallback)`, GSD_SHORTCUTS.dashboard.command),
+    handler: openDashboardOverlay,
   });
 
-  pi.registerShortcut(Key.ctrlAlt("p"), {
-    description: shortcutDesc("Open parallel worker monitor", "/gsd parallel watch"),
-    handler: async (ctx) => {
-      const basePath = projectRoot();
-      const parallelDir = join(basePath, ".gsd", "parallel");
-      if (!existsSync(parallelDir)) {
-        ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
-        return;
-      }
-      await ctx.ui.custom<boolean>(
-        (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true)),
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            minWidth: 80,
-            maxHeight: "92%",
-            anchor: "center",
-          },
-        },
-      );
-    },
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.notifications.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.notifications.action, GSD_SHORTCUTS.notifications.command),
+    handler: openNotificationsOverlay,
+  });
+
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.notifications.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.notifications.action} (fallback)`, GSD_SHORTCUTS.notifications.command),
+    handler: openNotificationsOverlay,
+  });
+
+  pi.registerShortcut(Key.ctrlAlt(GSD_SHORTCUTS.parallel.key), {
+    description: shortcutDesc(GSD_SHORTCUTS.parallel.action, GSD_SHORTCUTS.parallel.command),
+    handler: openParallelOverlay,
+  });
+
+  // Fallback for terminals where Ctrl+Alt letter chords are not forwarded reliably.
+  pi.registerShortcut(Key.ctrlShift(GSD_SHORTCUTS.parallel.key), {
+    description: shortcutDesc(`${GSD_SHORTCUTS.parallel.action} (fallback)`, GSD_SHORTCUTS.parallel.command),
+    handler: openParallelOverlay,
   });
 }