gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/src/resources/extensions/gsd/commands-pr-branch.ts

@@ -0,0 +1,234 @@
+/**
+ * GSD Command — /gsd pr-branch
+ *
+ * Creates a clean PR branch by cherry-picking commits while stripping
+ * any changes to .gsd/, .planning/, and PLAN.md paths. Useful for
+ * upstream PRs where planning artifacts should not be included.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { execFileSync } from "node:child_process";
+
+import {
+  nativeGetCurrentBranch,
+  nativeDetectMainBranch,
+  nativeBranchExists,
+} from "./native-git-bridge.js";
+
+const EXCLUDED_PATHS = [".gsd", ".planning", "PLAN.md"] as const;
+
+function git(basePath: string, args: readonly string[]): string {
+  return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
+}
+
+function gitAllowFail(basePath: string, args: readonly string[]): void {
+  try {
+    execFileSync("git", args, { cwd: basePath, encoding: "utf-8", stdio: "pipe" });
+  } catch {
+    // ignored — caller opts into non-fatal behavior
+  }
+}
+
+function hasStagedChanges(basePath: string): boolean {
+  try {
+    execFileSync("git", ["diff", "--cached", "--quiet"], {
+      cwd: basePath,
+      stdio: "pipe",
+    });
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function isValidBranchName(name: string): boolean {
+  try {
+    execFileSync("git", ["check-ref-format", "--branch", name], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCodeOnlyCommits(basePath: string, base: string, head: string): string[] {
+  try {
+    const allCommits = git(basePath, ["log", "--format=%H", `${base}..${head}`])
+      .split("\n")
+      .filter(Boolean);
+    const codeCommits: string[] = [];
+
+    for (const sha of allCommits) {
+      const files = git(basePath, ["diff-tree", "--no-commit-id", "--name-only", "-r", sha])
+        .split("\n")
+        .filter(Boolean);
+      const hasCodeChanges = files.some(
+        (f) => !f.startsWith(".gsd/") && !f.startsWith(".planning/") && f !== "PLAN.md",
+      );
+      if (hasCodeChanges) {
+        codeCommits.push(sha);
+      }
+    }
+
+    return codeCommits.reverse(); // chronological for cherry-picking
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Cherry-pick a commit while stripping excluded paths from the resulting
+ * commit. Returns true if a commit was produced, false if nothing remained
+ * after filtering.
+ */
+function cherryPickFiltered(basePath: string, sha: string): boolean {
+  git(basePath, ["cherry-pick", "--no-commit", "--allow-empty", sha]);
+
+  // Unstage any excluded paths introduced by the cherry-pick.
+  gitAllowFail(basePath, ["reset", "HEAD", "--", ...EXCLUDED_PATHS]);
+
+  // Restore worktree state for excluded paths from HEAD (if tracked),
+  // then remove any newly introduced untracked files under those paths.
+  gitAllowFail(basePath, ["checkout", "HEAD", "--", ...EXCLUDED_PATHS]);
+  gitAllowFail(basePath, ["clean", "-fdq", "--", ...EXCLUDED_PATHS]);
+
+  if (!hasStagedChanges(basePath)) {
+    // Nothing remained after filtering — discard worktree residue and skip.
+    git(basePath, ["reset", "--hard", "HEAD"]);
+    return false;
+  }
+
+  git(basePath, ["commit", "-C", sha]);
+  return true;
+}
+
+function assertNoExcludedPaths(basePath: string, base: string): void {
+  const files = git(basePath, [
+    "diff",
+    "--name-only",
+    `${base}..HEAD`,
+  ])
+    .split("\n")
+    .filter(Boolean);
+  const leaked = files.filter(
+    (f) => f.startsWith(".gsd/") || f.startsWith(".planning/") || f === "PLAN.md",
+  );
+  if (leaked.length > 0) {
+    throw new Error(
+      `PR branch still contains excluded paths: ${leaked.slice(0, 5).join(", ")}${
+        leaked.length > 5 ? ` (+${leaked.length - 5} more)` : ""
+      }`,
+    );
+  }
+}
+
+export async function handlePrBranch(
+  args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const basePath = process.cwd();
+  const dryRun = args.includes("--dry-run");
+  const nameMatch = args.match(/--name\s+(\S+)/);
+
+  const currentBranch = nativeGetCurrentBranch(basePath);
+  const mainBranch = nativeDetectMainBranch(basePath);
+
+  // Determine base ref (prefer upstream/main if available)
+  let baseRef: string;
+  try {
+    git(basePath, ["rev-parse", "--verify", "upstream/main"]);
+    baseRef = "upstream/main";
+  } catch {
+    baseRef = mainBranch;
+  }
+
+  // Find commits with code changes
+  const commits = getCodeOnlyCommits(basePath, baseRef, "HEAD");
+
+  if (commits.length === 0) {
+    ctx.ui.notify("No code-only commits found (all commits only touch .gsd/ files).", "info");
+    return;
+  }
+
+  if (dryRun) {
+    const lines = [`Would create PR branch with ${commits.length} commits (filtering .gsd/ paths):\n`];
+    for (const sha of commits) {
+      const msg = git(basePath, ["log", "--format=%s", "-1", sha]);
+      lines.push(`  ${sha.slice(0, 8)} ${msg}`);
+    }
+    ctx.ui.notify(lines.join("\n"), "info");
+    return;
+  }
+
+  const requestedName = nameMatch?.[1];
+  if (requestedName && !isValidBranchName(requestedName)) {
+    ctx.ui.notify(
+      `Invalid branch name: ${requestedName}. Must satisfy git check-ref-format.`,
+      "error",
+    );
+    return;
+  }
+
+  const defaultName = `pr/${currentBranch}`;
+  const prBranch = requestedName ?? defaultName;
+
+  if (!isValidBranchName(prBranch)) {
+    ctx.ui.notify(
+      `Derived branch name is invalid: ${prBranch}. Use --name to override.`,
+      "error",
+    );
+    return;
+  }
+
+  if (nativeBranchExists(basePath, prBranch)) {
+    ctx.ui.notify(
+      `Branch ${prBranch} already exists. Use --name to specify a different name, or delete it first.`,
+      "warning",
+    );
+    return;
+  }
+
+  try {
+    // Create clean branch from base
+    git(basePath, ["checkout", "-b", prBranch, baseRef]);
+
+    // Cherry-pick with path filter
+    let picked = 0;
+    let skipped = 0;
+    for (const sha of commits) {
+      try {
+        if (cherryPickFiltered(basePath, sha)) {
+          picked++;
+        } else {
+          skipped++;
+        }
+      } catch (pickErr) {
+        gitAllowFail(basePath, ["cherry-pick", "--abort"]);
+        gitAllowFail(basePath, ["reset", "--hard", "HEAD"]);
+        const detail = pickErr instanceof Error ? pickErr.message : String(pickErr);
+        ctx.ui.notify(
+          `Cherry-pick conflict at ${sha.slice(0, 8)}. Picked ${picked}/${commits.length} commits. Resolve manually.\n${detail}`,
+          "warning",
+        );
+        git(basePath, ["checkout", currentBranch]);
+        return;
+      }
+    }
+
+    // Post-condition: no excluded paths should appear in the PR branch diff.
+    assertNoExcludedPaths(basePath, baseRef);
+
+    const skippedMsg = skipped > 0 ? ` (${skipped} skipped — contained only planning artifacts)` : "";
+    ctx.ui.notify(
+      `Created ${prBranch} with ${picked} commits${skippedMsg} (no .gsd/ artifacts).\nSwitch back: git checkout ${currentBranch}`,
+      "success",
+    );
+  } catch (err) {
+    // Restore original branch on failure
+    gitAllowFail(basePath, ["cherry-pick", "--abort"]);
+    gitAllowFail(basePath, ["reset", "--hard", "HEAD"]);
+    gitAllowFail(basePath, ["checkout", currentBranch]);
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to create PR branch: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -699,10 +699,22 @@ async function configureAdvanced(ctx: ExtensionCommandContext, prefs: Record<str
 export async function handlePrefsWizard(
   ctx: ExtensionCommandContext,
   scope: "global" | "project",
+  prefill?: Record<string, unknown>,
+  opts?: { pathOverride?: string },
 ): Promise<void> {
-  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  // pathOverride lets callers like /gsd init pass a basePath-derived target
+  // path so the wizard doesn't fall back to cwd-based getProjectGSDPreferencesPath
+  // when the init target diverges from the current working directory.
+  const path = opts?.pathOverride
+    ?? (scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath());
   const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
-  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+  // Order: existing-on-disk values, overlaid with prefill (caller's seeded answers).
+  // Callers like /gsd init pass freshly-collected init answers as prefill so the
+  // wizard menu shows them populated and writeable in one place.
+  const prefs: Record<string, unknown> = {
+    ...(existing?.preferences ?? {}),
+    ...(prefill ?? {}),
+  };
 
   ctx.ui.notify(`GSD preferences (${scope}) — pick a category to configure.`, "info");
 
@@ -734,30 +746,55 @@ export async function handlePrefsWizard(
     else if (choice.startsWith("Advanced"))      await configureAdvanced(ctx, prefs);
   }
 
-  // ─── Serialize to frontmatter ───────────────────────────────────────────
-  prefs.version = prefs.version || 1;
-  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  await writePreferencesFile(path, prefs, ctx, { scope });
+}
 
-  // Preserve existing body content (everything after closing ---)
-  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+/**
+ * Single source of truth for writing a PREFERENCES.md file.
+ *
+ * Both `/gsd init` and the prefs wizard route through this helper so we can't
+ * drift on serialization, body preservation, or post-write reload. Callers
+ * pass `ctx` for the reload/notify side effects; the function is safe to call
+ * without a full UI context for tests via `ctx: null` (skips reload/notify).
+ */
+export async function writePreferencesFile(
+  path: string,
+  prefs: Record<string, unknown>,
+  ctx: ExtensionCommandContext | null,
+  opts?: { scope?: "global" | "project"; defaultBody?: string; notifyOnSave?: boolean },
+): Promise<void> {
+  const next = { ...prefs, version: prefs.version || 1 };
+  const frontmatter = serializePreferencesToFrontmatter(next);
+
+  const fallbackBody = opts?.defaultBody
+    ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+
+  // Preserve existing body content (everything after closing ---) so users
+  // who edited the markdown body don't lose their notes.
+  let body = fallbackBody;
   if (existsSync(path)) {
     const preserved = extractBodyAfterFrontmatter(readFileSync(path, "utf-8"));
     if (preserved) body = preserved;
   }
 
   const content = `---\n${frontmatter}---${body}`;
-
   await saveFile(path, content);
-  await ctx.waitForIdle();
-  await ctx.reload();
-  ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
+
+  if (ctx) {
+    await ctx.waitForIdle();
+    await ctx.reload();
+    if (opts?.notifyOnSave !== false) {
+      const scopeLabel = opts?.scope ? `${opts.scope} ` : "";
+      ctx.ui.notify(`Saved ${scopeLabel}preferences to ${path}`, "info");
+    }
+  }
 }
 
 /** Wrap a YAML value in double quotes if it contains special characters. */
 export function yamlSafeString(val: unknown): string {
   if (typeof val !== "string") return String(val);
-  if (/[:#{\[\]'"`,|>&*!?@%]/.test(val) || val.trim() !== val || val === "") {
-    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  if (/[:#{\[\]'"`,|>&*!?@%\r\n]/.test(val) || val.trim() !== val || val === "") {
+    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n")}"`;
   }
   return val;
 }
@@ -822,10 +859,10 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
     "notifications", "cmux", "remote_questions", "git",
     "post_unit_hooks", "pre_dispatch_hooks",
-    "dynamic_routing", "token_profile", "phases", "parallel",
+    "dynamic_routing", "uok", "token_profile", "phases", "parallel",
     "auto_visualize", "auto_report",
     "verification_commands", "verification_auto_fix", "verification_max_retries",
-    "search_provider", "context_selection",
+    "search_provider", "context_selection", "language",
   ];
 
   const seen = new Set<string>();
@@ -862,3 +899,57 @@ export async function ensurePreferencesFile(
     ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
   }
 }
+
+/**
+ * Handle `/gsd language [code]` — set or clear the global language preference.
+ * Without an argument, shows the current setting.
+ * Project-level override can be set by editing `.gsd/PREFERENCES.md` directly
+ * (project language overrides global when both are set).
+ */
+export async function handleLanguage(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const path = getGlobalGSDPreferencesPath();
+  const lang = args.trim();
+
+  // Show current setting when called without argument
+  if (!lang) {
+    const loaded = loadGlobalGSDPreferences();
+    const current = loaded?.preferences.language;
+    if (current) {
+      ctx.ui.notify(`Current language preference: ${current}\nUse /gsd language <name> to change, or /gsd language off to clear.`, "info");
+    } else {
+      ctx.ui.notify("No language preference set. Use /gsd language <name> to set one (e.g. /gsd language Chinese).", "info");
+    }
+    return;
+  }
+
+  // Ensure preferences file exists with the canonical template
+  await ensurePreferencesFile(path, ctx, "global");
+
+  // Read via the same validated path as other handlers
+  const existing = loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : { version: 1 };
+
+  if (lang === "off" || lang === "none" || lang === "clear") {
+    delete prefs.language;
+    ctx.ui.notify("Language preference cleared. GSD will use the default language.", "info");
+  } else {
+    // Validate before writing — reject values that would fail on next load
+    if (lang.length > 50 || /[\r\n]/.test(lang)) {
+      ctx.ui.notify(
+        "Language value must be 50 characters or fewer with no newlines (e.g. /gsd language Chinese).",
+        "warning",
+      );
+      return;
+    }
+    prefs.language = lang;
+    ctx.ui.notify(`Language preference set to: ${lang}\nGSD will now respond in ${lang} across all sessions.`, "info");
+  }
+
+  const rawContent = existsSync(path) ? readFileSync(path, "utf-8") : `---\nversion: 1\n---\n`;
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  const body = extractBodyAfterFrontmatter(rawContent)
+    ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  await saveFile(path, `---\n${frontmatter}---${body}`);
+  await ctx.waitForIdle();
+  await ctx.reload();
+}

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

@@ -0,0 +1,125 @@
+/**
+ * GSD Command — /gsd scan
+ *
+ * Rapid codebase assessment — lightweight alternative to /gsd map-codebase.
+ * Spawns one focused AI analysis pass and writes structured documents to
+ * .gsd/codebase/ for use by planning and execution phases.
+ *
+ * Usage:
+ *   /gsd scan                   — tech+arch focus (default)
+ *   /gsd scan --focus tech      — technology stack + integrations only
+ *   /gsd scan --focus arch      — architecture + structure only
+ *   /gsd scan --focus quality   — conventions + testing patterns only
+ *   /gsd scan --focus concerns  — technical debt + concerns only
+ *   /gsd scan --focus tech+arch — explicit default (same as no flag)
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { loadPrompt } from "./prompt-loader.js";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+export const DEFAULT_FOCUS = "tech+arch";
+
+export const VALID_FOCUS_AREAS = ["tech", "arch", "quality", "concerns", "tech+arch"] as const;
+export type FocusArea = (typeof VALID_FOCUS_AREAS)[number];
+
+const FOCUS_DOCUMENTS: Record<FocusArea, string[]> = {
+  tech: ["STACK", "INTEGRATIONS"],
+  arch: ["ARCHITECTURE", "STRUCTURE"],
+  quality: ["CONVENTIONS", "TESTING"],
+  concerns: ["CONCERNS"],
+  "tech+arch": ["STACK", "INTEGRATIONS", "ARCHITECTURE", "STRUCTURE"],
+};
+
+// ─── Exported functions (exported for testing) ───────────────────────────────
+// Note: checkExistingDocuments reads the filesystem and is not purely functional.
+
+/**
+ * Parse --focus flag from raw args string.
+ * Returns default focus when flag is missing or the value is invalid.
+ * Shell-injection safe: only well-known values are accepted.
+ */
+export function parseScanArgs(args: string): { focus: string } {
+  const match = args.match(/--focus\s+([^\s]+)/i);
+  if (!match) return { focus: DEFAULT_FOCUS };
+
+  const raw = match[1].toLowerCase();
+  if ((VALID_FOCUS_AREAS as readonly string[]).includes(raw)) {
+    return { focus: raw };
+  }
+  return { focus: DEFAULT_FOCUS };
+}
+
+/**
+ * Return the list of document names (without extension) to generate for a focus.
+ * Falls back to the default focus documents for unknown values.
+ */
+export function resolveScanDocuments(focus: string): string[] {
+  return FOCUS_DOCUMENTS[focus as FocusArea] ?? FOCUS_DOCUMENTS[DEFAULT_FOCUS];
+}
+
+/**
+ * Build absolute output paths for the documents produced by a scan focus.
+ * All documents live under <basePath>/.gsd/codebase/
+ */
+export function buildScanOutputPaths(focus: string, basePath: string): string[] {
+  const docs = resolveScanDocuments(focus);
+  return docs.map((doc) => join(basePath, ".gsd", "codebase", `${doc}.md`));
+}
+
+/**
+ * Return the subset of paths that already exist on disk.
+ */
+export function checkExistingDocuments(paths: string[]): string[] {
+  return paths.filter((p) => existsSync(p));
+}
+
+// ─── Command handler ──────────────────────────────────────────────────────────
+
+export async function handleScan(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const basePath = process.cwd();
+  const { focus } = parseScanArgs(args);
+  const outputDir = join(basePath, ".gsd", "codebase");
+  const outputPaths = buildScanOutputPaths(focus, basePath);
+  const existing = checkExistingDocuments(outputPaths);
+
+  if (existing.length > 0) {
+    const names = existing.map((p) => relative(outputDir, p)).join(", ");
+    ctx.ui.notify(
+      `Existing documents will be overwritten: ${names}\nContinuing scan with focus: ${focus}`,
+      "warning",
+    );
+  }
+
+  mkdirSync(outputDir, { recursive: true });
+
+  const documents = resolveScanDocuments(focus);
+
+  ctx.ui.notify(`Running codebase scan (focus: ${focus})…`, "info");
+
+  try {
+    const prompt = loadPrompt("scan", {
+      focus,
+      documents: documents.join(", "),
+      outputDir: outputDir.replaceAll("\\", "/"),
+      workingDirectory: basePath,
+    });
+
+    pi.sendMessage(
+      { customType: "gsd-scan", content: prompt, display: false },
+      { triggerTurn: true },
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to dispatch scan: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/commands-session-report.ts

@@ -0,0 +1,101 @@
+/**
+ * GSD Command — /gsd session-report
+ *
+ * Summarizes the current session: tasks completed, cost, tokens,
+ * duration, model usage breakdown.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
+import type { UnitMetrics } from "./metrics.js";
+import { gsdRoot } from "./paths.js";
+import { formatDuration } from "../shared/format-utils.js";
+
+function formatSessionReport(units: UnitMetrics[]): string {
+  const totals = getProjectTotals(units);
+  const byModel = aggregateByModel(units);
+
+  const lines: string[] = [];
+  lines.push("╭─ Session Report ──────────────────────────────────────╮");
+
+  if (totals.duration > 0) {
+    lines.push(`│ Duration:    ${formatDuration(totals.duration).padEnd(40)}│`);
+  }
+  lines.push(`│ Units:       ${String(units.length).padEnd(40)}│`);
+  lines.push(`│ Cost:        ${formatCost(totals.cost).padEnd(40)}│`);
+  lines.push(`│ Tokens:      ${`${formatTokenCount(totals.tokens.input)} in / ${formatTokenCount(totals.tokens.output)} out`.padEnd(40)}│`);
+  lines.push("│                                                       │");
+
+  // Work completed
+  if (units.length > 0) {
+    lines.push("│ Work Completed:                                       │");
+    for (const unit of units) {
+      const finished = unit.finishedAt > 0;
+      const status = finished ? "✓" : "•";
+      const label = `  ${status} ${unit.id ?? "unknown"}`;
+      lines.push(`│ ${label.padEnd(53)}│`);
+    }
+    lines.push("│                                                       │");
+  }
+
+  // Model usage
+  if (byModel.length > 0) {
+    lines.push("│ Model Usage:                                          │");
+    for (const m of byModel) {
+      const label = `  ${m.model}: ${m.units} units (${formatCost(m.cost)})`;
+      lines.push(`│ ${label.padEnd(53)}│`);
+    }
+  }
+
+  lines.push("╰───────────────────────────────────────────────────────╯");
+  return lines.join("\n");
+}
+
+export async function handleSessionReport(
+  args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const basePath = process.cwd();
+
+  // Get units from in-memory ledger or disk
+  const ledger = getLedger();
+  let units: UnitMetrics[];
+
+  if (ledger && ledger.units.length > 0) {
+    units = ledger.units;
+  } else {
+    const diskLedger = loadLedgerFromDisk(basePath);
+    if (!diskLedger || diskLedger.units.length === 0) {
+      ctx.ui.notify("No session data — no units have been executed yet.", "info");
+      return;
+    }
+    units = diskLedger.units;
+  }
+
+  // JSON output
+  if (args.includes("--json")) {
+    const totals = getProjectTotals(units);
+    const byModel = aggregateByModel(units);
+    ctx.ui.notify(JSON.stringify({ units: units.length, totals, byModel }, null, 2), "info");
+    return;
+  }
+
+  // Save to file
+  if (args.includes("--save")) {
+    const report = formatSessionReport(units);
+    const reportsDir = join(gsdRoot(basePath), "reports");
+    mkdirSync(reportsDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const outPath = join(reportsDir, `session-${timestamp}.md`);
+    writeFileSync(outPath, `\`\`\`\n${report}\n\`\`\`\n`, "utf-8");
+    ctx.ui.notify(`Report saved: ${outPath}`, "success");
+    return;
+  }
+
+  // Display
+  ctx.ui.notify(formatSessionReport(units), "info");
+}