gsd-pi 2.71.0 → 2.72.0-dev.de4c4b3

package/dist/resources/extensions/gsd/error-classifier.js

@@ -20,10 +20,13 @@ export function resetRetryState(state) {
 // ── Classification ──────────────────────────────────────────────────────────
 const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i;
 const RATE_LIMIT_RE = /rate.?limit|too many requests|429/i;
+// OpenRouter affordability-style quota errors should be treated as transient
+// so core retry logic can lower maxTokens and continue in-session.
+const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient credits|not enough credits|fewer max_tokens/i;
 const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i;
 const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
-const CONNECTION_RE = /terminated|connection.?refused|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
 // This eliminates the need to enumerate every error message variant individually.
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
@@ -42,7 +45,7 @@ const RESET_DELAY_RE = /reset in (\d+)s/i;
  */
 export function classifyError(errorMsg, retryAfterMs) {
     const isPermanent = PERMANENT_RE.test(errorMsg);
-    const isRateLimit = RATE_LIMIT_RE.test(errorMsg);
+    const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
     // 1. Permanent — but rate limit takes precedence
     if (isPermanent && !isRateLimit) {
         return { kind: "permanent" };

package/dist/resources/extensions/gsd/forensics.js

@@ -508,19 +508,30 @@ function getDbCompletionCounts() {
  * Exported for testability.
  */
 export function detectStuckLoops(units, anomalies) {
-    // First, collect unique startedAt values per type/id key
+    // First, collect unique startedAt values per type/id key, bucketed by
+    // autoSessionKey when available so cross-session recovery does not look
+    // like a within-session stuck loop.
     const dispatchMap = new Map();
     for (const u of units) {
         const key = `${u.type}/${u.id}`;
-        let starts = dispatchMap.get(key);
+        let sessionBuckets = dispatchMap.get(key);
+        if (!sessionBuckets) {
+            sessionBuckets = new Map();
+            dispatchMap.set(key, sessionBuckets);
+        }
+        const sessionKey = u.autoSessionKey ?? "__legacy__";
+        let starts = sessionBuckets.get(sessionKey);
         if (!starts) {
             starts = new Set();
-            dispatchMap.set(key, starts);
+            sessionBuckets.set(sessionKey, starts);
         }
         starts.add(u.startedAt);
     }
-    for (const [key, starts] of dispatchMap) {
-        const count = starts.size;
+    for (const [key, sessionBuckets] of dispatchMap) {
+        const hasSessionAwareData = Array.from(sessionBuckets.keys()).some((sessionKey) => sessionKey !== "__legacy__");
+        const count = hasSessionAwareData
+            ? Math.max(...Array.from(sessionBuckets.values(), (starts) => starts.size))
+            : (sessionBuckets.get("__legacy__")?.size ?? 0);
         if (count > 1) {
             const [unitType, ...idParts] = key.split("/");
             anomalies.push({
@@ -529,7 +540,9 @@ export function detectStuckLoops(units, anomalies) {
                 unitType,
                 unitId: idParts.join("/"),
                 summary: `Unit ${key} was dispatched ${count} times`,
-                details: `Repeated dispatch suggests the unit completed but its artifacts weren't verified, or the state machine kept returning it.`,
+                details: hasSessionAwareData
+                    ? `Repeated dispatch within the same auto session suggests the unit completed but its artifacts were not verified, or the state machine kept returning it. Cross-session recovery runs are ignored.`
+                    : `Repeated dispatch suggests the unit completed but its artifacts weren't verified, or the state machine kept returning it.`,
             });
         }
     }

package/dist/resources/extensions/gsd/gate-registry.js

@@ -0,0 +1,208 @@
+/**
+ * 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";
+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",
+    },
+};
+/** Stable ordered lists per owner turn — iteration order matches declaration. */
+const ORDERED_GATES = Object.values(GATE_REGISTRY);
+/** Return every gate owned by a turn, in stable declaration order. */
+export function getGatesForTurn(turn) {
+    return ORDERED_GATES.filter((g) => g.ownerTurn === turn);
+}
+/** Return the set of gate ids a turn owns. */
+export function getGateIdsForTurn(turn) {
+    return new Set(getGatesForTurn(turn).map((g) => g.id));
+}
+/** Look up a definition by gate id, or undefined if unknown. */
+export function getGateDefinition(id) {
+    return GATE_REGISTRY[id];
+}
+/** Look up the owner turn for a gate id. Throws if the gate is unknown. */
+export function getOwnerTurn(id) {
+    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, turn, options = {}) {
+    const requireAll = options.requireAll ?? true;
+    const expected = getGateIdsForTurn(turn);
+    const pendingIds = new Set(pending.map((g) => g.gate_id));
+    const unknown = [];
+    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 = [];
+        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/dist/resources/extensions/gsd/gsd-db.js

@@ -8,6 +8,7 @@ import { createRequire } from "node:module";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
+import { getGateIdsForTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 const _require = createRequire(import.meta.url);
 let providerName = null;
@@ -1927,3 +1928,43 @@ export function getPendingSliceGateCount(milestoneId, sliceId) {
      WHERE milestone_id = :mid AND slice_id = :sid AND scope = 'slice' AND status = 'pending'`).get({ ":mid": milestoneId, ":sid": sliceId });
     return row ? row["cnt"] : 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, sliceId, turn, taskId) {
+    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 = {
+        ":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, sliceId, turn) {
+    return getPendingGatesForTurn(milestoneId, sliceId, turn).length;
+}

package/dist/resources/extensions/gsd/guided-flow.js

@@ -13,7 +13,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, formatInterruptedSessionRunningMessage, formatInterruptedSessionSummary, } from "./interrupted-session.js";
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
@@ -40,7 +40,6 @@ import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from ".
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 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 ─────────────────────────────────────────
 /**
@@ -200,11 +199,7 @@ export function checkAutoStartAfterDiscuss() {
     }
     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;
 }
 /**
@@ -1097,7 +1092,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             ],
         });
         if (resume === "resume") {
-            await startAuto(ctx, pi, basePath, false, {
+            startAutoDetached(ctx, pi, basePath, false, {
                 interrupted,
                 step: interrupted.pausedSession?.stepMode ?? false,
             });
@@ -1409,7 +1404,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 notYetMessage: "Run /gsd status for details.",
             });
             if (choice === "auto") {
-                await startAuto(ctx, pi, basePath, false);
+                startAutoDetached(ctx, pi, basePath, false);
             }
             else if (choice === "status") {
                 const { fireStatusViaCommand } = await import("./commands.js");
@@ -1622,7 +1617,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             notYetMessage: "Run /gsd when ready.",
         });
         if (choice === "auto") {
-            await startAuto(ctx, pi, basePath, false);
+            startAutoDetached(ctx, pi, basePath, false);
             return;
         }
         if (choice === "execute") {

package/dist/resources/extensions/gsd/metrics.js

@@ -113,6 +113,7 @@ export function snapshotUnitMetrics(ctx, unitType, unitId, startedAt, model, opt
         model,
         startedAt,
         finishedAt: Date.now(),
+        ...(opts?.autoSessionKey ? { autoSessionKey: opts.autoSessionKey } : {}),
         tokens,
         cost,
         toolCalls,

package/dist/resources/extensions/gsd/milestone-actions.js

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { resolveMilestonePath, resolveMilestoneFile, buildMilestoneFileName, } 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 ──────────────────────────────────────────────────────────────────
 /**
@@ -68,9 +68,15 @@ export function unparkMilestone(basePath, milestoneId) {
     if (!mDir || !existsSync(mDir))
         return false;
     const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
-    if (!existsSync(parkedPath))
-        return false; // not parked
-    unlinkSync(parkedPath);
+    const hadParkedFile = existsSync(parkedPath);
+    const dbThinksParked = isDbAvailable() && getMilestone(milestoneId)?.status === "parked";
+    // 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/dist/resources/extensions/gsd/milestone-validation-gates.js

@@ -6,17 +6,12 @@
  * 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"];
+import { getGatesForTurn } from "./gate-registry.js";
 /**
  * Insert milestone-level quality_gates records for a validation run.
  *
@@ -24,21 +19,25 @@ const MILESTONE_GATE_IDS = ["MV01", "MV02", "MV03", "MV04"];
  * 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, sliceId, verdict, evaluatedAt) {
     const db = _getAdapter();
     if (!db)
         return;
     const gateVerdict = verdict === "pass" ? "pass" : "flag";
-    for (const gateId of MILESTONE_GATE_IDS) {
+    const milestoneGates = getGatesForTurn("validate-milestone");
+    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)
        VALUES (:mid, :sid, :gid, 'milestone', '', 'complete', :verdict, :rationale, '', :evaluated_at)`).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/dist/resources/extensions/gsd/notification-overlay.js

@@ -1,8 +1,9 @@
 // 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 { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
-import { readNotifications, markAllRead, clearNotifications, } from "./notification-store.js";
+import { readNotifications, markAllRead, clearNotifications, onNotificationStoreChange, } from "./notification-store.js";
+import { formattedShortcutPair } from "./shortcut-defs.js";
 import { padRight, joinColumns } from "../shared/mod.js";
 const FILTER_CYCLE = ["all", "error", "warning", "info"];
 function severityIcon(severity) {
@@ -55,6 +56,11 @@ function formatTimestamp(ts) {
         return ts.slice(11, 19); // fallback: HH:MM:SS
     }
 }
+function notificationSignature(entries) {
+    return entries
+        .map((entry) => `${entry.ts}|${entry.severity}|${entry.read ? 1 : 0}|${entry.message}`)
+        .join("\n");
+}
 export class GSDNotificationOverlay {
     tui;
     theme;
@@ -64,9 +70,11 @@ export class GSDNotificationOverlay {
     scrollOffset = 0;
     filterIndex = 0;
     entries = [];
+    entriesSignature = "";
     refreshTimer;
     disposed = false;
     resizeHandler = null;
+    unsubscribeStore = null;
     constructor(tui, theme, onClose) {
         this.tui = tui;
         this.theme = theme;
@@ -74,6 +82,7 @@ export class GSDNotificationOverlay {
         // Mark all as read on open
         markAllRead();
         this.entries = readNotifications();
+        this.entriesSignature = notificationSignature(this.entries);
         // Resize handler
         this.resizeHandler = () => {
             if (this.disposed)
@@ -82,18 +91,18 @@ export class GSDNotificationOverlay {
             this.tui.requestRender();
         };
         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);
     }
     get filter() {
         return FILTER_CYCLE[this.filterIndex];
@@ -104,7 +113,10 @@ export class GSDNotificationOverlay {
         return this.entries.filter((e) => e.severity === this.filter);
     }
     handleInput(data) {
-        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;
@@ -146,6 +158,7 @@ export class GSDNotificationOverlay {
         if (data === "c") {
             clearNotifications();
             this.entries = [];
+            this.entriesSignature = notificationSignature(this.entries);
             this.scrollOffset = 0;
             this.invalidate();
             this.tui.requestRender();
@@ -174,11 +187,26 @@ export class GSDNotificationOverlay {
     dispose() {
         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;
         }
     }
+    _refreshFromDisk() {
+        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();
+        }
+    }
     wrapInBox(inner, width) {
         const th = this.theme;
         const border = (s) => th.fg("borderAccent", s);
@@ -215,7 +243,8 @@ export class GSDNotificationOverlay {
         lines.push(row(joinColumns(`${title}  ${th.fg("dim", "filter:")} ${filterLabel}`, th.fg("dim", count), contentWidth)));
         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
         const filtered = this.filteredEntries;