gsd-pi 2.64.0-dev.9c14bd0 → 2.64.0-dev.b3ee078

package/packages/pi-tui/src/components/loader.ts

@@ -2,13 +2,16 @@ import type { TUI } from "../tui.js";
 import { Text } from "./text.js";
 
 /**
- * Loader component that updates every 80ms with spinning animation
+ * Loader component that updates every 80ms with spinning animation.
+ * Frame rotation is isolated from message text to avoid invalidating
+ * Text's render cache (wrapTextWithAnsi, visibleWidth) on every tick.
  */
 export class Loader extends Text {
 	private frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	private currentFrame = 0;
 	private intervalId: NodeJS.Timeout | null = null;
 	private ui: TUI | null = null;
+	private _lastMessage: string = "";
 
 	constructor(
 		ui: TUI,
@@ -22,18 +25,38 @@ export class Loader extends Text {
 	}
 
 	render(width: number): string[] {
-		return ["", ...super.render(width)];
+		// Only update Text content when message actually changes —
+		// frame rotation is prepended below without touching the cache
+		if (this.message !== this._lastMessage) {
+			this.setText(this.messageColorFn(this.message));
+			this._lastMessage = this.message;
+		}
+		const messageLines = super.render(width);
+		// Shallow copy so we don't mutate cachedLines from Text
+		const result = ["", ...messageLines];
+		// Prepend spinner frame to first content line
+		if (result.length > 1) {
+			const frame = this.frames[this.currentFrame];
+			result[1] = this.spinnerColorFn(frame) + " " + result[1];
+		}
+		return result;
 	}
 
 	start() {
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
 		}
-		this.updateDisplay();
+		this.currentFrame = 0;
 		this.intervalId = setInterval(() => {
 			this.currentFrame = (this.currentFrame + 1) % this.frames.length;
-			this.updateDisplay();
+			if (this.ui) {
+				this.ui.requestRender();
+			}
 		}, 80);
+		// Trigger initial render
+		if (this.ui) {
+			this.ui.requestRender();
+		}
 	}
 
 	stop() {
@@ -50,12 +73,6 @@ export class Loader extends Text {
 
 	setMessage(message: string) {
 		this.message = message;
-		this.updateDisplay();
-	}
-
-	private updateDisplay() {
-		const frame = this.frames[this.currentFrame];
-		this.setText(`${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`);
 		if (this.ui) {
 			this.ui.requestRender();
 		}

package/packages/pi-tui/src/components/text.ts

@@ -23,6 +23,7 @@ export class Text implements Component {
 	}
 
 	setText(text: string): void {
+		if (this.text === text) return;
 		this.text = text;
 		this.cachedText = undefined;
 		this.cachedWidth = undefined;

package/packages/pi-tui/src/overlay-layout.ts

@@ -6,7 +6,7 @@
  */
 
 import type { OverlayAnchor, OverlayOptions, SizeValue } from "./tui.js";
-import { extractSegments, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth } from "./utils.js";
+import { applyBackgroundToLine, extractSegments, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth } from "./utils.js";
 import { isImageLine } from "./terminal-image.js";
 import { CURSOR_MARKER } from "./tui.js";
 
@@ -324,6 +324,19 @@ export function compositeOverlays(
 
 	const viewportStart = Math.max(0, workingHeight - termHeight);
 
+	// Apply backdrop dimming if any visible overlay requests it.
+	// Uses dim + dark gray background (256-color 233) so the overlay pops visually.
+	const hasBackdrop = visibleEntries.some((e) => e.options?.backdrop);
+	if (hasBackdrop) {
+		const dimFn = (text: string) =>
+			`\x1b[2m\x1b[38;5;242m\x1b[48;5;233m${text}\x1b[49m\x1b[39m\x1b[22m`;
+		for (let i = viewportStart; i < result.length; i++) {
+			if (!isImageLine(result[i]) && result[i].length > 0) {
+				result[i] = applyBackgroundToLine(result[i], termWidth, dimFn);
+			}
+		}
+	}
+
 	// Composite each overlay
 	for (const { overlayLines, row, col, w } of rendered) {
 		for (let i = 0; i < overlayLines.length; i++) {

package/packages/pi-tui/src/tui.ts

@@ -141,6 +141,8 @@ export interface OverlayOptions {
 	visible?: (termWidth: number, termHeight: number) => boolean;
 	/** If true, don't capture keyboard focus when shown */
 	nonCapturing?: boolean;
+	/** If true, dim the background behind the overlay */
+	backdrop?: boolean;
 }
 
 /**
@@ -166,20 +168,33 @@ export interface OverlayHandle {
  */
 export class Container implements Component {
 	children: Component[] = [];
+	private _prevRender: string[] | null = null;
 
 	addChild(component: Component): void {
 		this.children.push(component);
+		this._prevRender = null;
 	}
 
 	removeChild(component: Component): void {
 		const index = this.children.indexOf(component);
 		if (index !== -1) {
+			const child = this.children[index];
 			this.children.splice(index, 1);
+			if ('dispose' in child && typeof (child as any).dispose === 'function') {
+				(child as any).dispose();
+			}
+			this._prevRender = null;
 		}
 	}
 
 	clear(): void {
+		for (const child of this.children) {
+			if ('dispose' in child && typeof (child as any).dispose === 'function') {
+				(child as any).dispose();
+			}
+		}
 		this.children = [];
+		this._prevRender = null;
 	}
 
 	invalidate(): void {
@@ -194,6 +209,17 @@ export class Container implements Component {
 			const rendered = child.render(width);
 			for (let i = 0; i < rendered.length; i++) lines.push(rendered[i]);
 		}
+		// Return stable reference if output unchanged — allows doRender()
+		// to skip ALL post-processing (isImageLine, applyLineResets, diffs)
+		const prev = this._prevRender;
+		if (prev && prev.length === lines.length) {
+			let same = true;
+			for (let i = 0; i < lines.length; i++) {
+				if (lines[i] !== prev[i]) { same = false; break; }
+			}
+			if (same) return prev;
+		}
+		this._prevRender = lines;
 		return lines;
 	}
 }
@@ -222,6 +248,7 @@ export class TUI extends Container {
 	private previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
 	private fullRedrawCount = 0;
 	private stopped = false;
+	private _lastRenderedComponents: string[] | null = null;
 
 	// Overlay stack for modal components rendered on top of base content
 	private focusOrderCounter = 0;
@@ -599,6 +626,13 @@ export class TUI extends Container {
 		// Render all components to get new lines
 		let newLines = this.render(width);
 
+		// Skip ALL post-processing if component output is unchanged.
+		// Container.render() returns the same array reference when stable.
+		if (newLines === this._lastRenderedComponents && this.overlayStack.length === 0) {
+			return;
+		}
+		this._lastRenderedComponents = newLines;
+
 		// Composite overlays into the rendered lines (before differential compare)
 		if (this.overlayStack.length > 0) {
 			newLines = compositeOverlays(newLines, this.overlayStack, width, height, this.maxLinesRendered);

package/src/resources/extensions/bg-shell/bg-shell-lifecycle.ts

@@ -16,6 +16,7 @@ import {
 import {
 	processes,
 	pendingAlerts,
+	pushAlert,
 	cleanupAll,
 	cleanupSessionProcesses,
 	persistManifest,
@@ -37,19 +38,30 @@ export function registerBgShellLifecycle(pi: ExtensionAPI, state: BgShellSharedS
 		}
 	}
 
-	// Clean up on session shutdown
-	pi.on("session_shutdown", async () => {
-		cleanupAll();
-	});
-
 	// Register signal handlers to clean up bg processes on unexpected exit (fixes #428)
 	const signalCleanup = () => {
 		cleanupAll();
+		// Also kill bash-tool spawned children that bg-shell doesn't track
+		try {
+			const { listDescendants } = require("@gsd/native") as typeof import("@gsd/native");
+			const descendants = listDescendants(process.pid);
+			for (const childPid of descendants) {
+				try { process.kill(childPid, "SIGKILL"); } catch {}
+			}
+		} catch {}
 	};
 	process.on("SIGTERM", signalCleanup);
 	process.on("SIGINT", signalCleanup);
 	process.on("beforeExit", signalCleanup);
 
+	// Clean up on session shutdown — remove signal handlers to prevent accumulation
+	pi.on("session_shutdown", async () => {
+		process.off("SIGTERM", signalCleanup);
+		process.off("SIGINT", signalCleanup);
+		process.off("beforeExit", signalCleanup);
+		cleanupAll();
+	});
+
 	// ── Compaction Awareness: Survive Context Resets ───────────────
 
 	/** Build a compact state summary of all alive processes for context re-injection */
@@ -65,7 +77,7 @@ export function registerBgShellLifecycle(pi: ExtensionAPI, state: BgShellSharedS
 			return `  - id:${p.id} "${p.label}" [${p.processType}] status:${p.status} uptime:${formatUptime(Date.now() - p.startedAt)}${portInfo}${urlInfo}${errInfo}${groupInfo}`;
 		}).join("\n");
 
-		pendingAlerts.push(
+		pushAlert(null,
 			`${reason} ${alive.length} background process(es) are still running:\n${processSummaries}\nUse bg_shell digest/output/kill with these IDs.`
 		);
 	}
@@ -150,7 +162,7 @@ export function registerBgShellLifecycle(pi: ExtensionAPI, state: BgShellSharedS
 					`  - ${s.id}: ${s.label} (pid ${s.pid}, type: ${s.processType}${s.group ? `, group: ${s.group}` : ""})`
 				).join("\n");
 
-				pendingAlerts.push(
+				pushAlert(null,
 					`${surviving.length} background process(es) from previous session still running:\n${summary}\n  Note: These processes are outside bg_shell's control. Kill them manually if needed.`
 				);
 			}

package/src/resources/extensions/bg-shell/process-manager.ts

@@ -33,6 +33,8 @@ export const processes = new Map<string, BgProcess>();
 /** Pending alerts to inject into the next agent context */
 export let pendingAlerts: string[] = [];
 
+const MAX_PENDING_ALERTS = 50;
+
 /** Replace the pendingAlerts array (used by the extension entry point) */
 export function setPendingAlerts(alerts: string[]): void {
 	pendingAlerts = alerts;
@@ -58,8 +60,12 @@ export function addEvent(bg: BgProcess, event: Omit<ProcessEvent, "timestamp">):
 	}
 }
 
-export function pushAlert(bg: BgProcess, message: string): void {
-	pendingAlerts.push(`[bg:${bg.id} ${bg.label}] ${message}`);
+export function pushAlert(bg: BgProcess | null, message: string): void {
+	const prefix = bg ? `[bg:${bg.id} ${bg.label}] ` : "";
+	pendingAlerts.push(`${prefix}${message}`);
+	if (pendingAlerts.length > MAX_PENDING_ALERTS) {
+		pendingAlerts.splice(0, pendingAlerts.length - MAX_PENDING_ALERTS);
+	}
 }
 
 export function getInfo(p: BgProcess): BgProcessInfo {

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -804,27 +804,39 @@ export function registerDbTools(pi: ExtensionAPI): void {
         return m ? [m[1].trim(), m[2].trim()] : [s.trim(), ""];
       };
       const coerced = { ...params };
-      coerced.filesModified = (params.filesModified ?? []).map((f: any) => {
+      // Coerce simple string-array fields: LLMs sometimes pass a plain string
+      // instead of a single-element array (#3585).
+      const wrapArray = (v: any): any[] =>
+        v == null ? [] : Array.isArray(v) ? v : [v];
+      coerced.provides = wrapArray(params.provides);
+      coerced.keyFiles = wrapArray(params.keyFiles);
+      coerced.keyDecisions = wrapArray(params.keyDecisions);
+      coerced.patternsEstablished = wrapArray(params.patternsEstablished);
+      coerced.observabilitySurfaces = wrapArray(params.observabilitySurfaces);
+      coerced.requirementsSurfaced = wrapArray(params.requirementsSurfaced);
+      coerced.drillDownPaths = wrapArray(params.drillDownPaths);
+      coerced.affects = wrapArray(params.affects);
+      coerced.filesModified = wrapArray(params.filesModified).map((f: any) => {
         if (typeof f !== "string") return f;
         const [path, description] = splitPair(f);
         return { path, description };
       });
-      coerced.requires = (params.requires ?? []).map((r: any) => {
+      coerced.requires = wrapArray(params.requires).map((r: any) => {
         if (typeof r !== "string") return r;
         const [slice, provides] = splitPair(r);
         return { slice, provides };
       });
-      coerced.requirementsAdvanced = (params.requirementsAdvanced ?? []).map((r: any) => {
+      coerced.requirementsAdvanced = wrapArray(params.requirementsAdvanced).map((r: any) => {
         if (typeof r !== "string") return r;
         const [id, how] = splitPair(r);
         return { id, how };
       });
-      coerced.requirementsValidated = (params.requirementsValidated ?? []).map((r: any) => {
+      coerced.requirementsValidated = wrapArray(params.requirementsValidated).map((r: any) => {
         if (typeof r !== "string") return r;
         const [id, proof] = splitPair(r);
         return { id, proof };
       });
-      coerced.requirementsInvalidated = (params.requirementsInvalidated ?? []).map((r: any) => {
+      coerced.requirementsInvalidated = wrapArray(params.requirementsInvalidated).map((r: any) => {
         if (typeof r !== "string") return r;
         const [id, what] = splitPair(r);
         return { id, what };
@@ -884,14 +896,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
       deviations: Type.Optional(Type.String({ description: "Deviations from the slice plan, or 'None.'" })),
       knownLimitations: Type.Optional(Type.String({ description: "Known limitations or gaps, or 'None.'" })),
       followUps: Type.Optional(Type.String({ description: "Follow-up work discovered during execution, or 'None.'" })),
-      keyFiles: Type.Optional(Type.Array(Type.String(), { description: "Key files created or modified" })),
-      keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "Key decisions made during this slice" })),
-      patternsEstablished: Type.Optional(Type.Array(Type.String(), { description: "Patterns established by this slice" })),
-      observabilitySurfaces: Type.Optional(Type.Array(Type.String(), { description: "Observability surfaces added" })),
-      provides: Type.Optional(Type.Array(Type.String(), { description: "What this slice provides to downstream slices" })),
-      requirementsSurfaced: Type.Optional(Type.Array(Type.String(), { description: "New requirements surfaced" })),
-      drillDownPaths: Type.Optional(Type.Array(Type.String(), { description: "Paths to task summaries for drill-down" })),
-      affects: Type.Optional(Type.Array(Type.String(), { description: "Downstream slices affected" })),
+      keyFiles: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Key files created or modified" })),
+      keyDecisions: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Key decisions made during this slice" })),
+      patternsEstablished: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Patterns established by this slice" })),
+      observabilitySurfaces: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Observability surfaces added" })),
+      provides: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "What this slice provides to downstream slices" })),
+      requirementsSurfaced: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "New requirements surfaced" })),
+      drillDownPaths: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Paths to task summaries for drill-down" })),
+      affects: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Downstream slices affected" })),
       requirementsAdvanced: Type.Optional(Type.Array(
         Type.Union([
           Type.Object({

package/src/resources/extensions/gsd/bootstrap/notify-interceptor.ts

@@ -0,0 +1,34 @@
+// GSD Extension — Notify Interceptor
+// Wraps ctx.ui.notify() in-place to persist every notification through the
+// notification store. Uses a WeakSet to prevent double-wrapping and handle
+// UI context replacement on /reload gracefully.
+
+import type { ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { appendNotification, type NotifySeverity } from "../notification-store.js";
+
+// Track which ui context objects have been wrapped to prevent double-install.
+// WeakSet allows GC to collect replaced uiContext instances after /reload.
+const _wrappedContexts = new WeakSet<object>();
+
+/**
+ * Install the notify interceptor on a context's UI object.
+ * Mutates ctx.ui.notify in place — the original is called after persistence.
+ * Safe to call multiple times; no-ops if already installed on the same ui object.
+ */
+export function installNotifyInterceptor(ctx: ExtensionContext): void {
+  if (_wrappedContexts.has(ctx.ui)) return;
+
+  const originalNotify = ctx.ui.notify.bind(ctx.ui);
+
+  (ctx.ui as any).notify = (message: string, type?: "info" | "warning" | "error" | "success"): void => {
+    try {
+      appendNotification(message, (type ?? "info") as NotifySeverity, "notify");
+    } catch {
+      // Non-fatal — never let persistence break the UI
+    }
+    originalNotify(message, type);
+  };
+
+  _wrappedContexts.add(ctx.ui);
+}

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

@@ -21,6 +21,9 @@ import { resetAskUserQuestionsCache } from "../../ask-user-questions.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult } from "../safety/evidence-collector.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
+import { installNotifyInterceptor } from "./notify-interceptor.js";
+import { initNotificationStore } from "../notification-store.js";
+import { initNotificationWidget } from "../notification-widget.js";
 
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
@@ -33,6 +36,9 @@ async function syncServiceTierStatus(ctx: ExtensionContext): Promise<void> {
 
 export function registerHooks(pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
+    initNotificationStore(process.cwd());
+    installNotifyInterceptor(ctx);
+    initNotificationWidget(ctx);
     resetWriteGateState();
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
@@ -70,6 +76,8 @@ export function registerHooks(pi: ExtensionAPI): void {
   });
 
   pi.on("session_switch", async (_event, ctx) => {
+    initNotificationStore(process.cwd());
+    installNotifyInterceptor(ctx);
     resetWriteGateState();
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();

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

@@ -5,6 +5,7 @@ import type { ExtensionAPI } 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 { shortcutDesc } from "../../shared/mod.js";
 
@@ -31,6 +32,25 @@ export function registerShortcuts(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerShortcut(Key.ctrlAlt("n"), {
+    description: shortcutDesc("Open notification history", "/gsd notifications"),
+    handler: async (ctx) => {
+      await ctx.ui.custom<void>(
+        (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done()),
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "80%",
+            minWidth: 60,
+            maxHeight: "88%",
+            anchor: "center",
+            backdrop: true,
+          },
+        },
+      );
+    },
+  });
+
   pi.registerShortcut(Key.ctrlAlt("p"), {
     description: shortcutDesc("Open parallel worker monitor", "/gsd parallel watch"),
     handler: async (ctx) => {

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

@@ -264,6 +264,13 @@ function buildWorktreeContextBlock(): string {
   return "";
 }
 
+/**
+ * Low-entropy resume intent patterns — short phrases a user types to
+ * continue work after a pause, rate limit, or context reset (#3615).
+ * Tested against the trimmed, lowercased prompt with trailing punctuation stripped.
+ */
+const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/;
+
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {
   const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
   if (executeMatch) {
@@ -280,6 +287,27 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri
     }
   }
 
+  // Fallback: low-entropy resume prompt (e.g., "continue", "ok", "go ahead")
+  // during an active executing task — inject task context so the agent
+  // doesn't rebuild from scratch (#3615).
+  // Intent-gated: only fire for short, resume-like prompts to avoid hijacking
+  // control/help/diagnostic prompts with unrelated execution context.
+  // Phase-gated: only fire during "executing" to avoid misrouting during
+  // replanning, gate evaluation, or other non-execution phases.
+  const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
+  if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+    const state = await deriveState(basePath);
+    if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {
+      return buildTaskExecutionContextInjection(
+        basePath,
+        state.activeMilestone.id,
+        state.activeSlice.id,
+        state.activeTask.id,
+        state.activeTask.title,
+      );
+    }
+  }
+
   return null;
 }
 

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|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";
+  "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|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";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -48,6 +48,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
   { cmd: "run-hook", desc: "Manually trigger a specific hook" },
   { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
+  { cmd: "notifications", desc: "View, filter, and clear persistent notification history" },
   { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
   { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
   { cmd: "forensics", desc: "Examine execution logs" },
@@ -110,6 +111,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "keys", desc: "Manage API keys" },
     { cmd: "prefs", desc: "Configure global preferences" },
   ],
+  notifications: [
+    { cmd: "clear", desc: "Clear all notifications" },
+    { cmd: "tail", desc: "Show last N notifications (default: 20)" },
+    { cmd: "filter", desc: "Filter by severity (error|warning|info|success)" },
+  ],
   logs: [
     { cmd: "debug", desc: "List or view debug log files" },
     { cmd: "tail", desc: "Show last N activity log summaries" },

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

@@ -29,6 +29,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
+    "  /gsd notifications  View persistent notification history  [clear|tail|filter]  (Ctrl+Alt+N)",
     "",
     "COURSE CORRECTION",
     "  /gsd steer <desc>   Apply user override to active work",

package/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts

@@ -0,0 +1,140 @@
+// GSD Extension — /gsd notifications Command Handler
+// View, filter, and clear the persistent notification history.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import {
+  readNotifications,
+  clearNotifications,
+  getUnreadCount,
+  suppressPersistence,
+  unsuppressPersistence,
+  type NotifySeverity,
+} from "../../notification-store.js";
+import { GSDNotificationOverlay } from "../../notification-overlay.js";
+
+function severityIcon(severity: NotifySeverity): string {
+  switch (severity) {
+    case "error": return "✗";
+    case "warning": return "⚠";
+    case "success": return "✓";
+    case "info":
+    default: return "●";
+  }
+}
+
+function formatTimestamp(ts: string): string {
+  try {
+    const d = new Date(ts);
+    return d.toLocaleString("en-US", { hour12: false, month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+  } catch {
+    return ts.slice(0, 19);
+  }
+}
+
+export async function handleNotificationsCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<boolean> {
+  // /gsd notifications clear
+  if (args === "clear") {
+    clearNotifications();
+    // Suppress persistence so the confirmation toast doesn't re-populate the store
+    suppressPersistence();
+    try {
+      ctx.ui.notify("All notifications cleared.", "success");
+    } finally {
+      unsuppressPersistence();
+    }
+    return true;
+  }
+
+  // /gsd notifications tail [N]
+  if (args === "tail" || args.startsWith("tail ")) {
+    const countStr = args.replace(/^tail\s*/, "").trim();
+    const count = countStr ? parseInt(countStr, 10) : 20;
+    const n = isNaN(count) || count < 1 ? 20 : Math.min(count, 100);
+    const entries = readNotifications().slice(0, n);
+
+    if (entries.length === 0) {
+      ctx.ui.notify("No notifications.", "info");
+      return true;
+    }
+
+    const lines = entries.map((e) =>
+      `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
+    );
+    ctx.ui.notify(`Last ${entries.length} notification(s):\n${lines.join("\n")}`, "info");
+    return true;
+  }
+
+  // /gsd notifications filter <severity>
+  if (args.startsWith("filter ")) {
+    const severity = args.replace(/^filter\s+/, "").trim().toLowerCase();
+    if (!["error", "warning", "info", "success"].includes(severity)) {
+      ctx.ui.notify("Usage: /gsd notifications filter <error|warning|info|success>", "warning");
+      return true;
+    }
+    const entries = readNotifications().filter((e) => e.severity === severity);
+
+    if (entries.length === 0) {
+      ctx.ui.notify(`No ${severity} notifications.`, "info");
+      return true;
+    }
+
+    const lines = entries.slice(0, 20).map((e) =>
+      `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
+    );
+    const suffix = entries.length > 20 ? `\n... and ${entries.length - 20} more` : "";
+    ctx.ui.notify(`${severity} notifications (${entries.length}):\n${lines.join("\n")}${suffix}`, "info");
+    return true;
+  }
+
+  // /gsd notifications (no args) — open overlay in TUI, or print summary
+  if (args === "" || args === "status") {
+    // Try overlay first (TUI mode)
+    if (ctx.hasUI) {
+      try {
+        await ctx.ui.custom<void>(
+          (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done()),
+          {
+            overlay: true,
+            overlayOptions: {
+              width: "80%",
+              minWidth: 60,
+              maxHeight: "88%",
+              anchor: "center",
+              backdrop: true,
+            },
+          },
+        );
+        return true;
+      } catch {
+        // Fall through to text output if overlay fails
+      }
+    }
+
+    // Text fallback (RPC/headless mode)
+    const unread = getUnreadCount();
+    const entries = readNotifications().slice(0, 10);
+    if (entries.length === 0) {
+      ctx.ui.notify("No notifications.", "info");
+      return true;
+    }
+
+    const lines = entries.map((e) =>
+      `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`,
+    );
+    const header = unread > 0 ? `${unread} unread — ` : "";
+    ctx.ui.notify(`${header}Recent notifications:\n${lines.join("\n")}`, "info");
+    return true;
+  }
+
+  // Unknown subcommand
+  ctx.ui.notify(
+    "Usage: /gsd notifications [clear|tail [N]|filter <severity>]",
+    "warning",
+  );
+  return true;
+}