@opengsd/gsd-pi 1.0.2-dev.867e002 → 1.0.2-dev.aed3486

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

@@ -27,6 +27,32 @@ import { initCmuxEventListeners } from "../../cmux/index.js";
 
 export { writeCrashLog } from "./crash-log.js";
 
+// Pipe-closed storm guard. #99/#101 stopped EPIPE from flooding ~/.gsd/crash,
+// but a persistently-broken output pipe whose `destroyed`/`writableEnded` flags
+// never flip is still swallowed on every write — a tight, progress-free CPU
+// spin. If the pipe-closed error fires in a tight loop the pipe is gone for
+// good; exit cleanly instead.
+const EPIPE_STORM_THRESHOLD = 100;
+const EPIPE_STORM_WINDOW_MS = 10_000;
+let epipeCount = 0;
+let epipeWindowStart = 0;
+
+/** Write to stderr without ever re-throwing — stderr can EPIPE too, which would
+ *  re-enter this handler and re-loop. */
+function safeStderr(msg: string): void {
+  try {
+    process.stderr.write(msg);
+  } catch { /* stderr is also broken; nothing we can do */ }
+}
+
+/** A peer closing the read end of a pipe mid-write surfaces differently per
+ *  platform: POSIX throws `EPIPE`; Windows throws `Error: write EOF` (or
+ *  `read EOF`) with no `code` set, from node:internal/stream_base_commons.
+ *  Both are the same logical condition and must be treated as recoverable —
+ *  otherwise the Windows EOF variant escapes to the uncaught-exception path
+ *  and crashes auto-mode workers mid-iteration (#181). ECONNRESET is NOT
+ *  included here: it commonly comes from network sockets (#182 follow-up) and
+ *  is a real error that should surface rather than be silently swallowed. */
 function isPipeClosedError(err: Error): boolean {
   const errno = (err as NodeJS.ErrnoException).code;
   if (errno === "EPIPE") return true;
@@ -36,7 +62,7 @@ function isPipeClosedError(err: Error): boolean {
 
 export function handleRecoverableExtensionProcessError(err: Error): boolean {
   if (err.message.includes("ProcessTransport is not ready for writing")) {
-    process.stderr.write(`[gsd] swallowed dead transport control write: ${err.message}\n`);
+    safeStderr(`[gsd] swallowed dead transport control write: ${err.message}\n`);
     return true;
   }
   if (isPipeClosedError(err)) {
@@ -46,7 +72,18 @@ export function handleRecoverableExtensionProcessError(err: Error): boolean {
     if (stdoutGone) {
       process.exit(0);
     }
-    process.stderr.write(
+    const now = Date.now();
+    if (now - epipeWindowStart > EPIPE_STORM_WINDOW_MS) {
+      epipeWindowStart = now;
+      epipeCount = 0;
+    }
+    if (++epipeCount > EPIPE_STORM_THRESHOLD) {
+      safeStderr(
+        `[gsd] ${tag} storm (${epipeCount} within ${EPIPE_STORM_WINDOW_MS}ms) — output pipe is gone; exiting.\n`,
+      );
+      process.exit(0);
+    }
+    safeStderr(
       `[gsd] swallowed ${tag} (syscall=${(err as NodeJS.ErrnoException).syscall ?? "?"})\n`,
     );
     return true;
@@ -54,18 +91,18 @@ export function handleRecoverableExtensionProcessError(err: Error): boolean {
   if ((err as NodeJS.ErrnoException).code === "EIO") {
     const syscall = (err as NodeJS.ErrnoException).syscall;
     if (syscall === "read") {
-      process.stderr.write(`[gsd] EIO: ${err.message}\n`);
+      safeStderr(`[gsd] EIO: ${err.message}\n`);
       return true;
     }
   }
   if ((err as NodeJS.ErrnoException).code === "ENOENT") {
     const syscall = (err as NodeJS.ErrnoException).syscall;
     if (syscall?.startsWith("spawn")) {
-      process.stderr.write(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
+      safeStderr(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
       return true;
     }
     if (syscall === "uv_cwd") {
-      process.stderr.write(`[gsd] ENOENT (${syscall}): ${err.message}\n`);
+      safeStderr(`[gsd] ENOENT (${syscall}): ${err.message}\n`);
       return true;
     }
   }

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

@@ -33,6 +33,7 @@ import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 import { resolveSkillManifest } from "../skill-manifest.js";
+import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.js";
 import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 
@@ -357,8 +358,7 @@ export function scopeGsdWorkflowToolsForDispatch(
     ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames)
     : buildMinimalGsdWorkflowToolSet(current, registeredToolNames);
   const toolsChanged = !(scoped.length === current.length && scoped.every((name, index) => name === current[index]));
-  const skillManifest = resolveSkillManifest(unitType);
-  const canScopeSkills = skillManifest !== null && pi.getVisibleSkills && pi.setVisibleSkills;
+  const canScopeSkills = unitHasSkillManifest(unitType) && pi.getVisibleSkills && pi.setVisibleSkills;
   if (!toolsChanged && !canScopeSkills) {
     return null;
   }
@@ -366,8 +366,8 @@ export function scopeGsdWorkflowToolsForDispatch(
     pi.setActiveTools(scoped);
   }
   const visibleSkills = canScopeSkills ? pi.getVisibleSkills!() : undefined;
-  if (canScopeSkills) {
-    pi.setVisibleSkills!(skillManifest);
+  if (canScopeSkills && pi.setVisibleSkills) {
+    applyUnitSkillVisibility({ setVisibleSkills: pi.setVisibleSkills }, unitType);
   }
   return {
     tools: toolsChanged ? current : null,
@@ -615,9 +615,21 @@ export function registerHooks(
     // project MCP config that /gsd mcp init would write.
     await prepareWorkflowMcpForHookContext(ctx, beforeAgentBasePath);
 
+    let systemPrompt = event.systemPrompt;
+    const { appendDiscoveredSkillsFallback, hasSkillSnapshot, refreshCatalogForNewSkills } = await import("../skill-discovery.js");
+    if (hasSkillSnapshot()) {
+      const loadedSkills = await refreshCatalogForNewSkills({
+        reload: () => (ctx as ExtensionContext & { reload: () => Promise<void> }).reload(),
+        notify: (message, level) => ctx.ui.notify(message, level),
+      });
+      if (loadedSkills.length > 0) {
+        systemPrompt = appendDiscoveredSkillsFallback(ctx.getSystemPrompt(), loadedSkills);
+      }
+    }
+
     // GSD's own context injection (existing behavior — unchanged).
     const { buildBeforeAgentStartResult } = await import("./system-context.js");
-    const gsdResult = await buildBeforeAgentStartResult(event, ctx);
+    const gsdResult = await buildBeforeAgentStartResult({ ...event, systemPrompt }, ctx);
 
     // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
     // deriveState has its own ~100ms cache so this is cheap on repeat calls.
@@ -630,7 +642,7 @@ export function registerHooks(
 
     // 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;
+    let currentSystemPrompt = gsdResult?.systemPrompt ?? 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;

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -11,11 +11,9 @@ import { loadPrompt, getTemplatesDir } from "../prompt-loader.js";
 import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
-import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
-import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 import { deriveState } from "../state.js";
@@ -72,20 +70,6 @@ export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> =
   { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
 
-function buildBundledSkillsTable(): string {
-  const cwd = process.cwd();
-  const rows: string[] = [];
-  for (const { trigger, skill } of BUNDLED_SKILL_TRIGGERS) {
-    const resolution = resolveSkillReference(skill, cwd);
-    if (resolution.method === "unresolved") continue; // skill not installed — omit from prompt
-    rows.push(`| ${trigger} | \`${resolution.resolvedPath}\` |`);
-  }
-  if (rows.length === 0) {
-    return "*No bundled skills found. Install or sync skills to `~/.gsd/agent/skills/`, `~/.agents/skills/`, or `~/.claude/skills/`.*";
-  }
-  return `| Trigger | Skill to load |\n|---|---|\n${rows.join("\n")}`;
-}
-
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
     join(gsdHome(), "agent-instructions.md"),
@@ -110,7 +94,6 @@ export async function buildBeforeAgentStartResult(
 
   const stopContextTimer = debugTime("context-inject");
   const systemContent = loadPrompt("system", {
-    bundledSkillsTable: buildBundledSkillsTable(),
     templatesDir: getTemplatesDir(),
     shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
     shortcutShell: formatShortcut("Ctrl+Alt+B"),
@@ -141,7 +124,7 @@ export async function buildBeforeAgentStartResult(
   if (loadedPreferences) {
     const cwd = basePath;
     const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
-    preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions)}`;
+    preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
     if (report.warnings.length > 0) {
       ctx.ui.notify(
         `GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`,
@@ -201,14 +184,6 @@ export async function buildBeforeAgentStartResult(
     );
   }
 
-  let newSkillsBlock = "";
-  if (hasSkillSnapshot()) {
-    const newSkills = detectNewSkills();
-    if (newSkills.length > 0) {
-      newSkillsBlock = formatSkillsXml(newSkills);
-    }
-  }
-
   let codebaseBlock = "";
   try {
     const codebaseOptions = loadedPreferences?.preferences?.codebase
@@ -264,13 +239,13 @@ export async function buildBeforeAgentStartResult(
   // Keeping it out of `fullSystem` preserves provider prompt-cache stability
   // for the static system/tool prefix. The dynamic memory block rides the
   // volatile context message instead. (#5019)
-  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
+  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${worktreeBlock}${subagentModelBlock}`;
 
   stopContextTimer({
     systemPromptSize: fullSystem.length,
     injectionSize: injection?.length ?? forensicsInjection?.length ?? 0,
     hasPreferences: preferenceBlock.length > 0,
-    hasNewSkills: newSkillsBlock.length > 0,
+    hasNewSkills: false,
   });
 
   const contextMessage = buildContextMessage({ memoryBlock, injection, forensicsInjection });

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

@@ -205,7 +205,12 @@ export function getCloseoutManualResolveBlocker(basePath: string): string | null
     return `Unmerged paths remain in ${basePath}: ${conflictProbe.unmerged.slice(0, 5).join(", ")}`;
   }
 
-  const status = runGit(basePath, ["status", "--porcelain"]);
+  let status: string;
+  try {
+    status = runGit(basePath, ["status", "--porcelain"]);
+  } catch {
+    return `Could not inspect git status in ${basePath}.`;
+  }
   if (status) {
     return `Working tree still has uncommitted changes in ${basePath}. Commit, stash, or run /gsd closeout retry first.`;
   }

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

@@ -208,7 +208,15 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
 
   if (trimmed === "") {
     if (!(await guardRemoteSession(ctx, pi))) return true;
-    if (await hasUnresolvedCloseoutBlocker(ctx, projectRoot())) return true;
+    const basePath = projectRoot();
+    const { hasGsdBootstrapArtifacts } = await import("../../detection.js");
+    const { gsdRoot } = await import("../../paths.js");
+    if (!hasGsdBootstrapArtifacts(gsdRoot(basePath))) {
+      const { showSmartEntry } = await import("../../guided-flow.js");
+      await showSmartEntry(ctx, pi, basePath, { step: true });
+      return true;
+    }
+    if (await hasUnresolvedCloseoutBlocker(ctx, basePath)) return true;
     const { showGsdHome } = await import("../../gsd-command-home.js");
     await showGsdHome(ctx, pi, projectRoot());
     return true;

package/src/resources/extensions/gsd/commands-usage.ts

@@ -4,10 +4,12 @@
  * Shows current LLM context window usage and session token totals.
  */
 
-import type { ExtensionCommandContext, ContextUsage, SessionEntry } from "@gsd/pi-coding-agent";
+import type { ExtensionCommandContext, ContextUsage, SessionEntry, Theme } from "@gsd/pi-coding-agent";
+import { Key, matchesKey } from "@gsd/pi-tui";
 
 import { formatCost, formatPercent, formatTokenCount } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 
 export interface SessionTokenTotals {
   input: number;
@@ -160,6 +162,101 @@ export function formatUsageReport(options: {
   return lines.join("\n");
 }
 
+async function showUsageDialog(
+  ctx: ExtensionCommandContext,
+  reportText: string,
+): Promise<boolean | undefined> {
+  return ctx.ui.custom<boolean>((tui, theme: Theme, _kb, done) => {
+    let cachedLines: string[] | undefined;
+    let cachedWidth: number | undefined;
+    let cachedRows: number | undefined;
+    let cachedScrollOffset: number | undefined;
+    let scrollOffset = 0;
+    let lastMaxScroll = 0;
+    let lastVisibleRows = 1;
+
+    function render(width: number): string[] {
+      const terminalRows = process.stdout.rows || 0;
+      if (
+        cachedLines &&
+        cachedWidth === width &&
+        cachedRows === terminalRows &&
+        cachedScrollOffset === scrollOffset
+      ) {
+        return cachedLines;
+      }
+
+      const contentWidth = Math.max(1, width - 4);
+      const body = reportText.split("\n");
+      if (body[0] === "Context Usage") body.shift();
+      while (body[0] === "") body.shift();
+      const maxOverlayRows = terminalRows > 0 ? Math.max(5, Math.floor(terminalRows * 0.8)) : 24;
+      const frameRows = 4;
+      const visibleRows = Math.max(1, maxOverlayRows - frameRows);
+      const maxScroll = Math.max(0, body.length - visibleRows);
+      scrollOffset = Math.min(Math.max(scrollOffset, 0), maxScroll);
+      lastMaxScroll = maxScroll;
+      lastVisibleRows = visibleRows;
+      const visible = body.slice(scrollOffset, scrollOffset + visibleRows);
+      const scrollable = body.length > visibleRows;
+
+      cachedLines = renderDialogFrame(theme, "Context Usage", visible, width, {
+        footer: renderKeyHints(theme, scrollable ? ["↑↓ scroll", "any key close"] : ["any key close"], contentWidth),
+        scroll: { offset: scrollOffset, visibleRows, totalRows: body.length },
+      });
+      cachedWidth = width;
+      cachedRows = terminalRows;
+      cachedScrollOffset = scrollOffset;
+      return cachedLines;
+    }
+
+    function scrollBy(delta: number): boolean {
+      if (lastMaxScroll <= 0) return false;
+      const nextOffset = Math.min(Math.max(scrollOffset + delta, 0), lastMaxScroll);
+      if (nextOffset !== scrollOffset) {
+        scrollOffset = nextOffset;
+        cachedLines = undefined;
+        cachedScrollOffset = undefined;
+        tui.requestRender();
+      }
+      return true;
+    }
+
+    return {
+      render,
+      invalidate: () => {
+        cachedLines = undefined;
+        cachedWidth = undefined;
+        cachedRows = undefined;
+        cachedScrollOffset = undefined;
+      },
+      handleInput: (data: string) => {
+        if (matchesKey(data, Key.down) || matchesKey(data, "j")) {
+          if (scrollBy(1)) return;
+        }
+        if (matchesKey(data, Key.up) || matchesKey(data, "k")) {
+          if (scrollBy(-1)) return;
+        }
+        if (matchesKey(data, Key.pageDown)) {
+          if (scrollBy(lastVisibleRows)) return;
+        }
+        if (matchesKey(data, Key.pageUp)) {
+          if (scrollBy(-lastVisibleRows)) return;
+        }
+        done(true);
+      },
+    };
+  }, {
+    overlay: true,
+    overlayOptions: {
+      width: "70%",
+      minWidth: 64,
+      maxHeight: "80%",
+      anchor: "center",
+    },
+  });
+}
+
 export async function handleUsage(args: string, ctx: ExtensionCommandContext): Promise<void> {
   const contextUsage = ctx.getContextUsage?.();
   const sessionTotals = scanSessionTokenTotals(ctx.sessionManager.getEntries());
@@ -187,8 +284,16 @@ export async function handleUsage(args: string, ctx: ExtensionCommandContext): P
     return;
   }
 
-  ctx.ui.notify(
-    formatUsageReport({ modelLabel, contextUsage, sessionTotals }),
-    "info",
-  );
+  const reportText = formatUsageReport({ modelLabel, contextUsage, sessionTotals });
+
+  if (ctx.hasUI) {
+    try {
+      const result = await showUsageDialog(ctx, reportText);
+      if (result !== undefined) return;
+    } catch {
+      // Fall back to text notify below when custom overlays are unavailable.
+    }
+  }
+
+  ctx.ui.notify(reportText, "info");
 }

package/src/resources/extensions/gsd/config-overlay.ts

@@ -10,6 +10,7 @@
 import type { Theme } from "@gsd/pi-coding-agent";
 import { matchesKey, Key, truncateToWidth } from "@gsd/pi-tui";
 
+import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 import {
   loadEffectiveGSDPreferences,
   loadGlobalGSDPreferences,
@@ -231,6 +232,7 @@ export class GSDConfigOverlay {
   private onClose: () => void;
   private sections: ConfigSection[];
   private cachedLines?: string[];
+  private cachedWidth?: number;
   private scrollOffset = 0;
   private disposed = false;
 
@@ -247,6 +249,7 @@ export class GSDConfigOverlay {
 
   invalidate(): void {
     this.cachedLines = undefined;
+    this.cachedWidth = undefined;
   }
 
   dispose(): void {
@@ -286,16 +289,13 @@ export class GSDConfigOverlay {
   }
 
   render(width: number): string[] {
-    if (this.cachedLines) return this.cachedLines;
+    if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
 
     const t = this.theme;
-    const w = Math.max(width, 50);
+    const w = Math.max(1, width);
+    const contentWidth = Math.max(1, w - 4);
     const allLines: string[] = [];
 
-    // Header
-    allLines.push(t.bold(t.fg("accent", " GSD Configuration ")));
-    allLines.push(t.fg("muted", "\u2500".repeat(w)));
-
     // Find max label width for alignment
     let maxLabel = 0;
     for (const section of this.sections) {
@@ -306,26 +306,29 @@ export class GSDConfigOverlay {
     const labelPad = Math.min(maxLabel + 2, 24);
 
     for (const section of this.sections) {
-      allLines.push("");
+      if (allLines.length > 0) allLines.push("");
       allLines.push(t.bold(t.fg("accent", `  ${section.title}`)));
 
       for (const row of section.rows) {
         const label = t.fg("muted", `    ${row.label.padEnd(labelPad)}`);
         const value = row.accent ? t.bold(row.value) : row.value;
-        allLines.push(truncateToWidth(`${label}${value}`, w));
+        allLines.push(truncateToWidth(`${label}${value}`, contentWidth));
       }
     }
 
-    allLines.push("");
-    allLines.push(t.fg("muted", `  ${"\u2500".repeat(w - 4)}`));
-    allLines.push(t.fg("muted", "  esc/q close  \u2502  \u2191\u2193/jk scroll  \u2502  /gsd prefs to edit"));
-
     // Apply scroll
-    const maxScroll = Math.max(0, allLines.length - 20);
+    const terminalRows = process.stdout.rows || 32;
+    const maxBodyRows = Math.max(1, Math.min(allLines.length, terminalRows - 12));
+    const maxScroll = Math.max(0, allLines.length - maxBodyRows);
     this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
-    const visible = allLines.slice(this.scrollOffset);
+    const visible = allLines.slice(this.scrollOffset, this.scrollOffset + maxBodyRows);
+    const footer = renderKeyHints(t, ["esc/q close", "\u2191\u2193/jk scroll", "/gsd prefs to edit"], contentWidth);
 
-    this.cachedLines = visible;
-    return visible;
+    this.cachedLines = renderDialogFrame(t, "GSD Configuration", visible, w, {
+      footer,
+      scroll: { offset: this.scrollOffset, visibleRows: maxBodyRows, totalRows: allLines.length },
+    });
+    this.cachedWidth = width;
+    return this.cachedLines;
   }
 }

package/src/resources/extensions/gsd/context-overlay.ts

@@ -3,11 +3,11 @@
  */
 
 import type { Theme, ThemeColor } from "@gsd/pi-coding-agent";
-import { matchesKey, Key, truncateToWidth, visibleWidth } from "@gsd/pi-tui";
+import { matchesKey, Key, truncateToWidth } from "@gsd/pi-tui";
 
 import type { ContextBreakdownReport, ContextSectionBreakdown } from "./commands-context.js";
 import { formatTokenCount } from "./metrics.js";
-import { renderProgressBar, rightAlign } from "./tui/render-kit.js";
+import { renderDialogFrame, renderKeyHints, renderProgressBar, rightAlign } from "./tui/render-kit.js";
 
 const SECTION_COLORS: ThemeColor[] = ["accent", "success", "warning", "borderAccent", "text"];
 
@@ -70,6 +70,7 @@ export class GSDContextOverlay {
   private onClose: () => void;
   private report: ContextBreakdownReport;
   private cachedLines?: string[];
+  private cachedWidth?: number;
   private scrollOffset = 0;
   private disposed = false;
 
@@ -87,6 +88,7 @@ export class GSDContextOverlay {
 
   invalidate(): void {
     this.cachedLines = undefined;
+    this.cachedWidth = undefined;
   }
 
   dispose(): void {
@@ -125,24 +127,22 @@ export class GSDContextOverlay {
   }
 
   render(width: number): string[] {
-    if (this.cachedLines) return this.cachedLines;
+    if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
 
     const theme = this.theme;
-    const w = Math.max(width, 60);
+    const w = Math.max(1, width);
+    const contentWidth = Math.max(1, w - 4);
     const totals = getContextChartTotals(this.report);
     const chartTotal = Math.max(totals.inContext, totals.estimated, 1);
     const lines: string[] = [];
 
-    lines.push(theme.bold(theme.fg("accent", " Context Breakdown ")));
-    lines.push(theme.fg("muted", "─".repeat(w)));
-
     if (this.report.modelLabel) {
-      lines.push(rightAlign(theme.fg("muted", "Model"), theme.fg("text", this.report.modelLabel), w));
+      lines.push(rightAlign(theme.fg("muted", "Model"), theme.fg("text", this.report.modelLabel), contentWidth));
     }
 
     lines.push("");
     if (totals.window != null) {
-      const usageBarWidth = Math.max(20, w - 28);
+      const usageBarWidth = Math.max(8, contentWidth - 28);
       const usageBar = renderProgressBar(theme, totals.inContext, totals.window, usageBarWidth, {
         filledColor: totals.inContext / totals.window > 0.85 ? "warning" : "accent",
       });
@@ -151,7 +151,7 @@ export class GSDContextOverlay {
       lines.push(`  ${theme.fg("muted", "Estimated")} ${theme.fg("text", formatTokenCount(chartTotal))}`);
     }
 
-    const splitWidth = Math.max(16, Math.floor((w - 8) / 2));
+    const splitWidth = Math.max(8, Math.floor((contentWidth - 8) / 2));
     const systemBar = renderProgressBar(theme, totals.systemTokens, chartTotal, splitWidth, { filledColor: "accent" });
     const convBar = renderProgressBar(theme, totals.conversationTokens, chartTotal, splitWidth, { filledColor: "success" });
     lines.push("");
@@ -160,11 +160,11 @@ export class GSDContextOverlay {
 
     lines.push("");
     lines.push(theme.bold(theme.fg("accent", "  System prompt")));
-    lines.push(...renderSectionBars(theme, this.report.systemSections, chartTotal, w, 22));
+    lines.push(...renderSectionBars(theme, this.report.systemSections, chartTotal, contentWidth, 22));
 
     lines.push("");
     lines.push(theme.bold(theme.fg("accent", "  Conversation")));
-    lines.push(...renderSectionBars(theme, this.report.conversationSections, chartTotal, w, 22));
+    lines.push(...renderSectionBars(theme, this.report.conversationSections, chartTotal, contentWidth, 22));
 
     lines.push("");
     lines.push(theme.bold(theme.fg("accent", "  Skills")));
@@ -172,7 +172,7 @@ export class GSDContextOverlay {
     if (skills.available.length > 0) {
       lines.push(`    ${theme.fg("muted", "Available")} ${theme.fg("text", `${skills.available.length}`)}`);
       const preview = skills.available.slice(0, 8).join(", ");
-      lines.push(truncateToWidth(`      ${preview}${skills.available.length > 8 ? "…" : ""}`, w));
+      lines.push(truncateToWidth(`      ${preview}${skills.available.length > 8 ? "…" : ""}`, contentWidth));
     } else {
       lines.push(theme.fg("dim", "    none in prompt"));
     }
@@ -187,13 +187,18 @@ export class GSDContextOverlay {
     lines.push(theme.bold(theme.fg("accent", "  Agents")));
     lines.push(`    ${theme.fg("muted", "Subagent spawns")} ${theme.fg("text", String(this.report.subagentSpawns))}`);
 
-    lines.push("");
-    lines.push(theme.fg("muted", `  ${"─".repeat(Math.max(0, w - 4))}`));
-    lines.push(theme.fg("muted", "  esc/q close  │  ↑↓ scroll  │  /gsd context --open for browser chart"));
-
-    const maxScroll = Math.max(0, lines.length - 24);
+    const terminalRows = process.stdout.rows || 32;
+    const maxBodyRows = Math.max(1, Math.min(lines.length, terminalRows - 12));
+    const maxScroll = Math.max(0, lines.length - maxBodyRows);
     this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
-    this.cachedLines = lines.slice(this.scrollOffset);
+    const visible = lines.slice(this.scrollOffset, this.scrollOffset + maxBodyRows);
+    const footer = renderKeyHints(theme, ["esc/q close", "↑↓ scroll", "/gsd context --open"], contentWidth);
+
+    this.cachedLines = renderDialogFrame(theme, "Context Breakdown", visible, w, {
+      footer,
+      scroll: { offset: this.scrollOffset, visibleRows: maxBodyRows, totalRows: lines.length },
+    });
+    this.cachedWidth = width;
     return this.cachedLines;
   }
 }