gsd-pi 2.64.0 → 2.65.0

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-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";
+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|notifications";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -36,6 +36,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -97,6 +98,11 @@ const NESTED_COMPLETIONS = {
         { 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/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -25,6 +25,7 @@ export function showHelp(ctx) {
         "  /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/dist/resources/extensions/gsd/commands/handlers/notifications-handler.js

@@ -0,0 +1,104 @@
+// GSD Extension — /gsd notifications Command Handler
+// View, filter, and clear the persistent notification history.
+import { readNotifications, clearNotifications, getUnreadCount, suppressPersistence, unsuppressPersistence, } from "../../notification-store.js";
+import { GSDNotificationOverlay } from "../../notification-overlay.js";
+function severityIcon(severity) {
+    switch (severity) {
+        case "error": return "✗";
+        case "warning": return "⚠";
+        case "success": return "✓";
+        case "info":
+        default: return "●";
+    }
+}
+function formatTimestamp(ts) {
+    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, ctx, pi) {
+    // /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((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;
+}

package/dist/resources/extensions/gsd/commands/handlers/ops.js

@@ -175,6 +175,11 @@ Examples:
         await dispatchDirectPhase(ctx, pi, phase, projectRoot());
         return true;
     }
+    if (trimmed === "notifications" || trimmed.startsWith("notifications ")) {
+        const { handleNotificationsCommand } = await import("./notifications-handler.js");
+        await handleNotificationsCommand(trimmed.replace(/^notifications\s*/, "").trim(), ctx, pi);
+        return true;
+    }
     if (trimmed === "inspect") {
         await handleInspect(ctx);
         return true;

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

@@ -0,0 +1,256 @@
+// GSD Extension — Notification History Overlay
+// Scrollable panel showing all persisted notifications with severity filtering.
+// Toggled with Ctrl+Alt+N or opened from /gsd notifications.
+import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
+import { readNotifications, markAllRead, clearNotifications, } from "./notification-store.js";
+import { padRight, joinColumns } from "../shared/mod.js";
+const FILTER_CYCLE = ["all", "error", "warning", "info"];
+function severityIcon(severity) {
+    switch (severity) {
+        case "error": return "✗";
+        case "warning": return "⚠";
+        case "success": return "✓";
+        case "info":
+        default: return "●";
+    }
+}
+/** Word-wrap plain text to fit within maxWidth columns. */
+function wrapText(text, maxWidth) {
+    if (text.length <= maxWidth)
+        return [text];
+    const words = text.split(/\s+/);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= maxWidth) {
+            current += " " + word;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    // If a single word exceeds maxWidth, truncate it
+    return lines.map((l) => l.length > maxWidth ? l.slice(0, maxWidth - 1) + "…" : l);
+}
+function formatTimestamp(ts) {
+    try {
+        const d = new Date(ts);
+        const now = Date.now();
+        const diffMs = now - d.getTime();
+        if (diffMs < 60_000)
+            return "just now";
+        if (diffMs < 3600_000)
+            return `${Math.floor(diffMs / 60_000)}m ago`;
+        if (diffMs < 86400_000)
+            return `${Math.floor(diffMs / 3600_000)}h ago`;
+        return `${Math.floor(diffMs / 86400_000)}d ago`;
+    }
+    catch {
+        return ts.slice(11, 19); // fallback: HH:MM:SS
+    }
+}
+export class GSDNotificationOverlay {
+    tui;
+    theme;
+    onClose;
+    cachedWidth;
+    cachedLines;
+    scrollOffset = 0;
+    filterIndex = 0;
+    entries = [];
+    refreshTimer;
+    disposed = false;
+    resizeHandler = null;
+    constructor(tui, theme, onClose) {
+        this.tui = tui;
+        this.theme = theme;
+        this.onClose = onClose;
+        // Mark all as read on open
+        markAllRead();
+        this.entries = readNotifications();
+        // Resize handler
+        this.resizeHandler = () => {
+            if (this.disposed)
+                return;
+            this.invalidate();
+            this.tui.requestRender();
+        };
+        process.stdout.on("resize", this.resizeHandler);
+        // Refresh every 3s for new notifications
+        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);
+    }
+    get filter() {
+        return FILTER_CYCLE[this.filterIndex];
+    }
+    get filteredEntries() {
+        if (this.filter === "all")
+            return this.entries;
+        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"))) {
+            this.dispose();
+            this.onClose();
+            return;
+        }
+        // Scroll
+        if (matchesKey(data, Key.down) || matchesKey(data, "j")) {
+            this.scrollOffset++;
+            this.invalidate();
+            this.tui.requestRender();
+            return;
+        }
+        if (matchesKey(data, Key.up) || matchesKey(data, "k")) {
+            this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+            this.invalidate();
+            this.tui.requestRender();
+            return;
+        }
+        if (data === "g") {
+            this.scrollOffset = 0;
+            this.invalidate();
+            this.tui.requestRender();
+            return;
+        }
+        if (data === "G") {
+            this.scrollOffset = 999;
+            this.invalidate();
+            this.tui.requestRender();
+            return;
+        }
+        // Filter cycle
+        if (data === "f") {
+            this.filterIndex = (this.filterIndex + 1) % FILTER_CYCLE.length;
+            this.scrollOffset = 0;
+            this.invalidate();
+            this.tui.requestRender();
+            return;
+        }
+        // Clear all
+        if (data === "c") {
+            clearNotifications();
+            this.entries = [];
+            this.scrollOffset = 0;
+            this.invalidate();
+            this.tui.requestRender();
+            return;
+        }
+    }
+    render(width) {
+        if (this.cachedLines && this.cachedWidth === width) {
+            return this.cachedLines;
+        }
+        const content = this.buildContentLines(width);
+        const maxVisibleRows = Math.max(5, process.stdout.rows ? process.stdout.rows - 8 : 24) - 2;
+        const visibleContentRows = Math.min(content.length, maxVisibleRows);
+        const maxScroll = Math.max(0, content.length - visibleContentRows);
+        this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
+        const visibleContent = content.slice(this.scrollOffset, this.scrollOffset + visibleContentRows);
+        const lines = this.wrapInBox(visibleContent, width);
+        this.cachedWidth = width;
+        this.cachedLines = lines;
+        return lines;
+    }
+    invalidate() {
+        this.cachedLines = undefined;
+        this.cachedWidth = undefined;
+    }
+    dispose() {
+        this.disposed = true;
+        clearInterval(this.refreshTimer);
+        if (this.resizeHandler) {
+            process.stdout.removeListener("resize", this.resizeHandler);
+            this.resizeHandler = null;
+        }
+    }
+    wrapInBox(inner, width) {
+        const th = this.theme;
+        const border = (s) => th.fg("borderAccent", s);
+        const innerWidth = width - 4;
+        const lines = [];
+        lines.push(border("╭" + "─".repeat(width - 2) + "╮"));
+        for (const line of inner) {
+            const truncated = truncateToWidth(line, innerWidth);
+            const padWidth = Math.max(0, innerWidth - visibleWidth(truncated));
+            lines.push(border("│") + " " + truncated + " ".repeat(padWidth) + " " + border("│"));
+        }
+        lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
+        return lines;
+    }
+    buildContentLines(width) {
+        const th = this.theme;
+        const shellWidth = width - 4;
+        const contentWidth = Math.min(shellWidth, 128);
+        const sidePad = Math.max(0, Math.floor((shellWidth - contentWidth) / 2));
+        const leftMargin = " ".repeat(sidePad);
+        const lines = [];
+        const row = (content = "") => {
+            const truncated = truncateToWidth(content, contentWidth);
+            return leftMargin + padRight(truncated, contentWidth);
+        };
+        const blank = () => row("");
+        const hr = () => row(th.fg("dim", "─".repeat(contentWidth)));
+        // Header
+        const title = th.fg("accent", th.bold("Notifications"));
+        const filterLabel = this.filter === "all"
+            ? th.fg("dim", "all")
+            : th.fg(this.filter === "error" ? "error" : this.filter === "warning" ? "warning" : "dim", this.filter);
+        const count = `${this.filteredEntries.length} entries`;
+        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")));
+        lines.push(blank());
+        // Entries
+        const filtered = this.filteredEntries;
+        if (filtered.length === 0) {
+            lines.push(blank());
+            lines.push(row(th.fg("dim", this.entries.length === 0
+                ? "No notifications yet."
+                : `No ${this.filter} notifications.`)));
+            lines.push(blank());
+            return lines;
+        }
+        for (const entry of filtered) {
+            const icon = severityIcon(entry.severity);
+            const coloredIcon = entry.severity === "error" ? th.fg("error", icon)
+                : entry.severity === "warning" ? th.fg("warning", icon)
+                    : entry.severity === "success" ? th.fg("success", icon)
+                        : th.fg("dim", icon);
+            const time = th.fg("dim", formatTimestamp(entry.ts));
+            const source = entry.source === "workflow-logger" ? th.fg("dim", " [engine]") : "";
+            // Measure actual prefix width for wrapping
+            const prefix = `${coloredIcon} ${time}${source}  `;
+            const prefixWidth = visibleWidth(prefix);
+            const msgMaxWidth = Math.max(10, contentWidth - prefixWidth);
+            // Wrap long messages onto continuation lines indented to align with message start
+            const msgLines = wrapText(entry.message, msgMaxWidth);
+            const indent = " ".repeat(prefixWidth);
+            for (let i = 0; i < msgLines.length; i++) {
+                if (i === 0) {
+                    lines.push(row(`${prefix}${msgLines[i]}`));
+                }
+                else {
+                    lines.push(row(`${indent}${msgLines[i]}`));
+                }
+            }
+        }
+        return lines;
+    }
+}

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

@@ -0,0 +1,273 @@
+// GSD Extension — Persistent Notification Store
+// Captures all ctx.ui.notify() calls and workflow-logger warnings to
+// .gsd/notifications.jsonl so they survive context resets and session restarts.
+// Rotates at MAX_ENTRIES to prevent unbounded growth.
+import { appendFileSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+// ─── Constants ──────────────────────────────────────────────────────────
+const MAX_ENTRIES = 500;
+const FILENAME = "notifications.jsonl";
+const LOCKFILE = "notifications.lock";
+// ─── Module State ───────────────────────────────────────────────────────
+let _basePath = null;
+let _lineCount = 0; // Hint for rotation — not authoritative for public API
+let _suppressCount = 0;
+// ─── Public API ─────────────────────────────────────────────────────────
+/**
+ * Initialize the notification store. Call once at session start with the
+ * project root. Seeds in-memory counters from the existing file on disk.
+ */
+export function initNotificationStore(basePath) {
+    _basePath = basePath;
+    // Seed line count hint for rotation — public counters read from disk
+    _lineCount = _readEntriesFromDisk(basePath).length;
+}
+/**
+ * Append a notification entry to the store. Synchronous — safe to call
+ * from the notify() shim which is declared void (not async).
+ */
+export function appendNotification(message, severity, source = "notify") {
+    if (!_basePath)
+        return;
+    if (_suppressCount > 0)
+        return;
+    const entry = {
+        id: randomUUID(),
+        ts: new Date().toISOString(),
+        severity,
+        message: message.length > 500 ? message.slice(0, 500) + "…" : message,
+        source,
+        read: false,
+    };
+    try {
+        const dir = join(_basePath, ".gsd");
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, FILENAME), JSON.stringify(entry) + "\n", "utf-8");
+        _lineCount++;
+        // Rotate if hint suggests we're over limit
+        if (_lineCount > MAX_ENTRIES) {
+            _rotate();
+        }
+    }
+    catch {
+        // Non-fatal — never let persistence break the caller
+    }
+}
+/**
+ * Read all notification entries from disk. Returns newest-first.
+ */
+export function readNotifications(basePath) {
+    const bp = basePath ?? _basePath;
+    if (!bp)
+        return [];
+    return _readEntriesFromDisk(bp).reverse();
+}
+/**
+ * Mark all notifications as read. Atomic rewrite via temp-file + rename.
+ * Resyncs in-memory counters from disk after mutation.
+ */
+export function markAllRead(basePath) {
+    const bp = basePath ?? _basePath;
+    if (!bp)
+        return;
+    const entries = _readEntriesFromDisk(bp);
+    if (entries.length === 0)
+        return;
+    const hasUnread = entries.some((e) => !e.read);
+    if (!hasUnread)
+        return;
+    try {
+        _withLock(bp, () => {
+            // Re-read inside lock to get freshest state
+            const fresh = _readEntriesFromDisk(bp);
+            if (fresh.length === 0 || !fresh.some((e) => !e.read))
+                return;
+            const lines = fresh.map((e) => JSON.stringify({ ...e, read: true }));
+            _atomicWrite(bp, lines.join("\n") + "\n");
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+}
+/**
+ * Clear all notifications. Atomic write of empty content under lock.
+ */
+export function clearNotifications(basePath) {
+    const bp = basePath ?? _basePath;
+    if (!bp)
+        return;
+    try {
+        _withLock(bp, () => {
+            _atomicWrite(bp, "");
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+}
+/**
+ * Get the current unread count. Reads from disk to stay accurate across
+ * processes (web subprocess can clear/modify the file independently).
+ */
+export function getUnreadCount() {
+    if (!_basePath)
+        return 0;
+    try {
+        const entries = _readEntriesFromDisk(_basePath);
+        return entries.filter((e) => !e.read).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Get the total notification count. Reads from disk for cross-process accuracy.
+ */
+export function getLineCount() {
+    if (!_basePath)
+        return 0;
+    try {
+        return _readEntriesFromDisk(_basePath).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Temporarily suppress persistence. Use around ctx.ui.notify calls that
+ * should NOT be persisted (e.g., confirmation toasts after clear).
+ * Calls are ref-counted — nest safely.
+ */
+export function suppressPersistence() {
+    _suppressCount++;
+}
+export function unsuppressPersistence() {
+    _suppressCount = Math.max(0, _suppressCount - 1);
+}
+// ─── Test Helpers ───────────────────────────────────────────────────────
+/**
+ * Reset module state. Only for use in tests.
+ */
+export function _resetNotificationStore() {
+    _basePath = null;
+    _lineCount = 0;
+    _suppressCount = 0;
+}
+// ─── Internal ───────────────────────────────────────────────────────────
+function _readEntriesFromDisk(basePath) {
+    const filePath = join(basePath, ".gsd", FILENAME);
+    if (!existsSync(filePath))
+        return [];
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return content
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+    }
+    catch {
+        return [];
+    }
+}
+function _rotate() {
+    if (!_basePath)
+        return;
+    try {
+        _withLock(_basePath, () => {
+            // Re-read inside lock to get freshest state
+            const entries = _readEntriesFromDisk(_basePath);
+            if (entries.length <= MAX_ENTRIES)
+                return;
+            const trimmed = entries.slice(entries.length - MAX_ENTRIES);
+            const lines = trimmed.map((e) => JSON.stringify(e));
+            _atomicWrite(_basePath, lines.join("\n") + "\n");
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+}
+/**
+ * Atomic file rewrite via temp-file + rename. Prevents partial reads
+ * by other processes (web API subprocess, parallel workers).
+ * Must be called inside _withLock for cross-process safety.
+ */
+function _atomicWrite(basePath, content) {
+    const dir = join(basePath, ".gsd");
+    mkdirSync(dir, { recursive: true });
+    const target = join(dir, FILENAME);
+    const tmp = target + ".tmp." + process.pid;
+    writeFileSync(tmp, content, "utf-8");
+    renameSync(tmp, target);
+}
+/**
+ * Acquire an exclusive lockfile for rewrite operations.
+ * Uses O_CREAT|O_EXCL for atomic creation — if the file exists, another
+ * process holds the lock. Retries briefly, then proceeds anyway (best-effort)
+ * to avoid deadlocking the UI on a stale lock.
+ */
+function _withLock(basePath, fn) {
+    const lockPath = join(basePath, ".gsd", LOCKFILE);
+    let fd = null;
+    const maxAttempts = 5;
+    const retryMs = 20;
+    for (let i = 0; i < maxAttempts; i++) {
+        try {
+            mkdirSync(join(basePath, ".gsd"), { recursive: true });
+            fd = openSync(lockPath, "wx");
+            break;
+        }
+        catch (err) {
+            if (err?.code === "EEXIST") {
+                // Check if lock is stale (older than 5s)
+                try {
+                    const stat = readFileSync(lockPath, "utf-8");
+                    const lockTime = parseInt(stat, 10);
+                    if (Date.now() - lockTime > 5000) {
+                        try {
+                            unlinkSync(lockPath);
+                        }
+                        catch { /* race ok */ }
+                        continue;
+                    }
+                }
+                catch { /* can't read lock, retry */ }
+                // Wait and retry
+                const start = Date.now();
+                while (Date.now() - start < retryMs) { /* spin */ }
+                continue;
+            }
+            // Other error — proceed without lock
+            break;
+        }
+    }
+    // Only run the mutation if we actually own the lock
+    const ownsLock = fd !== null;
+    try {
+        if (ownsLock && fd !== null) {
+            // Write our PID timestamp into the lock for stale detection
+            writeFileSync(lockPath, String(Date.now()), "utf-8");
+            closeSync(fd);
+        }
+        return fn();
+    }
+    finally {
+        // Only delete the lock if we created it — never remove another process's lock
+        if (ownsLock) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}