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

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;

package/dist/resources/extensions/gsd/notification-store.js

@@ -16,6 +16,7 @@ let _basePath = null;
 let _lineCount = 0; // Hint for rotation — not authoritative for public API
 let _suppressCount = 0;
 let _recentMessageTimestamps = new Map();
+const _changeListeners = new Set();
 // ─── Public API ─────────────────────────────────────────────────────────
 /**
  * Initialize the notification store. Call once at session start with the
@@ -68,6 +69,7 @@ export function appendNotification(message, severity, source = "notify") {
         if (_lineCount > MAX_ENTRIES) {
             _rotate();
         }
+        _emitChange();
     }
     catch {
         // Non-fatal — never let persistence break the caller
@@ -96,6 +98,7 @@ export function markAllRead(basePath) {
     const hasUnread = entries.some((e) => !e.read);
     if (!hasUnread)
         return;
+    let changed = false;
     try {
         _withLock(bp, () => {
             // Re-read inside lock to get freshest state
@@ -104,11 +107,14 @@ export function markAllRead(basePath) {
                 return;
             const lines = fresh.map((e) => JSON.stringify({ ...e, read: true }));
             _atomicWrite(bp, lines.join("\n") + "\n");
+            changed = true;
         });
     }
     catch {
         // Non-fatal
     }
+    if (changed)
+        _emitChange();
 }
 /**
  * Clear all notifications. Atomic write of empty content under lock.
@@ -121,6 +127,8 @@ export function clearNotifications(basePath) {
         _withLock(bp, () => {
             _atomicWrite(bp, "");
         });
+        _lineCount = 0;
+        _emitChange();
     }
     catch {
         // Non-fatal
@@ -165,6 +173,16 @@ export function suppressPersistence() {
 export function unsuppressPersistence() {
     _suppressCount = Math.max(0, _suppressCount - 1);
 }
+/**
+ * Subscribe to notification-store mutations (append, mark-read, clear).
+ * Returns an unsubscribe function.
+ */
+export function onNotificationStoreChange(listener) {
+    _changeListeners.add(listener);
+    return () => {
+        _changeListeners.delete(listener);
+    };
+}
 // ─── Test Helpers ───────────────────────────────────────────────────────
 /**
  * Reset module state. Only for use in tests.
@@ -174,6 +192,7 @@ export function _resetNotificationStore() {
     _lineCount = 0;
     _suppressCount = 0;
     _recentMessageTimestamps = new Map();
+    _changeListeners.clear();
 }
 // ─── Internal ───────────────────────────────────────────────────────────
 function _readEntriesFromDisk(basePath) {
@@ -211,12 +230,23 @@ function _rotate() {
             const trimmed = entries.slice(entries.length - MAX_ENTRIES);
             const lines = trimmed.map((e) => JSON.stringify(e));
             _atomicWrite(_basePath, lines.join("\n") + "\n");
+            _lineCount = trimmed.length;
         });
     }
     catch {
         // Non-fatal
     }
 }
+function _emitChange() {
+    for (const listener of _changeListeners) {
+        try {
+            listener();
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
 /**
  * Atomic file rewrite via temp-file + rename. Prevents partial reads
  * by other processes (web API subprocess, parallel workers).
@@ -271,10 +301,11 @@ function _withLock(basePath, fn) {
             break;
         }
     }
-    // Only run the mutation if we actually own the lock
-    const ownsLock = fd !== null;
+    // Best-effort: mutation runs regardless of lock status (idempotent overwrites).
+    // createdLock gates cleanup only — never skip fn() on lock failure.
+    const createdLock = fd !== null;
     try {
-        if (ownsLock && fd !== null) {
+        if (createdLock && fd !== null) {
             // Write our PID timestamp into the lock for stale detection
             writeFileSync(lockPath, String(Date.now()), "utf-8");
             closeSync(fd);
@@ -283,7 +314,7 @@ function _withLock(basePath, fn) {
     }
     finally {
         // Only delete the lock if we created it — never remove another process's lock
-        if (ownsLock) {
+        if (createdLock) {
             try {
                 unlinkSync(lockPath);
             }