gsd-pi 2.19.0 → 2.20.0

package/dist/resources/extensions/gsd/doctor-proactive.ts

@@ -0,0 +1,286 @@
+/**
+ * GSD Doctor — Proactive Healing Layer
+ *
+ * Three mechanisms for automatic health monitoring during auto-mode:
+ *
+ * 1. Pre-dispatch health gate: lightweight check before each unit dispatch.
+ *    Returns blocking issues that should pause auto-mode rather than
+ *    dispatching into a broken state.
+ *
+ * 2. Health score tracking: tracks issue counts over time to detect
+ *    degradation trends. If health is declining, surfaces a warning.
+ *
+ * 3. Auto-heal escalation: if deterministic fix can't resolve issues
+ *    after N units, escalates to LLM-assisted heal dispatch.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot, resolveGsdRootFile } from "./paths.js";
+import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
+import { abortAndReset } from "./git-self-heal.js";
+
+// ── Health Score Tracking ──────────────────────────────────────────────────
+
+export interface HealthSnapshot {
+  timestamp: number;
+  errors: number;
+  warnings: number;
+  fixesApplied: number;
+  unitIndex: number; // which unit dispatch triggered this snapshot
+}
+
+/** In-memory health history for the current auto-mode session. */
+let healthHistory: HealthSnapshot[] = [];
+
+/** Count of consecutive units with unresolved errors. */
+let consecutiveErrorUnits = 0;
+
+/** Unit index counter for health tracking. */
+let healthUnitIndex = 0;
+
+/**
+ * Record a health snapshot after a doctor run.
+ * Called from the post-unit hook in auto.ts.
+ */
+export function recordHealthSnapshot(errors: number, warnings: number, fixesApplied: number): void {
+  healthUnitIndex++;
+  healthHistory.push({
+    timestamp: Date.now(),
+    errors,
+    warnings,
+    fixesApplied,
+    unitIndex: healthUnitIndex,
+  });
+
+  // Keep only the last 50 snapshots to bound memory
+  if (healthHistory.length > 50) {
+    healthHistory = healthHistory.slice(-50);
+  }
+
+  if (errors > 0) {
+    consecutiveErrorUnits++;
+  } else {
+    consecutiveErrorUnits = 0;
+  }
+}
+
+/**
+ * Get the current health trend.
+ * Returns "improving", "stable", "degrading", or "unknown" (not enough data).
+ */
+export function getHealthTrend(): "improving" | "stable" | "degrading" | "unknown" {
+  if (healthHistory.length < 3) return "unknown";
+
+  const recent = healthHistory.slice(-5);
+  const older = healthHistory.slice(-10, -5);
+
+  if (older.length === 0) return "unknown";
+
+  const recentAvg = recent.reduce((sum, s) => sum + s.errors + s.warnings, 0) / recent.length;
+  const olderAvg = older.reduce((sum, s) => sum + s.errors + s.warnings, 0) / older.length;
+
+  const delta = recentAvg - olderAvg;
+  if (delta > 1) return "degrading";
+  if (delta < -1) return "improving";
+  return "stable";
+}
+
+/**
+ * Get the number of consecutive units with unresolved errors.
+ */
+export function getConsecutiveErrorUnits(): number {
+  return consecutiveErrorUnits;
+}
+
+/**
+ * Get health history for display (e.g., dashboard overlay).
+ */
+export function getHealthHistory(): readonly HealthSnapshot[] {
+  return healthHistory;
+}
+
+/**
+ * Reset health tracking state. Called on auto-mode start/stop.
+ */
+export function resetHealthTracking(): void {
+  healthHistory = [];
+  consecutiveErrorUnits = 0;
+  healthUnitIndex = 0;
+}
+
+// ── Pre-Dispatch Health Gate ───────────────────────────────────────────────
+
+export interface PreDispatchHealthResult {
+  /** Whether the dispatch should proceed. */
+  proceed: boolean;
+  /** If blocked, the reason to show the user. */
+  reason?: string;
+  /** Issues found (for logging). */
+  issues: string[];
+  /** Whether fix was applied. */
+  fixesApplied: string[];
+}
+
+/**
+ * Lightweight pre-dispatch health check. Runs fast checks that should
+ * block dispatch if they fail — avoids dispatching into a broken state.
+ *
+ * This is NOT a full doctor run — it only checks critical, fast-to-evaluate
+ * conditions that would cause the next unit to fail or corrupt state.
+ *
+ * Returns { proceed: true } if dispatch should continue.
+ */
+export function preDispatchHealthGate(basePath: string): PreDispatchHealthResult {
+  const issues: string[] = [];
+  const fixesApplied: string[] = [];
+
+  // ── Stale crash lock blocks dispatch ──
+  // If a stale lock exists, the crash recovery path should handle it,
+  // not a new dispatch. This prevents double-dispatch after crashes.
+  try {
+    const lock = readCrashLock(basePath);
+    if (lock && !isLockProcessAlive(lock)) {
+      // Auto-clear it since we're about to dispatch anyway
+      clearLock(basePath);
+      fixesApplied.push("cleared stale auto.lock before dispatch");
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // ── Corrupt merge/rebase state blocks dispatch ──
+  // Dispatching a unit with MERGE_HEAD present will cause git operations to fail.
+  try {
+    const gitDir = join(basePath, ".git");
+    if (existsSync(gitDir)) {
+      const blockers = ["MERGE_HEAD", "rebase-apply", "rebase-merge"].filter(
+        f => existsSync(join(gitDir, f)),
+      );
+      if (blockers.length > 0) {
+        // Try to auto-heal
+        try {
+          const result = abortAndReset(basePath);
+          fixesApplied.push(`pre-dispatch: cleaned merge state (${result.cleaned.join(", ")})`);
+        } catch {
+          issues.push(`Corrupt git state: ${blockers.join(", ")}. Run /gsd doctor fix.`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // ── STATE.md existence check ──
+  // If STATE.md is missing, deriveState will still work but the LLM
+  // may get confused. Rebuild it silently.
+  try {
+    const stateFile = resolveGsdRootFile(basePath, "STATE");
+    const milestonesDir = join(gsdRoot(basePath), "milestones");
+    if (existsSync(milestonesDir) && !existsSync(stateFile)) {
+      issues.push("STATE.md missing — will rebuild after this unit");
+      // Don't block dispatch — rebuilding happens in post-hook
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // If we had critical issues that couldn't be auto-healed, block dispatch
+  if (issues.length > 0) {
+    return {
+      proceed: false,
+      reason: `Pre-dispatch health check failed:\n${issues.map(i => `  - ${i}`).join("\n")}\nRun /gsd doctor fix to resolve.`,
+      issues,
+      fixesApplied,
+    };
+  }
+
+  return { proceed: true, issues, fixesApplied };
+}
+
+// ── Auto-Heal Escalation ──────────────────────────────────────────────────
+
+/** Threshold: escalate to LLM heal after this many consecutive error units. */
+const ESCALATION_THRESHOLD = 5;
+
+/** Whether an escalation has already been triggered this session (prevent spam). */
+let escalationTriggered = false;
+
+/**
+ * Check whether auto-heal should escalate from deterministic fix to
+ * LLM-assisted heal. Called after each post-unit doctor run.
+ *
+ * Returns the structured issue text for LLM dispatch, or null if
+ * escalation is not needed.
+ */
+export function checkHealEscalation(
+  errors: number,
+  unresolvedIssues: Array<{ code: string; message: string; unitId: string }>,
+): { shouldEscalate: boolean; reason: string; issues: typeof unresolvedIssues } {
+  if (escalationTriggered) {
+    return { shouldEscalate: false, reason: "already escalated this session", issues: [] };
+  }
+
+  if (consecutiveErrorUnits < ESCALATION_THRESHOLD) {
+    return {
+      shouldEscalate: false,
+      reason: `${consecutiveErrorUnits}/${ESCALATION_THRESHOLD} consecutive error units`,
+      issues: [],
+    };
+  }
+
+  if (errors === 0) {
+    return { shouldEscalate: false, reason: "no errors to escalate", issues: [] };
+  }
+
+  const trend = getHealthTrend();
+  if (trend === "improving") {
+    return { shouldEscalate: false, reason: "health is improving — deferring escalation", issues: [] };
+  }
+
+  escalationTriggered = true;
+  return {
+    shouldEscalate: true,
+    reason: `${consecutiveErrorUnits} consecutive units with unresolved errors (trend: ${trend})`,
+    issues: unresolvedIssues,
+  };
+}
+
+/**
+ * Reset escalation state. Called on auto-mode start/stop.
+ */
+export function resetEscalation(): void {
+  escalationTriggered = false;
+}
+
+/**
+ * Format a health summary for display in the auto-mode dashboard.
+ */
+export function formatHealthSummary(): string {
+  if (healthHistory.length === 0) return "No health data yet.";
+
+  const latest = healthHistory[healthHistory.length - 1]!;
+  const trend = getHealthTrend();
+  const trendIcon = trend === "improving" ? "+" : trend === "degrading" ? "-" : "=";
+  const totalFixes = healthHistory.reduce((sum, s) => sum + s.fixesApplied, 0);
+
+  const parts = [
+    `Health: ${latest.errors}E/${latest.warnings}W`,
+    `trend:${trendIcon}`,
+    `fixes:${totalFixes}`,
+  ];
+
+  if (consecutiveErrorUnits > 0) {
+    parts.push(`streak:${consecutiveErrorUnits}/${ESCALATION_THRESHOLD}`);
+  }
+
+  return parts.join(" | ");
+}
+
+/**
+ * Reset all proactive healing state. Called on auto-mode start/stop.
+ */
+export function resetProactiveHealing(): void {
+  resetHealthTracking();
+  resetEscalation();
+}

package/dist/resources/extensions/gsd/doctor.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { join, sep } from "node:path";
 
 import { loadFile, parsePlan, parseRoadmap, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
@@ -9,6 +9,8 @@ import { listWorktrees } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { nativeIsRepo, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached } from "./native-git-bridge.js";
+import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
+import { ensureGitignore } from "./gitignore.js";
 
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
@@ -32,7 +34,14 @@ export type DoctorIssueCode =
   | "stale_milestone_branch"
   | "corrupt_merge_state"
   | "tracked_runtime_files"
-  | "legacy_slice_branches";
+  | "legacy_slice_branches"
+  | "stale_crash_lock"
+  | "orphaned_completed_units"
+  | "stale_hook_state"
+  | "activity_log_bloat"
+  | "state_file_stale"
+  | "state_file_missing"
+  | "gitignore_missing_patterns";
 
 export interface DoctorIssue {
   severity: DoctorSeverity;
@@ -657,6 +666,275 @@ async function checkGitHealth(
   }
 }
 
+// ── Runtime Health Checks ──────────────────────────────────────────────────
+// Checks for stale crash locks, orphaned completed-units, stale hook state,
+// activity log bloat, STATE.md drift, and gitignore drift.
+
+async function checkRuntimeHealth(
+  basePath: string,
+  issues: DoctorIssue[],
+  fixesApplied: string[],
+  shouldFix: (code: DoctorIssueCode) => boolean,
+): Promise<void> {
+  const root = gsdRoot(basePath);
+
+  // ── Stale crash lock ──────────────────────────────────────────────────
+  try {
+    const lock = readCrashLock(basePath);
+    if (lock) {
+      const alive = isLockProcessAlive(lock);
+      if (!alive) {
+        issues.push({
+          severity: "error",
+          code: "stale_crash_lock",
+          scope: "project",
+          unitId: "project",
+          message: `Stale auto.lock from PID ${lock.pid} (started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
+          file: ".gsd/auto.lock",
+          fixable: true,
+        });
+
+        if (shouldFix("stale_crash_lock")) {
+          clearLock(basePath);
+          fixesApplied.push("cleared stale auto.lock");
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — crash lock check failed
+  }
+
+  // ── Orphaned completed-units keys ─────────────────────────────────────
+  try {
+    const completedKeysFile = join(root, "completed-units.json");
+    if (existsSync(completedKeysFile)) {
+      const raw = readFileSync(completedKeysFile, "utf-8");
+      const keys: string[] = JSON.parse(raw);
+      const orphaned: string[] = [];
+
+      for (const key of keys) {
+        // Key format: "unitType/unitId" e.g. "execute-task/M001/S01/T01"
+        const slashIdx = key.indexOf("/");
+        if (slashIdx === -1) continue;
+        const unitType = key.slice(0, slashIdx);
+        const unitId = key.slice(slashIdx + 1);
+
+        // Only validate artifact-producing unit types
+        const { verifyExpectedArtifact } = await import("./auto-recovery.js");
+        if (!verifyExpectedArtifact(unitType, unitId, basePath)) {
+          orphaned.push(key);
+        }
+      }
+
+      if (orphaned.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "orphaned_completed_units",
+          scope: "project",
+          unitId: "project",
+          message: `${orphaned.length} completed-unit key(s) reference missing artifacts: ${orphaned.slice(0, 3).join(", ")}${orphaned.length > 3 ? "..." : ""}`,
+          file: ".gsd/completed-units.json",
+          fixable: true,
+        });
+
+        if (shouldFix("orphaned_completed_units")) {
+          const { removePersistedKey } = await import("./auto-recovery.js");
+          for (const key of orphaned) {
+            removePersistedKey(basePath, key);
+          }
+          fixesApplied.push(`removed ${orphaned.length} orphaned completed-unit key(s)`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — completed-units check failed
+  }
+
+  // ── Stale hook state ──────────────────────────────────────────────────
+  try {
+    const hookStateFile = join(root, "hook-state.json");
+    if (existsSync(hookStateFile)) {
+      const raw = readFileSync(hookStateFile, "utf-8");
+      const state = JSON.parse(raw);
+      const hasCycleCounts = state.cycleCounts && typeof state.cycleCounts === "object"
+        && Object.keys(state.cycleCounts).length > 0;
+
+      // Only flag if there are actual cycle counts AND no auto-mode is running
+      if (hasCycleCounts) {
+        const lock = readCrashLock(basePath);
+        const autoRunning = lock ? isLockProcessAlive(lock) : false;
+
+        if (!autoRunning) {
+          issues.push({
+            severity: "info",
+            code: "stale_hook_state",
+            scope: "project",
+            unitId: "project",
+            message: `hook-state.json has ${Object.keys(state.cycleCounts).length} residual cycle count(s) from a previous session`,
+            file: ".gsd/hook-state.json",
+            fixable: true,
+          });
+
+          if (shouldFix("stale_hook_state")) {
+            const { clearPersistedHookState } = await import("./post-unit-hooks.js");
+            clearPersistedHookState(basePath);
+            fixesApplied.push("cleared stale hook-state.json");
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — hook state check failed
+  }
+
+  // ── Activity log bloat ────────────────────────────────────────────────
+  try {
+    const activityDir = join(root, "activity");
+    if (existsSync(activityDir)) {
+      const files = readdirSync(activityDir);
+      let totalSize = 0;
+      for (const f of files) {
+        try {
+          totalSize += statSync(join(activityDir, f)).size;
+        } catch {
+          // stat failed — skip
+        }
+      }
+
+      const totalMB = totalSize / (1024 * 1024);
+      const BLOAT_FILE_THRESHOLD = 500;
+      const BLOAT_SIZE_MB = 100;
+
+      if (files.length > BLOAT_FILE_THRESHOLD || totalMB > BLOAT_SIZE_MB) {
+        issues.push({
+          severity: "warning",
+          code: "activity_log_bloat",
+          scope: "project",
+          unitId: "project",
+          message: `Activity logs: ${files.length} files, ${totalMB.toFixed(1)}MB (thresholds: ${BLOAT_FILE_THRESHOLD} files / ${BLOAT_SIZE_MB}MB)`,
+          file: ".gsd/activity/",
+          fixable: true,
+        });
+
+        if (shouldFix("activity_log_bloat")) {
+          const { pruneActivityLogs } = await import("./activity-log.js");
+          pruneActivityLogs(activityDir, 7); // 7-day retention
+          fixesApplied.push("pruned activity logs (7-day retention)");
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — activity log check failed
+  }
+
+  // ── STATE.md health ───────────────────────────────────────────────────
+  try {
+    const stateFilePath = resolveGsdRootFile(basePath, "STATE");
+    const milestonesPath = milestonesDir(basePath);
+
+    if (existsSync(milestonesPath)) {
+      if (!existsSync(stateFilePath)) {
+        issues.push({
+          severity: "warning",
+          code: "state_file_missing",
+          scope: "project",
+          unitId: "project",
+          message: "STATE.md is missing — state display will not work",
+          file: ".gsd/STATE.md",
+          fixable: true,
+        });
+
+        if (shouldFix("state_file_missing")) {
+          const state = await deriveState(basePath);
+          await saveFile(stateFilePath, buildStateMarkdown(state));
+          fixesApplied.push("created STATE.md from derived state");
+        }
+      } else {
+        // Check if STATE.md is stale by comparing active milestone/slice/phase
+        const currentContent = readFileSync(stateFilePath, "utf-8");
+        const state = await deriveState(basePath);
+        const freshContent = buildStateMarkdown(state);
+
+        // Extract key fields for comparison — don't compare full content
+        // since timestamp/formatting differences are normal
+        const extractFields = (content: string) => {
+          const milestone = content.match(/\*\*Active Milestone:\*\*\s*(.+)/)?.[1]?.trim() ?? "";
+          const slice = content.match(/\*\*Active Slice:\*\*\s*(.+)/)?.[1]?.trim() ?? "";
+          const phase = content.match(/\*\*Phase:\*\*\s*(.+)/)?.[1]?.trim() ?? "";
+          return { milestone, slice, phase };
+        };
+
+        const current = extractFields(currentContent);
+        const fresh = extractFields(freshContent);
+
+        if (current.milestone !== fresh.milestone || current.slice !== fresh.slice || current.phase !== fresh.phase) {
+          issues.push({
+            severity: "warning",
+            code: "state_file_stale",
+            scope: "project",
+            unitId: "project",
+            message: `STATE.md is stale — shows "${current.phase}" but derived state is "${fresh.phase}"`,
+            file: ".gsd/STATE.md",
+            fixable: true,
+          });
+
+          if (shouldFix("state_file_stale")) {
+            await saveFile(stateFilePath, freshContent);
+            fixesApplied.push("rebuilt STATE.md from derived state");
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — STATE.md check failed
+  }
+
+  // ── Gitignore drift ───────────────────────────────────────────────────
+  try {
+    const gitignorePath = join(basePath, ".gitignore");
+    if (existsSync(gitignorePath) && nativeIsRepo(basePath)) {
+      const content = readFileSync(gitignorePath, "utf-8");
+      const existingLines = new Set(
+        content.split("\n").map(l => l.trim()).filter(l => l && !l.startsWith("#")),
+      );
+
+      // Check for critical runtime patterns that must be present
+      const criticalPatterns = [
+        ".gsd/activity/",
+        ".gsd/runtime/",
+        ".gsd/auto.lock",
+        ".gsd/gsd.db",
+        ".gsd/completed-units.json",
+      ];
+
+      // If blanket .gsd/ or .gsd is present, all patterns are covered
+      const hasBlanketIgnore = existingLines.has(".gsd/") || existingLines.has(".gsd");
+
+      if (!hasBlanketIgnore) {
+        const missing = criticalPatterns.filter(p => !existingLines.has(p));
+        if (missing.length > 0) {
+          issues.push({
+            severity: "warning",
+            code: "gitignore_missing_patterns",
+            scope: "project",
+            unitId: "project",
+            message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+            file: ".gitignore",
+            fixable: true,
+          });
+
+          if (shouldFix("gitignore_missing_patterns")) {
+            ensureGitignore(basePath);
+            fixesApplied.push("added missing GSD runtime patterns to .gitignore");
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — gitignore check failed
+  }
+}
+
 export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all" }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
@@ -700,6 +978,9 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // Git health checks (orphaned worktrees, stale branches, corrupt merge state, tracked runtime files)
   await checkGitHealth(basePath, issues, fixesApplied, shouldFix);
 
+  // Runtime health checks (crash locks, completed-units, hook state, activity logs, STATE.md, gitignore)
+  await checkRuntimeHealth(basePath, issues, fixesApplied, shouldFix);
+
   const milestonesPath = milestonesDir(basePath);
   if (!existsSync(milestonesPath)) {
     return { ok: issues.every(issue => issue.severity !== "error"), basePath, issues, fixesApplied };

package/dist/resources/extensions/gsd/export.ts

@@ -1,18 +1,97 @@
 // GSD Extension — Session/Milestone Export
 // Generate shareable reports of milestone work in JSON or markdown format.
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join, basename } from "node:path";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
-  aggregateByModel, formatCost, formatTokenCount,
+  aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk,
 } from "./metrics.js";
 import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration } from "./history.js";
 
+/**
+ * Write an export file directly, without requiring an ExtensionCommandContext.
+ * Used by the visualizer overlay export tab.
+ * Returns the output file path, or null on failure.
+ */
+export function writeExportFile(
+  basePath: string,
+  format: "markdown" | "json",
+  visualizerData?: { totals: any; byPhase: any[]; bySlice: any[]; byModel: any[]; units: any[]; criticalPath?: any; remainingSliceCount?: number },
+): string | null {
+  const ledger = getLedger();
+  let units: UnitMetrics[];
+
+  if (visualizerData && visualizerData.units.length > 0) {
+    units = visualizerData.units;
+  } else if (ledger && ledger.units.length > 0) {
+    units = ledger.units;
+  } else {
+    const diskLedger = loadLedgerFromDisk(basePath);
+    if (!diskLedger || diskLedger.units.length === 0) return null;
+    units = diskLedger.units;
+  }
+
+  const projectName = basename(basePath);
+  const exportDir = gsdRoot(basePath);
+  mkdirSync(exportDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+
+  if (format === "json") {
+    const report = {
+      exportedAt: new Date().toISOString(),
+      project: projectName,
+      totals: visualizerData?.totals ?? getProjectTotals(units),
+      byPhase: visualizerData?.byPhase ?? aggregateByPhase(units),
+      bySlice: visualizerData?.bySlice ?? aggregateBySlice(units),
+      byModel: visualizerData?.byModel ?? aggregateByModel(units),
+      units,
+    };
+    const outPath = join(exportDir, `export-${timestamp}.json`);
+    writeFileSync(outPath, JSON.stringify(report, null, 2) + "\n", "utf-8");
+    return outPath;
+  } else {
+    const totals = visualizerData?.totals ?? getProjectTotals(units);
+    const phases = visualizerData?.byPhase ?? aggregateByPhase(units);
+    const slices = visualizerData?.bySlice ?? aggregateBySlice(units);
+
+    const md = [
+      `# GSD Session Report — ${projectName}`,
+      ``,
+      `**Generated**: ${new Date().toISOString()}`,
+      `**Units completed**: ${totals.units}`,
+      `**Total cost**: ${formatCost(totals.cost)}`,
+      `**Total tokens**: ${formatTokenCount(totals.tokens.total)}`,
+      `**Total duration**: ${formatDuration(totals.duration)}`,
+      `**Tool calls**: ${totals.toolCalls}`,
+      ``,
+      `## Cost by Phase`,
+      ``,
+      `| Phase | Units | Cost | Tokens | Duration |`,
+      `|-------|-------|------|--------|----------|`,
+      ...phases.map((p: any) =>
+        `| ${p.phase} | ${p.units} | ${formatCost(p.cost)} | ${formatTokenCount(p.tokens.total)} | ${formatDuration(p.duration)} |`,
+      ),
+      ``,
+      `## Cost by Slice`,
+      ``,
+      `| Slice | Units | Cost | Tokens | Duration |`,
+      `|-------|-------|------|--------|----------|`,
+      ...slices.map((s: any) =>
+        `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`,
+      ),
+      ``,
+    ].join("\n");
+
+    const outPath = join(exportDir, `export-${timestamp}.md`);
+    writeFileSync(outPath, md, "utf-8");
+    return outPath;
+  }
+}
+
 /**
  * Export session/milestone data to JSON or markdown.
  */