gsd-pi 2.63.0-dev.d04bbc5 → 2.64.0-dev.6fe1e44

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -18,6 +18,7 @@ import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
 import {
   resolveSliceFile,
+  resolveSlicePath,
   resolveTaskFile,
   resolveMilestoneFile,
   resolveTasksDir,
@@ -59,6 +60,10 @@ import { validateFileChanges } from "./safety/file-change-validator.js";
 import { validateContent } from "./safety/content-validator.js";
 import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js";
 import { resolveExpectedArtifactPath as resolveArtifactForContent } from "./auto-artifact-paths.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getSliceTasks } from "./gsd-db.js";
+import { runPreExecutionChecks, type PreExecutionResult } from "./pre-execution-checks.js";
+import { writePreExecutionEvidence } from "./verification-evidence.js";
 
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
@@ -772,6 +777,123 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
     }
   }
 
+  // ── Pre-execution checks (after plan-slice completes) ──
+  if (
+    s.currentUnit &&
+    s.currentUnit.type === "plan-slice"
+  ) {
+    let preExecPauseNeeded = false;
+    await runSafely("postUnitPostVerification", "pre-execution-checks", async () => {
+      try {
+        // Check preferences — respect enhanced_verification and enhanced_verification_pre
+        const prefs = loadEffectiveGSDPreferences()?.preferences;
+        const enhancedEnabled = prefs?.enhanced_verification !== false; // default true
+        const preEnabled = prefs?.enhanced_verification_pre !== false;  // default true
+
+        if (!enhancedEnabled || !preEnabled) {
+          debugLog("postUnitPostVerification", {
+            phase: "pre-execution-checks",
+            skipped: true,
+            reason: "disabled by preferences",
+          });
+          return;
+        }
+
+        // Parse the unit ID to get milestone/slice IDs
+        const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit!.id);
+        if (!mid || !sid) {
+          debugLog("postUnitPostVerification", {
+            phase: "pre-execution-checks",
+            skipped: true,
+            reason: "could not parse milestone/slice from unit ID",
+          });
+          return;
+        }
+
+        // Get tasks for this slice from DB
+        const tasks = getSliceTasks(mid, sid);
+        if (tasks.length === 0) {
+          debugLog("postUnitPostVerification", {
+            phase: "pre-execution-checks",
+            skipped: true,
+            reason: "no tasks found for slice",
+          });
+          return;
+        }
+
+        // Run pre-execution checks
+        const result: PreExecutionResult = await runPreExecutionChecks(tasks, s.basePath);
+
+        // Log summary to stderr in existing verification output format
+        const emoji = result.status === "pass" ? "✅" : result.status === "warn" ? "⚠️" : "❌";
+        process.stderr.write(
+          `gsd-pre-exec: ${emoji} Pre-execution checks ${result.status} for ${mid}/${sid} (${result.durationMs}ms)\n`,
+        );
+
+        // Log individual check results
+        for (const check of result.checks) {
+          const checkEmoji = check.passed ? "✓" : check.blocking ? "✗" : "⚠";
+          process.stderr.write(
+            `gsd-pre-exec:   ${checkEmoji} [${check.category}] ${check.target}: ${check.message}\n`,
+          );
+        }
+
+        // Write evidence JSON to slice artifacts directory
+        const slicePath = resolveSlicePath(s.basePath, mid, sid);
+        if (slicePath) {
+          writePreExecutionEvidence(result, slicePath, mid, sid);
+        }
+
+        // Notify UI
+        if (result.status === "fail") {
+          const blockingCount = result.checks.filter(c => !c.passed && c.blocking).length;
+          ctx.ui.notify(
+            `Pre-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found`,
+            "error",
+          );
+          preExecPauseNeeded = true;
+        } else if (result.status === "warn") {
+          ctx.ui.notify(
+            `Pre-execution checks passed with warnings`,
+            "warning",
+          );
+          // Strict mode: treat warnings as blocking
+          if (prefs?.enhanced_verification_strict === true) {
+            preExecPauseNeeded = true;
+          }
+        }
+
+        debugLog("postUnitPostVerification", {
+          phase: "pre-execution-checks",
+          status: result.status,
+          checkCount: result.checks.length,
+          durationMs: result.durationMs,
+        });
+      } catch (preExecError) {
+        // Fail-closed: if runPreExecutionChecks throws, pause auto-mode instead of silently continuing
+        const errorMessage = preExecError instanceof Error ? preExecError.message : String(preExecError);
+        debugLog("postUnitPostVerification", {
+          phase: "pre-execution-checks",
+          error: errorMessage,
+          failClosed: true,
+        });
+        logError("engine", `gsd-pre-exec: Pre-execution checks threw an error: ${errorMessage}`);
+        ctx.ui.notify(
+          `Pre-execution checks error: ${errorMessage} — pausing for human review`,
+          "error",
+        );
+        preExecPauseNeeded = true;
+      }
+    });
+
+    // Check for blocking failures after runSafely completes
+    if (preExecPauseNeeded) {
+      debugLog("postUnitPostVerification", { phase: "pre-execution-checks", pausing: true, reason: "blocking failures detected" });
+      await pauseAuto(ctx, pi);
+      return "stopped";
+    }
+  }
+
   // ── Triage check ──
   if (
     !s.stepMode &&

package/src/resources/extensions/gsd/auto-verification.ts

@@ -11,9 +11,10 @@
  */
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { resolveSliceFile, resolveSlicePath } from "./paths.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getTask } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSliceTasks, type TaskRow } from "./gsd-db.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import {
   runVerificationGate,
@@ -21,9 +22,11 @@ import {
   captureRuntimeErrors,
   runDependencyAudit,
 } from "./verification-gate.js";
-import { writeVerificationJSON } from "./verification-evidence.js";
+import { writeVerificationJSON, type PostExecutionCheckJSON, type EvidenceJSON } from "./verification-evidence.js";
 import { logWarning } from "./workflow-logger.js";
+import { runPostExecutionChecks, type PostExecutionResult } from "./post-execution-checks.js";
 import type { AutoSession } from "./auto/session.js";
+import type { VerificationResult as VerificationGateResult } from "./types.js";
 import { join } from "node:path";
 
 export interface VerificationContext {
@@ -183,11 +186,140 @@ export async function runPostUnitVerification(
       return "continue";
     }
 
+    // ── Post-execution checks (run after main verification passes for execute-task units) ──
+    let postExecChecks: PostExecutionCheckJSON[] | undefined;
+    let postExecBlockingFailure = false;
+
+    if (result.passed && mid && sid && tid) {
+      // Check preferences — respect enhanced_verification and enhanced_verification_post
+      const enhancedEnabled = prefs?.enhanced_verification !== false; // default true
+      const postEnabled = prefs?.enhanced_verification_post !== false; // default true
+
+      if (enhancedEnabled && postEnabled && isDbAvailable()) {
+        try {
+          // Get the completed task from DB
+          const taskRow = getTask(mid, sid, tid);
+          if (taskRow && taskRow.key_files && taskRow.key_files.length > 0) {
+            // Get all tasks in the slice
+            const allTasks = getSliceTasks(mid, sid);
+            // Filter to prior completed tasks (status = 'complete' or 'done', before current task)
+            const priorTasks = allTasks.filter(
+              (t: TaskRow) =>
+                (t.status === "complete" || t.status === "done") &&
+                t.id !== tid &&
+                t.sequence < taskRow.sequence
+            );
+
+            // Run post-execution checks
+            const postExecResult: PostExecutionResult = runPostExecutionChecks(
+              taskRow,
+              priorTasks,
+              s.basePath
+            );
+
+            // Store checks for evidence JSON
+            postExecChecks = postExecResult.checks;
+
+            // Log summary to stderr with gsd-post-exec: prefix
+            const emoji =
+              postExecResult.status === "pass"
+                ? "✅"
+                : postExecResult.status === "warn"
+                  ? "⚠️"
+                  : "❌";
+            process.stderr.write(
+              `gsd-post-exec: ${emoji} Post-execution checks ${postExecResult.status} for ${mid}/${sid}/${tid} (${postExecResult.durationMs}ms)\n`
+            );
+
+            // Log individual check results
+            for (const check of postExecResult.checks) {
+              const checkEmoji = check.passed
+                ? "✓"
+                : check.blocking
+                  ? "✗"
+                  : "⚠";
+              process.stderr.write(
+                `gsd-post-exec:   ${checkEmoji} [${check.category}] ${check.target}: ${check.message}\n`
+              );
+            }
+
+            // Check for blocking failures
+            if (postExecResult.status === "fail") {
+              postExecBlockingFailure = true;
+              const blockingCount = postExecResult.checks.filter(
+                (c) => !c.passed && c.blocking
+              ).length;
+              ctx.ui.notify(
+                `Post-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found`,
+                "error"
+              );
+            } else if (postExecResult.status === "warn") {
+              ctx.ui.notify(
+                `Post-execution checks passed with warnings`,
+                "warning"
+              );
+              // Strict mode: treat warnings as blocking
+              if (prefs?.enhanced_verification_strict === true) {
+                postExecBlockingFailure = true;
+              }
+            }
+          }
+        } catch (postExecErr) {
+          // Post-execution check errors are non-fatal — log and continue
+          logWarning("engine", `gsd-post-exec: error — ${(postExecErr as Error).message}`);
+        }
+      }
+    }
+
+    // Re-write verification evidence JSON with post-execution checks
+    if (postExecChecks && postExecChecks.length > 0 && mid && sid && tid) {
+      try {
+        const sDir = resolveSlicePath(s.basePath, mid, sid);
+        if (sDir) {
+          const tasksDir = join(sDir, "tasks");
+          // Add postExecutionChecks to the result for the JSON write
+          const resultWithPostExec = {
+            ...result,
+            // Mark as failed if there was a blocking post-exec failure
+            passed: result.passed && !postExecBlockingFailure,
+          };
+          // Manually write with postExecutionChecks field
+          writeVerificationJSONWithPostExec(
+            resultWithPostExec,
+            tasksDir,
+            tid,
+            s.currentUnit.id,
+            postExecChecks,
+            postExecBlockingFailure ? attempt + 1 : undefined,
+            postExecBlockingFailure ? maxRetries : undefined
+          );
+        }
+      } catch (evidenceErr) {
+        logWarning("engine", `verification-evidence: post-exec write error — ${(evidenceErr as Error).message}`);
+      }
+    }
+
+    // Update result.passed based on post-execution checks
+    if (postExecBlockingFailure) {
+      result.passed = false;
+    }
+
     // ── Auto-fix retry logic ──
     if (result.passed) {
       s.verificationRetryCount.delete(s.currentUnit.id);
       s.pendingVerificationRetry = null;
       return "continue";
+    } else if (postExecBlockingFailure) {
+      // Post-execution failures are cross-task consistency issues — retrying the same task won't fix them.
+      // Skip retry and pause immediately for human review.
+      s.verificationRetryCount.delete(s.currentUnit.id);
+      s.pendingVerificationRetry = null;
+      ctx.ui.notify(
+        `Post-execution checks failed — cross-task consistency issue detected, pausing for human review`,
+        "error",
+      );
+      await pauseAuto(ctx, pi);
+      return "pause";
     } else if (autoFixEnabled && attempt + 1 <= maxRetries) {
       const nextAttempt = attempt + 1;
       s.verificationRetryCount.set(s.currentUnit.id, nextAttempt);
@@ -231,3 +363,59 @@ export async function runPostUnitVerification(
     return "continue";
   }
 }
+
+/**
+ * Write verification evidence JSON with post-execution checks included.
+ * This is a variant of writeVerificationJSON that adds the postExecutionChecks field.
+ */
+function writeVerificationJSONWithPostExec(
+  result: VerificationGateResult,
+  tasksDir: string,
+  taskId: string,
+  unitId: string,
+  postExecutionChecks: PostExecutionCheckJSON[],
+  retryAttempt?: number,
+  maxRetries?: number,
+): void {
+  mkdirSync(tasksDir, { recursive: true });
+
+  const evidence: EvidenceJSON = {
+    schemaVersion: 1,
+    taskId,
+    unitId: unitId ?? taskId,
+    timestamp: result.timestamp,
+    passed: result.passed,
+    discoverySource: result.discoverySource,
+    checks: result.checks.map((check) => ({
+      command: check.command,
+      exitCode: check.exitCode,
+      durationMs: check.durationMs,
+      verdict: check.exitCode === 0 ? "pass" : "fail",
+    })),
+    ...(retryAttempt !== undefined ? { retryAttempt } : {}),
+    ...(maxRetries !== undefined ? { maxRetries } : {}),
+    postExecutionChecks,
+  };
+
+  if (result.runtimeErrors && result.runtimeErrors.length > 0) {
+    evidence.runtimeErrors = result.runtimeErrors.map(e => ({
+      source: e.source,
+      severity: e.severity,
+      message: e.message,
+      blocking: e.blocking,
+    }));
+  }
+
+  if (result.auditWarnings && result.auditWarnings.length > 0) {
+    evidence.auditWarnings = result.auditWarnings.map(w => ({
+      name: w.name,
+      severity: w.severity,
+      title: w.title,
+      url: w.url,
+      fixAvailable: w.fixAvailable,
+    }));
+  }
+
+  const filePath = join(tasksDir, `${taskId}-VERIFY.json`);
+  writeFileSync(filePath, JSON.stringify(evidence, null, 2) + "\n", "utf-8");
+}

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

@@ -895,6 +895,7 @@ export async function pauseAuto(
       sessionFile: s.pausedSessionFile,
       activeEngineId: s.activeEngineId,
       activeRunDir: s.activeRunDir,
+      autoStartTime: s.autoStartTime,
     };
     const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
     mkdirSync(runtimeDir, { recursive: true });
@@ -1137,6 +1138,7 @@ export async function startAuto(
           s.activeRunDir = meta.activeRunDir ?? null;
           s.originalBasePath = meta.originalBasePath || base;
           s.stepMode = meta.stepMode ?? requestedStepMode;
+          s.autoStartTime = meta.autoStartTime || Date.now();
           s.paused = true;
           try { unlinkSync(pausedPath); } catch (err) { /* non-fatal */
             logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
@@ -1162,6 +1164,7 @@ export async function startAuto(
             s.currentMilestoneId = meta.milestoneId;
             s.originalBasePath = meta.originalBasePath || base;
             s.stepMode = meta.stepMode ?? requestedStepMode;
+            s.autoStartTime = meta.autoStartTime || Date.now();
             s.paused = true;
             // Clean up the persisted file — we're consuming it
             try { unlinkSync(pausedPath); } catch (err) { /* non-fatal */
@@ -1194,6 +1197,7 @@ export async function startAuto(
     s.cmdCtx = ctx;
     s.basePath = base;
     setLogBasePath(base);
+    if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now();
     s.unitDispatchCount.clear();
     s.unitLifetimeDispatches.clear();
     if (!getLedger()) initMetrics(base);

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

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

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

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

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

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

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -48,6 +48,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
   { cmd: "run-hook", desc: "Manually trigger a specific hook" },
   { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
+  { cmd: "notifications", desc: "View, filter, and clear persistent notification history" },
   { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
   { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
   { cmd: "forensics", desc: "Examine execution logs" },
@@ -110,6 +111,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "keys", desc: "Manage API keys" },
     { cmd: "prefs", desc: "Configure global preferences" },
   ],
+  notifications: [
+    { cmd: "clear", desc: "Clear all notifications" },
+    { cmd: "tail", desc: "Show last N notifications (default: 20)" },
+    { cmd: "filter", desc: "Filter by severity (error|warning|info|success)" },
+  ],
   logs: [
     { cmd: "debug", desc: "List or view debug log files" },
     { cmd: "tail", desc: "Show last N activity log summaries" },

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

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

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

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