gsd-pi 2.74.0 → 2.75.0-dev.fd2382b9f

package/src/resources/extensions/gsd/commands-backlog.ts

@@ -0,0 +1,182 @@
+/**
+ * GSD Command — /gsd backlog
+ *
+ * Structured backlog management with 999.x numbering.
+ * Items stored in .gsd/BACKLOG.md as markdown checklist.
+ * Items can be promoted to active slices via add-slice.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+import { gsdRoot } from "./paths.js";
+
+interface BacklogItem {
+  id: string;
+  title: string;
+  done: boolean;
+  note: string;
+}
+
+function backlogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "BACKLOG.md");
+}
+
+function parseBacklog(basePath: string): BacklogItem[] {
+  const filePath = backlogPath(basePath);
+  if (!existsSync(filePath)) return [];
+
+  const content = readFileSync(filePath, "utf-8");
+  const items: BacklogItem[] = [];
+
+  for (const line of content.split("\n")) {
+    const match = line.match(/^- \[([ x])\] (999\.\d+) — (.+?)(?:\s*\((.+)\))?$/);
+    if (match) {
+      items.push({
+        id: match[2],
+        title: match[3].trim(),
+        done: match[1] === "x",
+        note: match[4] ?? "",
+      });
+    }
+  }
+
+  return items;
+}
+
+function writeBacklog(basePath: string, items: BacklogItem[]): void {
+  const filePath = backlogPath(basePath);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const lines = ["# Backlog\n"];
+  for (const item of items) {
+    const check = item.done ? "x" : " ";
+    const note = item.note ? ` (${item.note})` : "";
+    lines.push(`- [${check}] ${item.id} — ${item.title}${note}`);
+  }
+  lines.push(""); // trailing newline
+  writeFileSync(filePath, lines.join("\n"), "utf-8");
+}
+
+function nextBacklogId(items: BacklogItem[]): string {
+  let maxNum = 0;
+  for (const item of items) {
+    const match = item.id.match(/^999\.(\d+)$/);
+    if (match) {
+      const num = parseInt(match[1], 10);
+      if (num > maxNum) maxNum = num;
+    }
+  }
+  return `999.${maxNum + 1}`;
+}
+
+async function listBacklog(basePath: string, ctx: ExtensionCommandContext): Promise<void> {
+  const items = parseBacklog(basePath);
+  if (items.length === 0) {
+    ctx.ui.notify("Backlog is empty. Add items with /gsd backlog add <title>", "info");
+    return;
+  }
+
+  const lines = ["Backlog:\n"];
+  for (const item of items) {
+    const status = item.done ? "✓" : "○";
+    const note = item.note ? ` (${item.note})` : "";
+    lines.push(`  ${status} ${item.id} — ${item.title}${note}`);
+  }
+  const pending = items.filter((i) => !i.done).length;
+  lines.push(`\n${pending} pending, ${items.length - pending} promoted/done`);
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+async function addBacklogItem(basePath: string, title: string, ctx: ExtensionCommandContext): Promise<void> {
+  if (!title) {
+    ctx.ui.notify("Usage: /gsd backlog add <title>", "warning");
+    return;
+  }
+
+  const items = parseBacklog(basePath);
+  const id = nextBacklogId(items);
+  const date = new Date().toISOString().slice(0, 10);
+
+  items.push({ id, title: title.replace(/^['"]|['"]$/g, ""), done: false, note: `added ${date}` });
+  writeBacklog(basePath, items);
+
+  ctx.ui.notify(`Added ${id}: "${title}"`, "success");
+}
+
+async function promoteBacklogItem(
+  basePath: string,
+  itemId: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  if (!itemId) {
+    ctx.ui.notify("Usage: /gsd backlog promote <id>\nExample: /gsd backlog promote 999.1", "warning");
+    return;
+  }
+
+  const items = parseBacklog(basePath);
+  const item = items.find((i) => i.id === itemId);
+
+  if (!item) {
+    ctx.ui.notify(`Backlog item ${itemId} not found.`, "warning");
+    return;
+  }
+
+  if (item.done) {
+    ctx.ui.notify(`${itemId} is already promoted/done.`, "info");
+    return;
+  }
+
+  // Promote — currently requires single-writer engine (not yet available)
+  // Mark as promoted in backlog for now; slice creation will be available with the engine.
+  item.done = true;
+  item.note = `promoted ${new Date().toISOString().slice(0, 10)}`;
+  writeBacklog(basePath, items);
+  ctx.ui.notify(`Promoted ${itemId}: "${item.title}" — add it to the roadmap manually or wait for engine slice commands.`, "info");
+}
+
+async function removeBacklogItem(basePath: string, itemId: string, ctx: ExtensionCommandContext): Promise<void> {
+  if (!itemId) {
+    ctx.ui.notify("Usage: /gsd backlog remove <id>", "warning");
+    return;
+  }
+
+  const items = parseBacklog(basePath);
+  const idx = items.findIndex((i) => i.id === itemId);
+
+  if (idx === -1) {
+    ctx.ui.notify(`Backlog item ${itemId} not found.`, "warning");
+    return;
+  }
+
+  const removed = items.splice(idx, 1)[0];
+  writeBacklog(basePath, items);
+  ctx.ui.notify(`Removed ${removed.id}: "${removed.title}"`, "success");
+}
+
+export async function handleBacklog(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const basePath = process.cwd();
+  const parts = args.trim().split(/\s+/);
+  const sub = parts[0] ?? "";
+  const rest = parts.slice(1).join(" ");
+
+  switch (sub) {
+    case "":
+      return listBacklog(basePath, ctx);
+    case "add":
+      return addBacklogItem(basePath, rest, ctx);
+    case "promote":
+      return promoteBacklogItem(basePath, rest.trim(), ctx, pi);
+    case "remove":
+      return removeBacklogItem(basePath, rest.trim(), ctx);
+    default:
+      // Treat as implicit add
+      return addBacklogItem(basePath, args, ctx);
+  }
+}

package/src/resources/extensions/gsd/commands-cmux.ts

@@ -15,7 +15,7 @@ import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./comm
  * Returns true if preferences were written, false if skipped.
  */
 export function autoEnableCmuxPreferences(): boolean {
-  const path = getProjectGSDPreferencesPath();
+  const path = resolveProjectPreferencesWritePath();
   if (!existsSync(path)) return false;
 
   const existing = loadProjectGSDPreferences();
@@ -53,7 +53,7 @@ async function writeProjectCmuxPreferences(
   ctx: ExtensionCommandContext,
   updater: (prefs: Record<string, unknown>) => void,
 ): Promise<void> {
-  const path = getProjectGSDPreferencesPath();
+  const path = resolveProjectPreferencesWritePath();
   await ensurePreferencesFile(path, ctx, "project");
 
   const existing = loadProjectGSDPreferences();
@@ -73,6 +73,10 @@ async function writeProjectCmuxPreferences(
   await ctx.reload();
 }
 
+function resolveProjectPreferencesWritePath(): string {
+  return loadProjectGSDPreferences()?.path ?? getProjectGSDPreferencesPath();
+}
+
 function formatCmuxStatus(): string {
   const loaded = loadEffectiveGSDPreferences();
   const detected = detectCmuxEnvironment();

package/src/resources/extensions/gsd/commands-debug.ts

@@ -0,0 +1,484 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import {
+  assertValidDebugSessionSlug,
+  createDebugSession,
+  listDebugSessions,
+  loadDebugSession,
+  updateDebugSession,
+  type DebugTddGate,
+  type DebugSpecialistReview,
+} from "./debug-session-store.js";
+import { loadPrompt } from "./prompt-loader.js";
+
+export type DebugCommandIntent
+  = { type: "usage" }
+  | { type: "issue-start"; issue: string }
+  | { type: "list" }
+  | { type: "status"; slug: string }
+  | { type: "continue"; slug: string }
+  | { type: "diagnose"; slug?: string }
+  | { type: "diagnose-issue"; issue: string }
+  | { type: "error"; message: string };
+
+const SUBCOMMANDS = new Set(["list", "status", "continue", "--diagnose"]);
+
+function isValidSlugCandidate(input: string): boolean {
+  try {
+    assertValidDebugSessionSlug(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function formatSessionLine(prefix: string, session: {
+  slug: string;
+  mode: string;
+  status: string;
+  phase: string;
+  issue: string;
+  updatedAt: number;
+}): string {
+  return `${prefix} ${session.slug} [mode=${session.mode} status=${session.status} phase=${session.phase}] — ${session.issue} (updated ${new Date(session.updatedAt).toISOString()})`;
+}
+
+function usageText(): string {
+  return [
+    "Usage: /gsd debug <issue-text>",
+    "       /gsd debug list",
+    "       /gsd debug status <slug>",
+    "       /gsd debug continue <slug>",
+    "       /gsd debug --diagnose [<slug> | <issue text>]",
+  ].join("\n");
+}
+
+export function parseDebugCommand(args: string): DebugCommandIntent {
+  const raw = args.trim();
+  if (!raw) return { type: "usage" };
+
+  const parts = raw.split(/\s+/).filter(Boolean);
+  const head = parts[0] ?? "";
+
+  if (head === "list") {
+    // Strict match only; otherwise treat as issue text for deterministic fallback behavior.
+    if (parts.length === 1) return { type: "list" };
+    return { type: "issue-start", issue: raw };
+  }
+
+  if (head === "status") {
+    if (parts.length === 1) return { type: "error", message: "Missing slug. Usage: /gsd debug status <slug>" };
+    if (parts.length === 2 && isValidSlugCandidate(parts[1])) return { type: "status", slug: parts[1] };
+    return { type: "issue-start", issue: raw };
+  }
+
+  if (head === "continue") {
+    if (parts.length === 1) return { type: "error", message: "Missing slug. Usage: /gsd debug continue <slug>" };
+    if (parts.length === 2 && isValidSlugCandidate(parts[1])) return { type: "continue", slug: parts[1] };
+    return { type: "issue-start", issue: raw };
+  }
+
+  if (head === "--diagnose") {
+    if (parts.length === 1) return { type: "diagnose" };
+    if (parts.length === 2 && isValidSlugCandidate(parts[1])) return { type: "diagnose", slug: parts[1] };
+    if (parts.length >= 3) return { type: "diagnose-issue", issue: parts.slice(1).join(" ") };
+    return { type: "error", message: "Invalid diagnose target. Usage: /gsd debug --diagnose [<slug> | <issue text>]" };
+  }
+
+  if (head.startsWith("-") && !SUBCOMMANDS.has(head)) {
+    return { type: "error", message: `Unknown debug flag: ${head}.\n${usageText()}` };
+  }
+
+  return { type: "issue-start", issue: raw };
+}
+
+export async function handleDebug(args: string, ctx: ExtensionCommandContext, pi?: ExtensionAPI): Promise<void> {
+  const parsed = parseDebugCommand(args);
+  const basePath = process.cwd();
+
+  if (parsed.type === "usage") {
+    ctx.ui.notify(usageText(), "info");
+    return;
+  }
+
+  if (parsed.type === "error") {
+    ctx.ui.notify(parsed.message, "warning");
+    return;
+  }
+
+  if (parsed.type === "issue-start") {
+    const issue = parsed.issue.trim();
+    if (!issue) {
+      ctx.ui.notify(`Issue text is required.\n${usageText()}`, "warning");
+      return;
+    }
+
+    try {
+      const created = createDebugSession(basePath, { issue });
+      const s = created.session;
+      ctx.ui.notify(
+        [
+          `Debug session started: ${s.slug}`,
+          formatSessionLine("Session:", s),
+          `Artifact: ${created.artifactPath}`,
+          `Log: ${s.logPath}`,
+          `Next: /gsd debug status ${s.slug} or /gsd debug continue ${s.slug}`,
+        ].join("\n"),
+        "info",
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(
+        `Unable to create debug session: ${message}\nTry /gsd debug --diagnose for artifact health details.`,
+        "error",
+      );
+    }
+    return;
+  }
+
+  if (parsed.type === "list") {
+    try {
+      const listed = listDebugSessions(basePath);
+      if (listed.sessions.length === 0 && listed.malformed.length === 0) {
+        ctx.ui.notify("No debug sessions found. Start one with: /gsd debug <issue-text>", "info");
+        return;
+      }
+
+      const lines: string[] = [];
+      if (listed.sessions.length > 0) {
+        lines.push("Debug sessions:");
+        for (const record of listed.sessions) {
+          lines.push(formatSessionLine("  -", record.session));
+        }
+      }
+
+      if (listed.malformed.length > 0) {
+        lines.push("");
+        lines.push(`Malformed artifacts: ${listed.malformed.length}`);
+        for (const bad of listed.malformed.slice(0, 5)) {
+          lines.push(`  - ${bad.artifactPath} :: ${bad.message}`);
+        }
+        if (listed.malformed.length > 5) {
+          lines.push(`  ... and ${listed.malformed.length - 5} more`);
+        }
+        lines.push("Run /gsd debug --diagnose for remediation guidance.");
+      }
+
+      ctx.ui.notify(lines.join("\n"), "info");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(
+        `Unable to list debug sessions: ${message}\nRun /gsd debug --diagnose for details.`,
+        "warning",
+      );
+    }
+    return;
+  }
+
+  if (parsed.type === "status") {
+    try {
+      const loaded = loadDebugSession(basePath, parsed.slug);
+      if (!loaded) {
+        ctx.ui.notify(
+          `Unknown debug session slug '${parsed.slug}'. Run /gsd debug list to see available sessions.`,
+          "warning",
+        );
+        return;
+      }
+
+      const s = loaded.session;
+      ctx.ui.notify(
+        [
+          `Debug session status: ${s.slug}`,
+          `mode=${s.mode}`,
+          `status=${s.status}`,
+          `phase=${s.phase}`,
+          `issue=${s.issue}`,
+          `artifact=${loaded.artifactPath}`,
+          `log=${s.logPath}`,
+          `updated=${new Date(s.updatedAt).toISOString()}`,
+          `lastError=${s.lastError ?? "none"}`,
+        ].join("\n"),
+        "info",
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(
+        `Unable to load debug session '${parsed.slug}': ${message}\nTry /gsd debug --diagnose ${parsed.slug}`,
+        "warning",
+      );
+    }
+    return;
+  }
+
+  if (parsed.type === "continue") {
+    try {
+      const loaded = loadDebugSession(basePath, parsed.slug);
+      if (!loaded) {
+        ctx.ui.notify(
+          `Unknown debug session slug '${parsed.slug}'. Run /gsd debug list to see available sessions.`,
+          "warning",
+        );
+        return;
+      }
+
+      if (loaded.session.status === "resolved") {
+        ctx.ui.notify(
+          `Session '${parsed.slug}' is resolved. Open a new session with /gsd debug <issue-text> for follow-up work.`,
+          "warning",
+        );
+        return;
+      }
+
+      // Determine checkpoint/TDD/specialist dispatch context before updating session state.
+      const checkpoint = loaded.session.checkpoint;
+      const tddGate = loaded.session.tddGate;
+      const specialistReview: DebugSpecialistReview | null | undefined = loaded.session.specialistReview;
+      const hasCheckpoint = checkpoint != null && checkpoint.awaitingResponse;
+      const hasTddGate = tddGate != null && tddGate.enabled;
+
+      let dispatchTemplate = "debug-diagnose";
+      let goal = "find_and_fix";
+      let dispatchModeLabel = "find_and_fix";
+      let checkpointContext = "";
+      let tddContext = "";
+      let specialistContext = "";
+      let tddGateUpdate: DebugTddGate | undefined;
+
+      if (hasCheckpoint || hasTddGate) {
+        dispatchTemplate = "debug-session-manager";
+
+        if (hasCheckpoint) {
+          const cpLines = [
+            `## Active Checkpoint`,
+            `- type: ${checkpoint.type}`,
+            `- summary: ${checkpoint.summary}`,
+          ];
+          if (checkpoint.userResponse) {
+            cpLines.push(`- userResponse:\n\nDATA_START\n${checkpoint.userResponse}\nDATA_END`);
+          } else {
+            cpLines.push(`- awaitingResponse: true`);
+          }
+          checkpointContext = cpLines.join("\n");
+          dispatchModeLabel = `checkpointType=${checkpoint.type}`;
+        }
+
+        if (hasTddGate) {
+          if (tddGate.phase === "red") {
+            goal = "find_and_fix";
+            const tddLines = [
+              `## TDD Gate`,
+              `- phase: red → green`,
+            ];
+            if (tddGate.testFile) tddLines.push(`- testFile: ${tddGate.testFile}`);
+            if (tddGate.testName) tddLines.push(`- testName: ${tddGate.testName}`);
+            if (tddGate.failureOutput) tddLines.push(`- failureOutput:\n${tddGate.failureOutput}`);
+            tddLines.push(`The failing test has been confirmed. Proceed to implement the fix that makes this test pass.`);
+            tddContext = tddLines.join("\n");
+            tddGateUpdate = { ...tddGate, phase: "green" };
+            dispatchModeLabel = "tddPhase=red→green";
+          } else if (tddGate.phase === "green") {
+            goal = "find_and_fix";
+            const tddLines = [
+              `## TDD Gate`,
+              `- phase: green`,
+            ];
+            if (tddGate.testFile) tddLines.push(`- testFile: ${tddGate.testFile}`);
+            if (tddGate.testName) tddLines.push(`- testName: ${tddGate.testName}`);
+            tddLines.push(`The test is now passing. Continue verifying the fix.`);
+            tddContext = tddLines.join("\n");
+            dispatchModeLabel = "tddPhase=green";
+          } else {
+            // phase === "pending": investigate only, do not fix yet
+            goal = "find_root_cause_only";
+            const tddLines = [
+              `## TDD Gate`,
+              `- phase: pending`,
+              `TDD mode is active. Write a failing test that captures this bug first. Do NOT fix the issue yet.`,
+            ];
+            if (tddGate.testFile) tddLines.push(`- testFile: ${tddGate.testFile}`);
+            tddContext = tddLines.join("\n");
+            dispatchModeLabel = "tddPhase=pending";
+          }
+        } else {
+          // Checkpoint only, no TDD gate — apply fix after human response
+          goal = "find_and_fix";
+        }
+      }
+
+      // Build specialistContext from session's specialistReview field (null/undefined → empty string).
+      if (specialistReview != null) {
+        specialistContext = [
+          `## Prior Specialist Review`,
+          `- hint: ${specialistReview.hint}`,
+          `- skill: ${specialistReview.skill ?? ""}`,
+          `- verdict: ${specialistReview.verdict}`,
+          `- detail: ${specialistReview.detail}`,
+        ].join("\n");
+        dispatchModeLabel += ` specialistHint=${specialistReview.hint}`;
+      }
+
+      // Update session state BEFORE dispatch — handler returns after sendMessage.
+      const resumed = updateDebugSession(basePath, parsed.slug, {
+        status: "active",
+        phase: "continued",
+        lastError: null,
+        ...(tddGateUpdate !== undefined ? { tddGate: tddGateUpdate } : {}),
+      });
+
+      const canDispatch = pi != null && typeof (pi as ExtensionAPI).sendMessage === "function";
+      const dispatchNote = canDispatch ? `\ndispatchMode=${dispatchModeLabel}` : "";
+      ctx.ui.notify(
+        [
+          `Resumed debug session: ${resumed.session.slug}`,
+          formatSessionLine("Session:", resumed.session),
+          `Log: ${resumed.session.logPath}`,
+          `Next: /gsd debug status ${resumed.session.slug}`,
+        ].join("\n") + dispatchNote,
+        "info",
+      );
+
+      if (canDispatch) {
+        try {
+          const promptVars: Record<string, string> = {
+            goal,
+            issue: resumed.session.issue,
+            slug: resumed.session.slug,
+            mode: resumed.session.mode,
+            workingDirectory: basePath,
+          };
+          if (dispatchTemplate === "debug-session-manager") {
+            promptVars.checkpointContext = checkpointContext;
+            promptVars.tddContext = tddContext;
+            promptVars.specialistContext = specialistContext;
+          }
+          const prompt = loadPrompt(dispatchTemplate, promptVars);
+          pi.sendMessage(
+            { customType: "gsd-debug-continue", content: prompt, display: false },
+            { triggerTurn: true },
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          ctx.ui.notify(
+            `Continue dispatch failed: ${msg}\nSession '${resumed.session.slug}' is persisted; retry with /gsd debug continue ${resumed.session.slug}`,
+            "warning",
+          );
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(
+        `Unable to continue debug session '${parsed.slug}': ${message}\nTry /gsd debug --diagnose ${parsed.slug}`,
+        "warning",
+      );
+    }
+    return;
+  }
+
+  if (parsed.type === "diagnose-issue") {
+    const issue = parsed.issue.trim();
+    if (!issue) {
+      ctx.ui.notify(`Issue text is required.\n${usageText()}`, "warning");
+      return;
+    }
+
+    try {
+      const created = createDebugSession(basePath, { issue, mode: "diagnose" });
+      const s = created.session;
+      ctx.ui.notify(
+        [
+          `Diagnose session started: ${s.slug}`,
+          formatSessionLine("Session:", s),
+          `Artifact: ${created.artifactPath}`,
+          `Log: ${s.logPath}`,
+          `dispatchMode=find_root_cause_only`,
+          `Next: /gsd debug status ${s.slug} or /gsd debug --diagnose ${s.slug}`,
+        ].join("\n"),
+        "info",
+      );
+
+      if (pi && typeof pi.sendMessage === "function") {
+        try {
+          const prompt = loadPrompt("debug-diagnose", {
+            goal: "find_root_cause_only",
+            issue: s.issue,
+            slug: s.slug,
+            mode: s.mode,
+            workingDirectory: basePath,
+          });
+          pi.sendMessage(
+            { customType: "gsd-debug-diagnose", content: prompt, display: false },
+            { triggerTurn: true },
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          ctx.ui.notify(
+            `Diagnose dispatch failed: ${msg}\nSession '${s.slug}' is persisted; continue manually with /gsd debug continue ${s.slug}`,
+            "warning",
+          );
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(
+        `Unable to create diagnose session: ${message}\nTry /gsd debug --diagnose for artifact health details.`,
+        "error",
+      );
+    }
+    return;
+  }
+
+  if (parsed.type === "diagnose") {
+    try {
+      const listed = listDebugSessions(basePath);
+
+      if (parsed.slug) {
+        const loaded = loadDebugSession(basePath, parsed.slug);
+        if (!loaded) {
+          ctx.ui.notify(
+            `Diagnose: session '${parsed.slug}' not found.\nRun /gsd debug list to discover valid slugs.`,
+            "warning",
+          );
+          return;
+        }
+
+        const s = loaded.session;
+        ctx.ui.notify(
+          [
+            `Diagnose session: ${s.slug}`,
+            `mode=${s.mode}`,
+            `status=${s.status}`,
+            `phase=${s.phase}`,
+            `artifact=${loaded.artifactPath}`,
+            `log=${s.logPath}`,
+            `lastError=${s.lastError ?? "none"}`,
+            `malformedArtifactsInStore=${listed.malformed.length}`,
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+
+      const lines = [
+        "Debug session diagnostics:",
+        `healthySessions=${listed.sessions.length}`,
+        `malformedArtifacts=${listed.malformed.length}`,
+      ];
+
+      if (listed.malformed.length > 0) {
+        lines.push("");
+        lines.push("Malformed artifacts (first 10):");
+        for (const malformed of listed.malformed.slice(0, 10)) {
+          lines.push(`  - ${malformed.artifactPath}`);
+          lines.push(`    ${malformed.message}`);
+        }
+        lines.push("Remediation: repair/remove malformed JSON artifacts under .gsd/debug/sessions/.");
+      }
+
+      ctx.ui.notify(lines.join("\n"), listed.malformed.length > 0 ? "warning" : "info");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Diagnose failed: ${message}`, "error");
+    }
+  }
+}