preflight-dev 3.1.0

package/src/tools/search-history.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { searchSemantic, listIndexedProjects } from "../lib/timeline-db.js";
+import { getRelatedProjects } from "../lib/config.js";
+import type { SearchScope } from "../types.js";
+
+const RELATIVE_DATE_RE = /^(\d+)(days?|weeks?|months?|years?)$/;
+
+function parseRelativeDate(input: string): string {
+  const match = input.match(RELATIVE_DATE_RE);
+  if (!match) return input; // assume ISO already
+  const [, numStr, unit] = match;
+  const num = parseInt(numStr, 10);
+  const d = new Date();
+  if (unit.startsWith("day")) d.setDate(d.getDate() - num);
+  else if (unit.startsWith("week")) d.setDate(d.getDate() - num * 7);
+  else if (unit.startsWith("month")) d.setMonth(d.getMonth() - num);
+  else if (unit.startsWith("year")) d.setFullYear(d.getFullYear() - num);
+  return d.toISOString();
+}
+
+const TYPE_BADGES: Record<string, string> = {
+  prompt: "💬 prompt",
+  assistant: "🤖 assistant",
+  correction: "❌ correction",
+  commit: "📦 commit",
+  tool_call: "🔧 tool_call",
+  compaction: "🗜️ compaction",
+  sub_agent_spawn: "🚀 sub_agent_spawn",
+  error: "⚠️ error",
+};
+
+/** Get project directories to search based on scope */
+async function getSearchProjects(scope: SearchScope): Promise<string[]> {
+  const currentProject = process.env.CLAUDE_PROJECT_DIR;
+  
+  switch (scope) {
+    case "current":
+      return currentProject ? [currentProject] : [];
+      
+    case "related":
+      const related = getRelatedProjects();
+      return currentProject ? [currentProject, ...related] : related;
+      
+    case "all":
+      const projects = await listIndexedProjects();
+      return projects.map(p => p.project);
+      
+    default:
+      return currentProject ? [currentProject] : [];
+  }
+}
+
+export function registerSearchHistory(server: McpServer) {
+  server.tool(
+    "search_history",
+    "Semantic search across the unified timeline of prompts, commits, corrections, and tool calls. Find relevant events using natural language queries.",
+    {
+      query: z.string().describe("Natural language search query"),
+      scope: z.enum(["current", "related", "all"]).default("current").describe("Search scope: current project, related projects (PREFLIGHT_RELATED), or all indexed projects"),
+      project: z.string().optional().describe("Filter to a specific project name (overrides scope)"),
+      branch: z.string().optional(),
+      author: z.string().optional().describe("Filter commits to this author (partial match, case-insensitive)"),
+      type: z.enum(["prompt", "assistant", "correction", "commit", "tool_call", "compaction", "sub_agent_spawn", "error", "all"]).default("all"),
+      since: z.string().optional().describe("ISO date or relative: '2025-06-01', '3months'"),
+      until: z.string().optional().describe("ISO date or relative"),
+      limit: z.number().default(10),
+    },
+    async (params) => {
+      const since = params.since ? parseRelativeDate(params.since) : undefined;
+      const until = params.until ? parseRelativeDate(params.until) : undefined;
+
+      // Determine which projects to search
+      let projectDirs: string[];
+      if (params.project) {
+        // Specific project overrides scope
+        projectDirs = [params.project];
+      } else {
+        projectDirs = await getSearchProjects(params.scope);
+      }
+
+      if (projectDirs.length === 0) {
+        return { 
+          content: [{ 
+            type: "text", 
+            text: `## Search Results for "${params.query}"\n_No projects found for scope "${params.scope}". Make sure CLAUDE_PROJECT_DIR is set or projects are onboarded._` 
+          }] 
+        };
+      }
+
+      let results = await searchSemantic(params.query, {
+        project_dirs: projectDirs,
+        project: undefined, // Don't filter by single project when using project_dirs
+        branch: params.branch,
+        type: params.type === "all" ? undefined : params.type,
+        since,
+        until,
+        limit: params.author ? params.limit * 3 : params.limit, // over-fetch if filtering by author
+      });
+
+      // Post-filter by author (stored in metadata JSON)
+      if (params.author) {
+        const authorLower = params.author.toLowerCase();
+        results = results.filter((r: any) => {
+          try {
+            const meta = JSON.parse(r.metadata || "{}");
+            return (meta.author || "").toLowerCase().includes(authorLower);
+          } catch { return false; }
+        }).slice(0, params.limit);
+      }
+
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: `## Search Results for "${params.query}"\n_No results found._` }] };
+      }
+
+      const projects = new Set(results.map((r: any) => r.project || "unknown"));
+      const lines: string[] = [
+        `## Search Results for "${params.query}"`,
+        `_${results.length} result${results.length !== 1 ? "s" : ""} across ${projects.size} project${projects.size !== 1 ? "s" : ""}_`,
+        "",
+      ];
+
+      results.forEach((event: any, i: number) => {
+        const badge = TYPE_BADGES[event.type] || event.type;
+        const ts = event.timestamp ? new Date(event.timestamp).toISOString().replace("T", " ").slice(0, 16) : "unknown";
+        const proj = event.project || "unknown";
+        const branch = event.branch ? ` / ${event.branch}` : "";
+        const score = event._distance != null ? (1 - event._distance).toFixed(2) : "?";
+
+        lines.push(`### ${i + 1}. [${badge}] ${proj}${branch} — ${ts}`);
+
+        const content = (event.content || event.summary || "").slice(0, 200);
+        lines.push(`> ${content.replace(/\n/g, "\n> ")}`);
+
+        const meta: string[] = [`Score: ${score}`];
+        if (event.session_id) meta.push(`Session: ${event.session_id.slice(0, 8)}`);
+        if (event.commit_hash) meta.push(`Hash: ${event.commit_hash.slice(0, 7)}`);
+        lines.push(meta.join(" | "));
+        lines.push("");
+      });
+
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}

package/src/tools/sequence-tasks.ts

@@ -0,0 +1,182 @@
+// CATEGORY 6: sequence_tasks — Sequencing
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { run } from "../lib/git.js";
+import { now } from "../lib/state.js";
+import { PROJECT_DIR } from "../lib/files.js";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+type Cat = "schema" | "config" | "api" | "ui" | "test" | "other";
+
+const CATEGORIES: Record<Exclude<Cat, "other">, RegExp> = {
+  schema: /\b(schema|migrat|database|db|table|column|index|alter|foreign.?key)\b/i,
+  config: /\b(config|env|\.env|settings|secrets?|dotenv|yaml|toml)\b/i,
+  api:    /\b(api|route|endpoint|controller|handler|middleware|graphql|rest|rpc)\b/i,
+  ui:     /\b(ui|component|page|view|layout|template|css|style|frontend|react|vue|svelte)\b/i,
+  test:   /\b(test|spec|e2e|cypress|playwright|jest|vitest|assert|fixture)\b/i,
+};
+
+const CAT_DIR_MAP: Record<string, string> = {
+  schema: "db/", config: "config/", api: "api/", ui: "src/", test: "test/", other: "src/",
+};
+
+// Dependency order: earlier items must complete before later ones
+const DEP_ORDER: Cat[] = ["config", "schema", "api", "ui", "test", "other"];
+
+function classify(task: string): Cat[] {
+  const cats = (Object.entries(CATEGORIES) as [Exclude<Cat, "other">, RegExp][])
+    .filter(([, re]) => re.test(task))
+    .map(([k]) => k as Cat);
+  // Default to "other" instead of "ui" to avoid misclassifying unrelated tasks
+  return cats.length > 0 ? cats : ["other"];
+}
+
+function riskScore(cats: Cat[]): number {
+  let s = 0;
+  if (cats.includes("schema")) s += 10;
+  if (cats.includes("config")) s += 7;
+  if (cats.includes("api")) s += 4;
+  if (cats.includes("ui")) s += 2;
+  if (cats.includes("test")) s += 1;
+  if (cats.includes("other")) s += 3;
+  return s;
+}
+
+/** Validate a path is within PROJECT_DIR */
+function isSafePath(dir: string): boolean {
+  const resolved = resolve(PROJECT_DIR, dir);
+  return resolved.startsWith(resolve(PROJECT_DIR) + "/") || resolved === resolve(PROJECT_DIR);
+}
+
+/** Detect circular dependencies among categorized tasks */
+function detectCircularDeps(tasks: { task: string; cats: Cat[] }[]): string[] {
+  const warnings: string[] = [];
+  // Simple heuristic: if a task mentions output of another task, flag it
+  // More importantly, check if dependency order would create contradictions
+  const catSets = tasks.map((t) => new Set(t.cats));
+  for (let i = 0; i < tasks.length; i++) {
+    for (let j = i + 1; j < tasks.length; j++) {
+      const iCats = catSets[i];
+      const jCats = catSets[j];
+      // Check if i should come before j AND j before i
+      const iBeforeJ = [...iCats].some((c) => [...jCats].some((d) => DEP_ORDER.indexOf(c) < DEP_ORDER.indexOf(d)));
+      const jBeforeI = [...jCats].some((c) => [...iCats].some((d) => DEP_ORDER.indexOf(c) < DEP_ORDER.indexOf(d)));
+      if (iBeforeJ && jBeforeI) {
+        warnings.push(`⚠️ Potential circular dependency: "${tasks[i].task.slice(0, 50)}" and "${tasks[j].task.slice(0, 50)}" have cross-layer categories — consider splitting.`);
+      }
+    }
+  }
+  return warnings;
+}
+
+export function registerSequenceTasks(server: McpServer): void {
+  server.tool(
+    "sequence_tasks",
+    `Order a set of tasks to minimize context switches, reduce re-reads, and batch related work. Supports dependency-order, file-locality, and risk-first strategies. Call when you have multiple tasks to execute in a session.`,
+    {
+      tasks: z.array(z.string()).min(1).describe("Tasks to sequence (natural language descriptions)"),
+      strategy: z.enum(["dependency", "locality", "risk-first"]).default("locality").describe("Sequencing strategy"),
+    },
+    async ({ tasks, strategy }) => {
+      const ts = now();
+
+      const classified = tasks.map((t) => ({
+        task: t,
+        cats: classify(t),
+        dir: null as string | null,
+      }));
+
+      // For locality: infer directories from path-like tokens in task text
+      if (strategy === "locality") {
+        // Use git ls-files with a depth limit instead of find for performance
+        const gitFiles = run("git ls-files 2>/dev/null | head -1000");
+        const knownDirs = new Set<string>();
+        for (const f of gitFiles.split("\n").filter(Boolean)) {
+          const parts = f.split("/");
+          if (parts.length >= 2) knownDirs.add(parts.slice(0, 2).join("/"));
+          if (parts.length >= 1) knownDirs.add(parts[0]);
+        }
+
+        for (const item of classified) {
+          const pathTokens = item.task.match(/[\w\-\/]+\.\w+|[\w\-]+\/[\w\-\/]*/g) || [];
+          for (const token of pathTokens) {
+            const dir = token.split("/").slice(0, 2).join("/");
+            // Validate: must be a known git directory and safe path
+            if (isSafePath(dir) && knownDirs.has(dir)) {
+              item.dir = dir;
+              break;
+            }
+          }
+          if (!item.dir) {
+            item.dir = CAT_DIR_MAP[item.cats[0]] ?? "src/";
+          }
+        }
+      }
+
+      let ordered: typeof classified;
+      let reasoning: string[] = [];
+
+      if (strategy === "dependency") {
+        ordered = [...classified].sort((a, b) => {
+          const aIndices = a.cats.map((c) => DEP_ORDER.indexOf(c)).filter((i) => i >= 0);
+          const bIndices = b.cats.map((c) => DEP_ORDER.indexOf(c)).filter((i) => i >= 0);
+          const aIdx = aIndices.length > 0 ? Math.min(...aIndices) : DEP_ORDER.length;
+          const bIdx = bIndices.length > 0 ? Math.min(...bIndices) : DEP_ORDER.length;
+          return aIdx - bIdx;
+        });
+        reasoning = ordered.map(
+          (item, i) => `${i + 1}. **[${item.cats.join(",")}]** — ${DEP_ORDER.indexOf(item.cats[0]) <= 1 ? "foundational change, must come early" : "depends on earlier layers"}`
+        );
+      } else if (strategy === "risk-first") {
+        ordered = [...classified].sort((a, b) => riskScore(b.cats) - riskScore(a.cats));
+        reasoning = ordered.map(
+          (item, i) => `${i + 1}. **[${item.cats.join(",")}]** risk=${riskScore(item.cats)} — ${riskScore(item.cats) >= 7 ? "high-risk, do while context is fresh" : "lower risk, safe to do later"}`
+        );
+      } else {
+        ordered = [...classified].sort((a, b) => (a.dir ?? "").localeCompare(b.dir ?? ""));
+        reasoning = ordered.map(
+          (item, i) => `${i + 1}. dir=\`${item.dir}\` **[${item.cats.join(",")}]** — grouped by proximity`
+        );
+      }
+
+      // Estimate context switches
+      let switches = 0;
+      for (let i = 1; i < ordered.length; i++) {
+        const prevCats = new Set(ordered[i - 1].cats);
+        const currCats = ordered[i].cats;
+        const overlap = currCats.some((c) => prevCats.has(c));
+        if (!overlap) switches++;
+        if (strategy === "locality" && ordered[i].dir !== ordered[i - 1].dir) switches++;
+      }
+
+      // Parallelization warnings
+      const warnings: string[] = [];
+      const hasSchema = classified.some((t) => t.cats.includes("schema"));
+      const hasTest = classified.some((t) => t.cats.includes("test"));
+      const hasApi = classified.some((t) => t.cats.includes("api"));
+      if (hasSchema && hasTest) warnings.push("⚠️ Schema changes and tests should NOT run in parallel — tests depend on schema state.");
+      if (hasSchema && hasApi) warnings.push("⚠️ Schema migrations and API changes should be sequential — API may reference new columns/tables.");
+      if (hasSchema) warnings.push("⚠️ Schema/migration tasks are non-parallelizable with anything that touches the DB.");
+
+      // Circular dependency check
+      const circularWarnings = detectCircularDeps(classified);
+      warnings.push(...circularWarnings);
+
+      const result = [
+        `## Sequenced Tasks (strategy: ${strategy})`,
+        `_Generated ${ts}_`,
+        "",
+        ...ordered.map((item, i) => `${i + 1}. ${item.task}`),
+        "",
+        "### Reasoning",
+        ...reasoning,
+        "",
+        `**Estimated context switches:** ${switches}`,
+        ...(warnings.length ? ["", "### Warnings", ...warnings] : []),
+      ].join("\n");
+
+      return { content: [{ type: "text" as const, text: result }] };
+    }
+  );
+}

package/src/tools/session-handoff.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { run, getBranch, getRecentCommits, getStatus } from "../lib/git.js";
+import { readIfExists, findWorkspaceDocs } from "../lib/files.js";
+import { STATE_DIR, now } from "../lib/state.js";
+
+/** Check if a CLI tool is available */
+function hasCommand(cmd: string): boolean {
+  const result = run(`command -v ${cmd} 2>/dev/null`);
+  return !!result && !result.startsWith("[command failed");
+}
+
+export function registerSessionHandoff(server: McpServer): void {
+  server.tool(
+    "session_handoff",
+    `Generate a handoff brief for the next session. Reads last checkpoint, recent commits, open PRs, workspace state, and correction patterns to create a "here's where we are" document. Call at session end or when starting a new session to catch up on what happened.`,
+    {
+      direction: z.enum(["outgoing", "incoming"]).describe("'outgoing' = ending this session, 'incoming' = starting a new one"),
+    },
+    async ({ direction }) => {
+      const branch = getBranch();
+      const sections: string[] = [];
+
+      if (direction === "incoming") {
+        const lastCheckpoint = readIfExists(".claude/last-checkpoint.md", 50);
+        const recentLog = getRecentCommits(10);
+        const dirty = getStatus();
+
+        sections.push(`## Session Handoff — INCOMING\n**Branch**: ${branch}\n**Time**: ${now()}`);
+
+        if (lastCheckpoint) {
+          sections.push(`## Last Checkpoint\n${lastCheckpoint}`);
+        } else {
+          sections.push(`## Last Checkpoint\nNone found. This may be the first session or checkpoints weren't saved.`);
+        }
+
+        sections.push(`## Recent Commits\n\`\`\`\n${recentLog}\n\`\`\``);
+
+        if (dirty) {
+          sections.push(`## Uncommitted Work\n\`\`\`\n${dirty}\n\`\`\``);
+        }
+
+        // Only try gh if it exists
+        if (hasCommand("gh")) {
+          const openPRs = run("gh pr list --state open --json number,title,headRefName 2>/dev/null || echo '[]'");
+          if (openPRs && openPRs !== "[]") {
+            sections.push(`## Open PRs\n\`\`\`json\n${openPRs}\n\`\`\``);
+          }
+        }
+
+        const docs = findWorkspaceDocs();
+        const freshDocs = Object.entries(docs)
+          .sort((a, b) => b[1].mtime.getTime() - a[1].mtime.getTime())
+          .slice(0, 5);
+        if (freshDocs.length > 0) {
+          sections.push(`## Most Recently Updated Workspace Docs\n${freshDocs.map(([n, d]) =>
+            `- .claude/${n} (updated ${Math.round((Date.now() - d.mtime.getTime()) / 3600000)}h ago)`
+          ).join("\n")}`);
+        }
+
+        // Correction patterns
+        const correctionFile = join(STATE_DIR, "corrections.jsonl");
+        if (existsSync(correctionFile)) {
+          try {
+            const raw = readFileSync(correctionFile, "utf-8").trim();
+            if (raw) {
+              const corr = raw.split("\n").filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+              if (corr.length > 0) {
+                const cats: Record<string, number> = {};
+                for (const c of corr) cats[c.category] = (cats[c.category] || 0) + 1;
+                sections.push(`## Known Error Patterns\n${Object.entries(cats).map(([k, v]) => `- ${k}: ${v}x`).join("\n")}\n\n**Watch out for these patterns.**`);
+              }
+            }
+          } catch { /* ignore parse errors */ }
+        }
+
+        sections.push(`## Recommendation\n1. Read the last checkpoint to understand where previous session left off\n2. Check git status for uncommitted work\n3. Read the most recently updated workspace docs\n4. Start with a specific task — don't try to "continue where we left off" without reading state first`);
+
+      } else {
+        // OUTGOING
+        const dirty = getStatus();
+        const dirtyCount = dirty ? dirty.split("\n").filter(Boolean).length : 0;
+        const recentLog = getRecentCommits(5);
+
+        sections.push(`## Session Handoff — OUTGOING\n**Branch**: ${branch}\n**Time**: ${now()}`);
+
+        if (dirtyCount > 0) {
+          sections.push(`## ⚠️ Uncommitted Work (${dirtyCount} files)\n\`\`\`\n${dirty}\n\`\`\`\n\n**Action**: Commit this work or it will be lost to the next session.`);
+
+          // Suggest stash if there's dirty work
+          const stashSuggestion = dirtyCount > 10
+            ? "\n💡 **Tip**: Consider `git stash` if you want to save work without committing."
+            : "";
+          if (stashSuggestion) sections.push(stashSuggestion);
+        }
+
+        sections.push(`## Recent Commits This Session\n\`\`\`\n${recentLog}\n\`\`\``);
+
+        // Check for today's checkpoint using date comparison
+        const lastCheckpoint = readIfExists(".claude/last-checkpoint.md", 10);
+        const hasRecentCheckpoint = (() => {
+          if (!lastCheckpoint) return false;
+          // Look for a timestamp line and compare dates
+          const match = lastCheckpoint.match(/\*\*Time\*\*:\s*(\S+)/);
+          if (!match) return false;
+          try {
+            const cpDate = new Date(match[1]);
+            // Consider "recent" if within last 4 hours
+            return (Date.now() - cpDate.getTime()) < 4 * 60 * 60 * 1000;
+          } catch { return false; }
+        })();
+
+        if (!hasRecentCheckpoint) {
+          sections.push(`## ⚠️ No recent checkpoint\nRun the \`checkpoint\` tool to save session state for the next session.`);
+        }
+
+        sections.push(`## Before ending:\n1. Commit all work\n2. Run \`checkpoint\` with summary + next steps\n3. Update any stale workspace docs (run \`audit_workspace\`)\n4. Push to remote`);
+      }
+
+      return { content: [{ type: "text" as const, text: sections.join("\n\n") }] };
+    }
+  );
+}

package/src/tools/session-health.ts

@@ -0,0 +1,107 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getBranch, getStatus, getLastCommit, getLastCommitTime, run } from "../lib/git.js";
+import { readIfExists, findWorkspaceDocs } from "../lib/files.js";
+import { loadState, saveState } from "../lib/state.js";
+import { getConfig } from "../lib/config.js";
+
+/** Parse a git date string safely, returning null on failure */
+function parseGitDate(dateStr: string): Date | null {
+  if (!dateStr || dateStr.startsWith("[command failed")) return null;
+  const d = new Date(dateStr);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+export function registerSessionHealth(server: McpServer): void {
+  server.tool(
+    "check_session_health",
+    `Check session health and recommend whether to continue, checkpoint, or start fresh. Tracks session depth, uncommitted work, workspace staleness, and time since last commit. Call periodically during long sessions.`,
+    {
+      stale_threshold_hours: z.number().optional().describe("Hours before a doc is considered stale. Default: 2"),
+    },
+    async ({ stale_threshold_hours }) => {
+      const config = getConfig();
+      const staleHours = stale_threshold_hours ?? (config.thresholds.session_stale_minutes / 60);
+      const branch = getBranch();
+      const dirty = getStatus();
+      const dirtyCount = dirty ? dirty.split("\n").filter(Boolean).length : 0;
+      const lastCommit = getLastCommit();
+      const lastCommitTimeStr = getLastCommitTime();
+      const uncommittedDiff = run("git diff --stat | tail -1");
+
+      // Parse commit time safely
+      const commitDate = parseGitDate(lastCommitTimeStr);
+      const minutesSinceCommit = commitDate
+        ? Math.round((Date.now() - commitDate.getTime()) / 60000)
+        : null;
+
+      // Track session start time
+      const sessionState = loadState("session-health");
+      if (!sessionState.sessionStart) {
+        sessionState.sessionStart = Date.now();
+        sessionState.checkCount = 0;
+        saveState("session-health", sessionState);
+      }
+      sessionState.checkCount = (sessionState.checkCount || 0) + 1;
+      saveState("session-health", sessionState);
+
+      const sessionMinutes = Math.round((Date.now() - sessionState.sessionStart) / 60000);
+
+      const lastCheckpoint = readIfExists(".claude/last-checkpoint.md", 20);
+
+      const docs = findWorkspaceDocs();
+      const staleThresholdMs = staleHours * 60 * 60 * 1000;
+      const staleDocs = Object.entries(docs)
+        .filter(([, d]) => (Date.now() - d.mtime.getTime()) > staleThresholdMs)
+        .map(([n]) => n);
+
+      const issues: string[] = [];
+      let severity = "healthy";
+
+      if (dirtyCount > 15) { issues.push(`🚨 ${dirtyCount} uncommitted files — commit now`); severity = "critical"; }
+      else if (dirtyCount > 5) { issues.push(`⚠️ ${dirtyCount} uncommitted files — consider committing`); severity = "warning"; }
+
+      const staleMinutes = config.thresholds.session_stale_minutes;
+      if (minutesSinceCommit !== null) {
+        if (minutesSinceCommit > staleMinutes * 4) { issues.push(`🚨 ${minutesSinceCommit}min since last commit — checkpoint immediately`); severity = "critical"; }
+        else if (minutesSinceCommit > staleMinutes * 2) { issues.push(`⚠️ ${minutesSinceCommit}min since last commit — commit soon`); if (severity !== "critical") severity = "warning"; }
+      } else {
+        issues.push("⚠️ Could not determine last commit time");
+      }
+
+      if (sessionMinutes > 180) { issues.push(`🚨 Session running ${sessionMinutes}min — consider starting fresh`); severity = "critical"; }
+      else if (sessionMinutes > 90) { issues.push(`⚠️ Session running ${sessionMinutes}min — checkpoint soon`); if (severity !== "critical") severity = "warning"; }
+
+      if (staleDocs.length > 3) { issues.push(`📝 ${staleDocs.length} workspace docs are >${staleHours}h stale: ${staleDocs.slice(0, 3).join(", ")}`); }
+
+      const recommendation = severity === "critical"
+        ? "🚨 **STOP and checkpoint.** Run `checkpoint` tool now. Commit all work, save state, consider starting fresh."
+        : severity === "warning"
+          ? "⚠️ **Checkpoint soon.** Commit current batch, update workspace docs if needed."
+          : "✅ **Session is healthy.** Continue working.";
+
+      const commitTimeStr = minutesSinceCommit !== null ? `${minutesSinceCommit}min ago` : "unknown";
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: `## Session Health Report
+
+**Branch**: ${branch}
+**Session duration**: ${sessionMinutes}min (check #${sessionState.checkCount})
+**Uncommitted**: ${dirtyCount} files
+**Last commit**: ${lastCommit} (${commitTimeStr})
+**Changes**: ${uncommittedDiff || "none"}
+**Stale docs**: ${staleDocs.length > 0 ? staleDocs.join(", ") : "none"}
+**Last checkpoint**: ${lastCheckpoint ? "exists" : "none"}
+
+### Issues
+${issues.length ? issues.join("\n") : "None — session is healthy"}
+
+### Recommendation
+${recommendation}`,
+        }],
+      };
+    }
+  );
+}