gsd-pi 2.71.0-dev.06b86c6 → 2.71.0-dev.4c35d99

package/src/resources/extensions/gsd/gate-registry.ts

@@ -0,0 +1,251 @@
+/**
+ * GSD Gate Registry — single source of truth for quality-gate ownership.
+ *
+ * Each gate declares which workflow turn owns it, the scope at which it is
+ * persisted in the `quality_gates` table, and the question/guidance text used
+ * in the prompt that turn sends. The registry replaces the ad-hoc
+ * `GATE_QUESTIONS` table that used to live in `auto-prompts.ts`, and every
+ * layer of the prompt system (prompt builders, dispatch rules, state
+ * derivation, tool handlers) consults it so a pending gate can never be
+ * silently dropped.
+ *
+ * Design notes:
+ *   - `GATE_REGISTRY` is exhaustiveness-checked against `GateId` via
+ *     `satisfies Record<GateId, GateDefinition>`, so adding a new GateId
+ *     without a registry entry is a compile error.
+ *   - `getGatesForTurn(turn)` returns the definitions a turn owns.
+ *   - `assertGateCoverage(pending, turn)` throws a GSDError if the pending
+ *     list for a turn contains unknown gates, or if any gate owned by the
+ *     turn is missing from the pending list.
+ */
+
+import { GSDError, GSD_PARSE_ERROR } from "./errors.js";
+import type { GateId, GateRow, GateScope } from "./types.js";
+
+/** Which workflow turn is responsible for evaluating / closing a gate. */
+export type OwnerTurn =
+  | "gate-evaluate"
+  | "execute-task"
+  | "complete-slice"
+  | "validate-milestone";
+
+export interface GateDefinition {
+  id: GateId;
+  scope: GateScope;
+  ownerTurn: OwnerTurn;
+  /** One-line question the assistant must answer. */
+  question: string;
+  /** Markdown guidance describing what a good answer looks like. */
+  guidance: string;
+  /** H3 section header used in the artifact the turn writes
+   *  (e.g. "Operational Readiness" for Q8 in the slice summary). */
+  promptSection: string;
+}
+
+export const GATE_REGISTRY = {
+  Q3: {
+    id: "Q3",
+    scope: "slice",
+    ownerTurn: "gate-evaluate",
+    question: "How can this be exploited?",
+    guidance: [
+      "Identify abuse scenarios: parameter tampering, replay attacks, privilege escalation.",
+      "Map data exposure risks: PII, tokens, secrets accessible through this slice.",
+      "Define input trust boundaries: untrusted user input reaching DB, API, or filesystem.",
+      "If none apply, return verdict 'omitted' with rationale explaining why.",
+    ].join("\n"),
+    promptSection: "Abuse Surface",
+  },
+  Q4: {
+    id: "Q4",
+    scope: "slice",
+    ownerTurn: "gate-evaluate",
+    question: "What existing promises does this break?",
+    guidance: [
+      "List which existing requirements (R001, R003, etc.) are touched by this slice.",
+      "Identify what must be re-tested after shipping.",
+      "Flag decisions that should be revisited given the new scope.",
+      "If no existing requirements are affected, return verdict 'omitted'.",
+    ].join("\n"),
+    promptSection: "Broken Promises",
+  },
+  Q5: {
+    id: "Q5",
+    scope: "task",
+    ownerTurn: "execute-task",
+    question: "What breaks when dependencies fail?",
+    guidance: [
+      "Enumerate the task's external dependencies (APIs, filesystem, network, subprocesses).",
+      "Describe the failure path for each: timeout, malformed response, connection loss.",
+      "Verify the implementation handles each failure or explicitly bubbles the error.",
+      "Return verdict 'omitted' only if the task has no external dependencies.",
+    ].join("\n"),
+    promptSection: "Failure Modes",
+  },
+  Q6: {
+    id: "Q6",
+    scope: "task",
+    ownerTurn: "execute-task",
+    question: "What is the 10x load breakpoint?",
+    guidance: [
+      "Identify the resource that saturates first at 10x the expected load.",
+      "Describe the protection applied (pool sizing, rate limiting, pagination, caching).",
+      "Return verdict 'omitted' if the task has no runtime load dimension.",
+    ].join("\n"),
+    promptSection: "Load Profile",
+  },
+  Q7: {
+    id: "Q7",
+    scope: "task",
+    ownerTurn: "execute-task",
+    question: "What negative tests protect this task?",
+    guidance: [
+      "List malformed inputs, error paths, and boundary conditions the tests cover.",
+      "Point to the specific test files or cases that assert each negative scenario.",
+      "Return verdict 'omitted' only if the task has no meaningful negative surface.",
+    ].join("\n"),
+    promptSection: "Negative Tests",
+  },
+  Q8: {
+    id: "Q8",
+    scope: "slice",
+    ownerTurn: "complete-slice",
+    question: "How will ops know this slice is healthy or broken?",
+    guidance: [
+      "Describe the health signal (metric, log line, dashboard) that proves the slice works.",
+      "Describe the failure signal that triggers an alert or paging.",
+      "Document the recovery procedure and any monitoring gaps.",
+      "Return verdict 'omitted' only for slices with no runtime behavior at all.",
+    ].join("\n"),
+    promptSection: "Operational Readiness",
+  },
+  MV01: {
+    id: "MV01",
+    scope: "milestone",
+    ownerTurn: "validate-milestone",
+    question: "Is every success criterion in the milestone roadmap satisfied?",
+    guidance: [
+      "Walk the success-criteria checklist from the milestone roadmap.",
+      "For each criterion, point to the slice / assessment / verification evidence that proves it.",
+      "Return verdict 'flag' if any criterion is unmet or unverifiable.",
+    ].join("\n"),
+    promptSection: "Success Criteria Checklist",
+  },
+  MV02: {
+    id: "MV02",
+    scope: "milestone",
+    ownerTurn: "validate-milestone",
+    question: "Does every slice have a SUMMARY.md and a passing assessment?",
+    guidance: [
+      "Confirm every slice listed in the roadmap has a SUMMARY.md.",
+      "Confirm each slice has an ASSESSMENT verdict of 'pass' (or justified 'omitted').",
+      "Flag missing artifacts and slices with outstanding follow-ups or known limitations.",
+    ].join("\n"),
+    promptSection: "Slice Delivery Audit",
+  },
+  MV03: {
+    id: "MV03",
+    scope: "milestone",
+    ownerTurn: "validate-milestone",
+    question: "Do the slices integrate end-to-end?",
+    guidance: [
+      "Trace at least one cross-slice flow proving the pieces compose.",
+      "Flag gaps where two slices were built in isolation with no integration evidence.",
+    ].join("\n"),
+    promptSection: "Cross-Slice Integration",
+  },
+  MV04: {
+    id: "MV04",
+    scope: "milestone",
+    ownerTurn: "validate-milestone",
+    question: "Are all touched requirements covered and still coherent?",
+    guidance: [
+      "For each requirement advanced, validated, surfaced, or invalidated across the milestone's slices, confirm the milestone-level evidence matches.",
+      "Flag requirements that slices claim to advance but no artifact proves.",
+    ].join("\n"),
+    promptSection: "Requirement Coverage",
+  },
+} as const satisfies Record<GateId, GateDefinition>;
+
+export type GateRegistry = typeof GATE_REGISTRY;
+
+/** Stable ordered lists per owner turn — iteration order matches declaration. */
+const ORDERED_GATES: readonly GateDefinition[] = Object.values(GATE_REGISTRY) as readonly GateDefinition[];
+
+/** Return every gate owned by a turn, in stable declaration order. */
+export function getGatesForTurn(turn: OwnerTurn): GateDefinition[] {
+  return ORDERED_GATES.filter((g) => g.ownerTurn === turn);
+}
+
+/** Return the set of gate ids a turn owns. */
+export function getGateIdsForTurn(turn: OwnerTurn): Set<GateId> {
+  return new Set(getGatesForTurn(turn).map((g) => g.id));
+}
+
+/** Look up a definition by gate id, or undefined if unknown. */
+export function getGateDefinition(id: string): GateDefinition | undefined {
+  return (GATE_REGISTRY as Record<string, GateDefinition>)[id];
+}
+
+/** Look up the owner turn for a gate id. Throws if the gate is unknown. */
+export function getOwnerTurn(id: GateId): OwnerTurn {
+  const def = GATE_REGISTRY[id];
+  if (!def) {
+    throw new GSDError(GSD_PARSE_ERROR, `gate-registry: unknown gate id "${id}"`);
+  }
+  return def.ownerTurn;
+}
+
+/**
+ * Assert that the pending gate rows for a turn match what the registry says
+ * the turn owns. Fails loudly rather than silently skipping.
+ *
+ * - Every row in `pending` must have a definition whose `ownerTurn` matches `turn`.
+ *   (The caller is responsible for scoping the pending list — e.g. filtering
+ *   by slice scope before passing it in.)
+ * - `options.requireAll` (default true): every gate the turn owns must appear
+ *   in `pending`. Set to false for turns like `execute-task` that only need
+ *   coverage for the subset of gates that were seeded (e.g. tasks with no
+ *   external dependencies have no Q5 row).
+ */
+export function assertGateCoverage(
+  pending: ReadonlyArray<Pick<GateRow, "gate_id">>,
+  turn: OwnerTurn,
+  options: { requireAll?: boolean } = {},
+): void {
+  const requireAll = options.requireAll ?? true;
+  const expected = getGateIdsForTurn(turn);
+  const pendingIds = new Set(pending.map((g) => g.gate_id));
+
+  const unknown: string[] = [];
+  for (const id of pendingIds) {
+    const def = getGateDefinition(id);
+    if (!def) {
+      unknown.push(id);
+      continue;
+    }
+    if (def.ownerTurn !== turn) {
+      unknown.push(`${id} (owned by ${def.ownerTurn}, not ${turn})`);
+    }
+  }
+
+  if (unknown.length > 0) {
+    throw new GSDError(
+      GSD_PARSE_ERROR,
+      `assertGateCoverage: turn "${turn}" received pending gates it does not own: ${unknown.join(", ")}`,
+    );
+  }
+
+  if (requireAll) {
+    const missing: GateId[] = [];
+    for (const id of expected) {
+      if (!pendingIds.has(id)) missing.push(id);
+    }
+    if (missing.length > 0) {
+      throw new GSDError(
+        GSD_PARSE_ERROR,
+        `assertGateCoverage: turn "${turn}" is missing required gates: ${missing.join(", ")}`,
+      );
+    }
+  }
+}

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

@@ -10,6 +10,7 @@ import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
+import { getGateIdsForTurn, type OwnerTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 
 const _require = createRequire(import.meta.url);
@@ -2302,3 +2303,53 @@ export function getPendingSliceGateCount(milestoneId: string, sliceId: string):
   ).get({ ":mid": milestoneId, ":sid": sliceId });
   return row ? (row["cnt"] as number) : 0;
 }
+
+/**
+ * Return pending gate rows owned by a specific workflow turn.
+ *
+ * Unlike `getPendingGates(..., scope)`, this filters by the registry's
+ * `ownerTurn` metadata so callers can distinguish Q3/Q4 (owned by
+ * gate-evaluate) from Q8 (owned by complete-slice) even though both are
+ * scope:"slice". Pass `taskId` to narrow task-scoped results to one task.
+ */
+export function getPendingGatesForTurn(
+  milestoneId: string,
+  sliceId: string,
+  turn: OwnerTurn,
+  taskId?: string,
+): GateRow[] {
+  if (!currentDb) return [];
+  const ids = getGateIdsForTurn(turn);
+  if (ids.size === 0) return [];
+  const idList = [...ids];
+  const placeholders = idList.map((_, i) => `:gid${i}`).join(",");
+  const params: Record<string, unknown> = {
+    ":mid": milestoneId,
+    ":sid": sliceId,
+  };
+  idList.forEach((id, i) => {
+    params[`:gid${i}`] = id;
+  });
+  let sql =
+    `SELECT * FROM quality_gates
+     WHERE milestone_id = :mid AND slice_id = :sid
+       AND status = 'pending'
+       AND gate_id IN (${placeholders})`;
+  if (taskId !== undefined) {
+    sql += ` AND task_id = :tid`;
+    params[":tid"] = taskId;
+  }
+  return currentDb.prepare(sql).all(params).map(rowToGate);
+}
+
+/**
+ * Count pending gates for a turn. Convenience wrapper used by state
+ * derivation to decide whether a phase transition should pause.
+ */
+export function getPendingGateCountForTurn(
+  milestoneId: string,
+  sliceId: string,
+  turn: OwnerTurn,
+): number {
+  return getPendingGatesForTurn(milestoneId, sliceId, turn).length;
+}

package/src/resources/extensions/gsd/guided-flow.ts

@@ -15,7 +15,7 @@ import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
-import { startAuto } from "./auto.js";
+import { startAutoDetached } from "./auto.js";
 import { clearLock } from "./crash-recovery.js";
 import {
   assessInterruptedSession,
@@ -67,7 +67,6 @@ export {
   showQueue, handleQueueReorder, showQueueAdd,
   buildExistingMilestonesContext,
 } from "./guided-flow-queue.js";
-import { getErrorMessage } from "./error-utils.js";
 import { logWarning } from "./workflow-logger.js";
 
 // ─── ID Generation with Reservation ─────────────────────────────────────────
@@ -244,11 +243,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   pendingAutoStartMap.delete(basePath);
   ctx.ui.notify(`Milestone ${milestoneId} ready.`, "info");
-  startAuto(ctx, pi, basePath, false, { step }).catch((err) => {
-    ctx.ui.notify(`Auto-start failed: ${getErrorMessage(err)}`, "error");
-    logWarning("guided", `auto start error: ${getErrorMessage(err)}`);
-    debugLog("auto-start-failed", { error: getErrorMessage(err) });
-  });
+  startAutoDetached(ctx, pi, basePath, false, { step });
   return true;
 }
 
@@ -1305,7 +1300,7 @@ export async function showSmartEntry(
       ],
     });
     if (resume === "resume") {
-      await startAuto(ctx, pi, basePath, false, {
+      startAutoDetached(ctx, pi, basePath, false, {
         interrupted,
         step: interrupted.pausedSession?.stepMode ?? false,
       });
@@ -1647,7 +1642,7 @@ export async function showSmartEntry(
       });
 
       if (choice === "auto") {
-        await startAuto(ctx, pi, basePath, false);
+        startAutoDetached(ctx, pi, basePath, false);
       } else if (choice === "status") {
         const { fireStatusViaCommand } = await import("./commands.js");
         await fireStatusViaCommand(ctx);
@@ -1859,7 +1854,7 @@ export async function showSmartEntry(
     });
 
     if (choice === "auto") {
-      await startAuto(ctx, pi, basePath, false);
+      startAutoDetached(ctx, pi, basePath, false);
       return;
     }
 

package/src/resources/extensions/gsd/interrupted-session.ts

@@ -34,6 +34,7 @@ export interface PausedSessionMetadata {
   activeEngineId?: string;
   activeRunDir?: string | null;
   autoStartTime?: number;
+  milestoneLock?: string | null;
 }
 
 export interface InterruptedSessionAssessment {

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

@@ -41,6 +41,7 @@ export interface UnitMetrics {
   model: string;           // model ID used
   startedAt: number;       // ms timestamp
   finishedAt: number;      // ms timestamp
+  autoSessionKey?: string; // identifies one auto-mode run across pause/resume
   tokens: TokenCounts;
   cost: number;            // total USD cost
   toolCalls: number;
@@ -133,7 +134,16 @@ export function snapshotUnitMetrics(
   unitId: string,
   startedAt: number,
   model: string,
-  opts?: { tier?: string; modelDowngraded?: boolean; contextWindowTokens?: number; truncationSections?: number; continueHereFired?: boolean; promptCharCount?: number; baselineCharCount?: number },
+  opts?: {
+    tier?: string;
+    modelDowngraded?: boolean;
+    contextWindowTokens?: number;
+    truncationSections?: number;
+    continueHereFired?: boolean;
+    promptCharCount?: number;
+    baselineCharCount?: number;
+    autoSessionKey?: string;
+  },
 ): UnitMetrics | null {
   if (!ledger) return null;
 
@@ -181,6 +191,7 @@ export function snapshotUnitMetrics(
     model,
     startedAt,
     finishedAt: Date.now(),
+    ...(opts?.autoSessionKey ? { autoSessionKey: opts.autoSessionKey } : {}),
     tokens,
     cost,
     toolCalls,

package/src/resources/extensions/gsd/milestone-actions.ts

@@ -20,7 +20,7 @@ import {
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadQueueOrder, saveQueueOrder } from "./queue-order.js";
-import { isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
+import { getMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
 import { logWarning } from "./workflow-logger.js";
 
 // ─── Park ──────────────────────────────────────────────────────────────────
@@ -77,9 +77,16 @@ export function unparkMilestone(basePath: string, milestoneId: string): boolean
   if (!mDir || !existsSync(mDir)) return false;
 
   const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
-  if (!existsSync(parkedPath)) return false; // not parked
+  const hadParkedFile = existsSync(parkedPath);
+  const dbThinksParked = isDbAvailable() && getMilestone(milestoneId)?.status === "parked";
 
-  unlinkSync(parkedPath);
+  // Recover the reverse desync too: DB can still say "parked" even when the
+  // PARKED marker was lost on disk, and /gsd unpark should repair that state.
+  if (!hadParkedFile && !dbThinksParked) return false;
+
+  if (hadParkedFile) {
+    unlinkSync(parkedPath);
+  }
   // Sync DB status so deriveStateFromDb picks up the unparked milestone (#2694)
   if (isDbAvailable()) {
     try {

package/src/resources/extensions/gsd/milestone-validation-gates.ts

@@ -6,19 +6,13 @@
  * records in the DB. This module inserts milestone-level validation gates
  * that correspond to the validation checks performed.
  *
- * Gate IDs for milestone validation:
- *   MV01 — Success criteria checklist
- *   MV02 — Slice delivery audit
- *   MV03 — Cross-slice integration
- *   MV04 — Requirement coverage
- *
- * These use the existing quality_gates table with scope "milestone".
+ * Gate IDs for milestone validation (MV01–MV04) are sourced from the
+ * gate registry so the definitions stay in lockstep with prompt builders,
+ * dispatch rules, and state derivation. See gate-registry.ts.
  */
 
 import { _getAdapter } from "./gsd-db.js";
-
-/** Milestone validation gate IDs. */
-const MILESTONE_GATE_IDS = ["MV01", "MV02", "MV03", "MV04"] as const;
+import { getGatesForTurn } from "./gate-registry.js";
 
 /**
  * Insert milestone-level quality_gates records for a validation run.
@@ -27,6 +21,9 @@ const MILESTONE_GATE_IDS = ["MV01", "MV02", "MV03", "MV04"] as const;
  * from the overall milestone validation verdict. Individual gate-level
  * verdicts are not available (the handler receives a single verdict),
  * so all gates share the overall verdict.
+ *
+ * Gate IDs come from the registry — adding/removing an MV-scoped gate
+ * in gate-registry.ts automatically flows through here.
  */
 export function insertMilestoneValidationGates(
   milestoneId: string,
@@ -38,8 +35,9 @@ export function insertMilestoneValidationGates(
   if (!db) return;
 
   const gateVerdict = verdict === "pass" ? "pass" : "flag";
+  const milestoneGates = getGatesForTurn("validate-milestone");
 
-  for (const gateId of MILESTONE_GATE_IDS) {
+  for (const def of milestoneGates) {
     db.prepare(
       `INSERT OR REPLACE INTO quality_gates
        (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
@@ -47,9 +45,9 @@ export function insertMilestoneValidationGates(
     ).run({
       ":mid": milestoneId,
       ":sid": sliceId,
-      ":gid": gateId,
+      ":gid": def.id,
       ":verdict": gateVerdict,
-      ":rationale": `Milestone validation verdict: ${verdict}`,
+      ":rationale": `${def.promptSection} — milestone validation verdict: ${verdict}`,
       ":evaluated_at": evaluatedAt,
     });
   }

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

@@ -1,6 +1,6 @@
 // GSD Extension — Notification History Overlay
 // Scrollable panel showing all persisted notifications with severity filtering.
-// Toggled with Ctrl+Alt+N (⌃⌥N on macOS) or opened from /gsd notifications.
+// Toggled with Ctrl+Alt+N (⌃⌥N on macOS), Ctrl+Shift+N fallback, or /gsd notifications.
 
 import type { Theme } from "@gsd/pi-coding-agent";
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
@@ -9,11 +9,12 @@ import {
   readNotifications,
   markAllRead,
   clearNotifications,
-  getUnreadCount,
+  onNotificationStoreChange,
   type NotificationEntry,
   type NotifySeverity,
 } from "./notification-store.js";
-import { padRight, centerLine, joinColumns, formatDuration } from "../shared/mod.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
+import { padRight, joinColumns } from "../shared/mod.js";
 
 type FilterMode = "all" | "error" | "warning" | "info";
 const FILTER_CYCLE: FilterMode[] = ["all", "error", "warning", "info"];
@@ -63,6 +64,12 @@ function formatTimestamp(ts: string): string {
   }
 }
 
+function notificationSignature(entries: readonly NotificationEntry[]): string {
+  return entries
+    .map((entry) => `${entry.ts}|${entry.severity}|${entry.read ? 1 : 0}|${entry.message}`)
+    .join("\n");
+}
+
 export class GSDNotificationOverlay {
   private tui: { requestRender: () => void };
   private theme: Theme;
@@ -72,9 +79,11 @@ export class GSDNotificationOverlay {
   private scrollOffset = 0;
   private filterIndex = 0;
   private entries: NotificationEntry[] = [];
+  private entriesSignature = "";
   private refreshTimer: ReturnType<typeof setInterval>;
   private disposed = false;
   private resizeHandler: (() => void) | null = null;
+  private unsubscribeStore: (() => void) | null = null;
 
   constructor(
     tui: { requestRender: () => void },
@@ -88,6 +97,7 @@ export class GSDNotificationOverlay {
     // Mark all as read on open
     markAllRead();
     this.entries = readNotifications();
+    this.entriesSignature = notificationSignature(this.entries);
 
     // Resize handler
     this.resizeHandler = () => {
@@ -97,17 +107,17 @@ export class GSDNotificationOverlay {
     };
     process.stdout.on("resize", this.resizeHandler);
 
-    // Refresh every 3s for new notifications
+    // Subscribe to store mutations for immediate updates
+    this.unsubscribeStore = onNotificationStoreChange(() => {
+      if (this.disposed) return;
+      this._refreshFromDisk();
+    });
+
+    // 30s safety-net for cross-process edits (web subprocess, parallel workers)
     this.refreshTimer = setInterval(() => {
       if (this.disposed) return;
-      const fresh = readNotifications();
-      if (fresh.length !== this.entries.length) {
-        this.entries = fresh;
-        markAllRead();
-        this.invalidate();
-        this.tui.requestRender();
-      }
-    }, 3000);
+      this._refreshFromDisk();
+    }, 30_000);
   }
 
   private get filter(): FilterMode {
@@ -120,7 +130,12 @@ export class GSDNotificationOverlay {
   }
 
   handleInput(data: string): void {
-    if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c")) || matchesKey(data, Key.ctrlAlt("n"))) {
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl("c")) ||
+      matchesKey(data, Key.ctrlAlt("n")) ||
+      matchesKey(data, Key.ctrlShift("n"))
+    ) {
       this.dispose();
       this.onClose();
       return;
@@ -165,6 +180,7 @@ export class GSDNotificationOverlay {
     if (data === "c") {
       clearNotifications();
       this.entries = [];
+      this.entriesSignature = notificationSignature(this.entries);
       this.scrollOffset = 0;
       this.invalidate();
       this.tui.requestRender();
@@ -199,12 +215,28 @@ export class GSDNotificationOverlay {
   dispose(): void {
     this.disposed = true;
     clearInterval(this.refreshTimer);
+    if (this.unsubscribeStore) {
+      this.unsubscribeStore();
+      this.unsubscribeStore = null;
+    }
     if (this.resizeHandler) {
       process.stdout.removeListener("resize", this.resizeHandler);
       this.resizeHandler = null;
     }
   }
 
+  private _refreshFromDisk(): void {
+    const fresh = readNotifications();
+    const signature = notificationSignature(fresh);
+    if (signature !== this.entriesSignature) {
+      markAllRead();
+      this.entries = readNotifications();
+      this.entriesSignature = notificationSignature(this.entries);
+      this.invalidate();
+      this.tui.requestRender();
+    }
+  }
+
   private wrapInBox(inner: string[], width: number): string[] {
     const th = this.theme;
     const border = (s: string) => th.fg("borderAccent", s);
@@ -250,7 +282,8 @@ export class GSDNotificationOverlay {
     lines.push(hr());
 
     // Controls
-    lines.push(row(th.fg("dim", "↑/↓ scroll  f filter  c clear  Esc close")));
+    const closeShortcut = formattedShortcutPair("notifications");
+    lines.push(row(th.fg("dim", `↑/↓ scroll  f filter  c clear  Esc close  (${closeShortcut})`)));
     lines.push(blank());
 
     // Entries