codetrap 0.1.6 → 0.1.7

package/README.md

@@ -160,7 +160,8 @@ codetrap/
 | `repair-scope` | Move legacy mis-scoped project traps into the current project (dry-run by default, `--apply` to mutate, `--json`) |
 | `migrate-project` | Move project traps between initialized projects (`--from-project-path`, `--to-project-path`, dry-run by default, `--apply`, `--json`) |
 | `embed` | Generate embeddings (requires JINA_API_KEY) |
-| `session` | Start a development session, append notes, promote explicit structured trap notes into candidates, and accept/reject candidates |
+| `session` | Start a development session, append notes, promote explicit structured trap notes into candidates, accept/reject candidates, and clean up session files |
+| `web` | Start the local review and trap library console |
 | `serve` | Start MCP server |
 
 ### Session Mode
@@ -179,6 +180,14 @@ codetrap session accept cand-001
 
 `session accept` writes the confirmed lesson through `TrapOperations`, attaches session evidence, and checks similar active traps before saving. `--edit-json` is applied before the conflict check, so edits to scope/module/title/tags/path globs affect both the saved trap and conflict detection. If a possible conflict is found, the candidate keeps its edited trap shape and conflict diagnostics; use `--accept-anyway` to keep both traps or `--supersedes <trap-id>` to preserve lifecycle history.
 
+Session maintenance commands keep temporary files from becoming stale context:
+
+```bash
+codetrap session cleanup <session-id> --deleted-trap-candidates
+codetrap session delete <session-id>
+codetrap session prune --older-than 90d --apply
+```
+
 ## Agent Integration
 
 For AI coding agents, use the CLI as the default integration path:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
   "type": "module",
   "license": "MIT",

package/src/commands/workflow.ts

@@ -10,6 +10,7 @@ import {
 } from "../lib/scope-migration";
 import { TrapOperations } from "../lib/trap-operations";
 import { buildDoctorReport, formatDoctorText } from "../lib/doctor";
+import { formatEmbedText } from "../lib/embed-output";
 import { searchDefaultsFromConfig } from "../lib/config";
 import { SessionStore } from "../lib/session-store";
 import { SessionOperations, type SessionConflictResult } from "../lib/session-operations";
@@ -44,6 +45,7 @@ import {
   sessionIdRequestFromArgs,
   sessionListRequestFromArgs,
   sessionNoteRequestFromArgs,
+  sessionPruneRequestFromArgs,
   sessionRejectRequestFromArgs,
   sessionShowRequestFromArgs,
   sessionStartRequestFromArgs,
@@ -380,12 +382,7 @@ async function cmdEmbed(args: string[], store: TrapStore): Promise<CommandResult
   const { opts } = parseArgs(args);
   try {
     const result = await store.ensureEmbeddings(embedRequestFromArgs(opts));
-    return textResult([
-      ...result.scopes.map((scoped) =>
-        `[${scoped.scope}] embeddings generated: ${scoped.generated}, skipped: ${scoped.skipped}, batches: ${scoped.batches}`
-      ),
-      `Total generated: ${result.generated}, skipped: ${result.skipped}, batches: ${result.batches}`,
-    ].join("\n"));
+    return textResult(formatEmbedText(result));
   } catch (error) {
     return errorFrom(error);
   }
@@ -424,8 +421,14 @@ async function cmdSession(args: string[], store: TrapStore, trapOperations: Trap
         return cmdSessionAccept(rest, sessions);
       case "reject":
         return cmdSessionReject(rest, sessions);
+      case "delete":
+        return cmdSessionDelete(rest, sessions);
+      case "prune":
+        return cmdSessionPrune(rest, sessions);
+      case "cleanup":
+        return cmdSessionCleanup(rest, sessions);
       default:
-        return errorResult("Usage: codetrap session <start|note|status|list|show|notes|close|candidates|candidate|accept|reject>");
+        return errorResult("Usage: codetrap session <start|note|status|list|show|notes|close|candidates|candidate|accept|reject|delete|prune|cleanup>");
     }
   } catch (error) {
     return errorFrom(error);
@@ -589,6 +592,45 @@ function cmdSessionReject(args: string[], sessions: SessionOperations): CommandR
   return textResult(`Rejected ${rejected.candidate.id}.`);
 }
 
+function cmdSessionDelete(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionShowRequestFromArgs(positionals);
+  const result = sessions.deleteSession(request.sessionId);
+  const payload = { success: result.deleted, ...result };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult(`Deleted session ${result.session_id}.`);
+}
+
+function cmdSessionPrune(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const result = sessions.pruneSessions(sessionPruneRequestFromArgs(opts));
+  if (opts.json !== undefined) return jsonResult(result);
+  const verb = result.dry_run ? "Would delete" : "Deleted";
+  const lines = [`${verb} ${result.dry_run ? result.sessions.length : result.deleted_count} session(s) older than ${result.cutoff}.`];
+  if (result.dry_run && result.sessions.length > 0) {
+    lines.push("Run with --apply to delete them.");
+  }
+  lines.push(...result.sessions.map((session) => `- ${session.id} [${session.status}] ${session.goal}`));
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionCleanup(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  if (opts["deleted-trap-candidates"] === undefined && opts.deleted_trap_candidates === undefined) {
+    return errorResult("Usage: codetrap session cleanup [session-id] --deleted-trap-candidates [--json]");
+  }
+  const request = sessionIdRequestFromArgs(positionals);
+  const result = sessions.cleanupDeletedTrapCandidates(request.sessionId);
+  const payload = {
+    success: true,
+    session_id: result.session.id,
+    removed_count: result.removed_count,
+    removed_candidate_ids: result.removed_candidate_ids,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult(`Removed ${result.removed_count} deleted-trap candidate(s) from session ${result.session.id}.`);
+}
+
 function formatStatsText(stats: ReturnType<TrapOperations["getStats"]>): string {
   const sections: string[] = [];
   if (stats.project) {

package/src/db/connection.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { getGlobalDB, getProjectDB } from "../lib/scope";
 import { initSchema } from "./schema";
 
-let globalDB: Database | null = null;
+const globalDBs = new Map<string, Database>();
 const projectDBs = new Map<string, Database>();
 
 export function openDatabase(path = ":memory:"): Database {
@@ -11,12 +11,12 @@ export function openDatabase(path = ":memory:"): Database {
   return db;
 }
 
-export function openGlobal(): Database {
-  if (!globalDB) {
-    const path = getGlobalDB();
-    globalDB = openDatabase(path);
+export function openGlobal(home?: string): Database {
+  const path = getGlobalDB(home);
+  if (!globalDBs.has(path)) {
+    globalDBs.set(path, openDatabase(path));
   }
-  return globalDB;
+  return globalDBs.get(path)!;
 }
 
 export function openProject(root: string): Database {

package/src/index.ts

@@ -47,7 +47,7 @@ function showHelp(): void {
   console.log("  supersede_trap        Mark one trap as superseded by another");
   console.log("  embed                 Generate embeddings for semantic search");
   console.log("  session               Record implementation notes and capture candidate traps");
-  console.log("  web                   Start local candidate review console");
+  console.log("  web                   Start local review and trap library console");
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
@@ -68,9 +68,9 @@ function showHelp(): void {
   console.log("  --no-rerank             Disable query-aware search reranking");
   console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");
-  console.log("  --project <path>        Project path for web review console");
-  console.log("  --host <host>           Host for web review console (default 127.0.0.1)");
-  console.log("  --port <n>              Port for web review console (default 4737)");
+  console.log("  --project <path>        Project path for web console");
+  console.log("  --host <host>           Host for web console (default 127.0.0.1)");
+  console.log("  --port <n>              Port for web console (default 4737)");
   console.log("  --json                  JSON output for search/show/list/stats/doctor; JSON input for add/edit");
   console.log("  --output-json           JSON output for add/edit when --json is used as input");
   console.log("  --from-project-path <path>  Source project path for scope repair/migration");

package/src/lib/command-requests.ts

@@ -63,6 +63,11 @@ export type SessionRejectRequest = SessionCandidateRequest & {
   reason?: string;
 };
 
+export type SessionPruneRequest = {
+  olderThanDays: number;
+  apply: boolean;
+};
+
 export type SessionNoteStdin = {
   isTTY: boolean;
   read: () => string;
@@ -205,6 +210,15 @@ export function sessionRejectRequestFromArgs(positionals: string[], args: RawArg
   };
 }
 
+export function sessionPruneRequestFromArgs(args: RawArgs): SessionPruneRequest {
+  const olderThan = stringOption(args, "older_than", "older-than");
+  if (!olderThan) throw new Error("--older-than is required.");
+  return {
+    olderThanDays: parseDurationDays(olderThan),
+    apply: flagPresent(args, "apply"),
+  };
+}
+
 function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
   for (const key of keys) {
     const value = args[key];
@@ -282,6 +296,14 @@ function jsonObjectOption(args: RawArgs, key: string): Record<string, unknown> |
   }
 }
 
+function parseDurationDays(value: string): number {
+  const match = value.trim().match(/^(\d+)\s*(d|day|days)?$/i);
+  if (!match) throw new Error(`Invalid duration: ${value}. Use a value like 90d.`);
+  const days = Number.parseInt(match[1], 10);
+  if (!Number.isInteger(days) || days <= 0) throw new Error(`Invalid duration: ${value}. Use a positive day count.`);
+  return days;
+}
+
 function requiredPositional(positionals: string[], index: number, name: string): string {
   const value = positionals[index];
   if (!value) throw new Error(`${name} is required.`);

package/src/lib/doctor.ts

@@ -1,9 +1,14 @@
 import type { TrapStore } from "./store";
 import type { TrapOperations } from "./trap-operations";
-import type { EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
+import type { EmbeddingStateSummary, EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
 import { createScopeContext } from "./scope-context";
 import { hybridFallbackReason } from "./embedding-health";
 
+export type DoctorNextAction = {
+  command: string;
+  reason: string;
+};
+
 export type DoctorReport = {
   cwd: string;
   project_root: string | null;
@@ -23,6 +28,7 @@ export type DoctorReport = {
       global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
     };
   };
+  next_actions: DoctorNextAction[];
   mcp_hint: string;
 };
 
@@ -35,6 +41,7 @@ export function buildDoctorReport(
   const stats = operations.getStats();
   const embeddings = operations.getEmbeddingStats();
   const semanticAvailable = store.hasEmbeddingProvider();
+  const diagnostics = store.diagnostics();
 
   return {
     ...scope,
@@ -48,8 +55,9 @@ export function buildDoctorReport(
       fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
     },
     diagnostics: {
-      mis_scoped_traps: store.diagnostics().mis_scoped_traps,
+      mis_scoped_traps: diagnostics.mis_scoped_traps,
     },
+    next_actions: buildDoctorNextActions(semanticAvailable, embeddings, diagnostics),
     mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
   };
 }
@@ -70,10 +78,62 @@ export function formatDoctorText(report: DoctorReport): string {
     `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
     "Diagnostics:",
     `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
+    "Next actions:",
+    ...formatNextActions(report.next_actions),
     `mcp_hint: ${report.mcp_hint}`,
   ].join("\n");
 }
 
+function buildDoctorNextActions(
+  semanticAvailable: boolean,
+  embeddings: EmbeddingStatsResult,
+  diagnostics: ReturnType<TrapStore["diagnostics"]>
+): DoctorNextAction[] {
+  const actions: DoctorNextAction[] = [];
+  if (!semanticAvailable) {
+    actions.push({
+      command: "export JINA_API_KEY=<your-jina-api-key>",
+      reason: "Enable semantic and hybrid search; otherwise use --mode fts.",
+    });
+  } else {
+    const projectAction = embeddingRefreshAction("project", embeddings.project);
+    const globalAction = embeddingRefreshAction("global", embeddings.global);
+    if (projectAction) actions.push(projectAction);
+    if (globalAction) actions.push(globalAction);
+  }
+
+  const stranded = diagnostics.mis_scoped_traps.global_db_project_traps.length;
+  if (stranded > 0) {
+    actions.push({
+      command: "codetrap repair-scope --dry-run --json",
+      reason: `${stranded} project-scoped trap(s) are stored in the global database.`,
+    });
+  }
+  return actions;
+}
+
+function embeddingRefreshAction(
+  scope: "project" | "global",
+  stats: EmbeddingStateSummary | null
+): DoctorNextAction | null {
+  if (!stats || stats.total === 0) return null;
+  const needsRefresh = stats.missing + stats.stale;
+  if (needsRefresh === 0) return null;
+  const parts = [
+    stats.missing > 0 ? `${stats.missing} missing` : null,
+    stats.stale > 0 ? `${stats.stale} stale` : null,
+  ].filter((item): item is string => item !== null);
+  return {
+    command: `codetrap embed --scope ${scope}`,
+    reason: `${scope} embeddings need refresh (${parts.join(", ")}).`,
+  };
+}
+
+function formatNextActions(actions: DoctorNextAction[]): string[] {
+  if (actions.length === 0) return ["  (none)"];
+  return actions.map((action) => `  - ${action.command} # ${action.reason}`);
+}
+
 function formatEmbeddingStats(
   label: string,
   stats: EmbeddingStatsResult["global"] | null

package/src/lib/embed-output.ts

@@ -0,0 +1,26 @@
+export type EmbedCommandResult = {
+  generated: number;
+  skipped: number;
+  batches: number;
+  scopes: { scope: string; generated: number; skipped: number; batches: number }[];
+};
+
+export function formatEmbedText(result: EmbedCommandResult): string {
+  return [
+    ...result.scopes.map((scoped) =>
+      `[${scoped.scope}] embeddings generated: ${scoped.generated}, skipped: ${scoped.skipped}, batches: ${scoped.batches}`
+    ),
+    `Total generated: ${result.generated}, skipped: ${result.skipped}, batches: ${result.batches}`,
+    `Next: ${embedNextAction(result)}`,
+  ].join("\n");
+}
+
+function embedNextAction(result: EmbedCommandResult): string {
+  if (result.generated > 0) {
+    return 'codetrap search "<query>" --mode hybrid';
+  }
+  if (result.skipped > 0) {
+    return "embeddings are already fresh; run codetrap doctor to verify hybrid search.";
+  }
+  return "add traps first, then rerun codetrap embed --scope project or --scope global.";
+}

package/src/lib/scope-context.ts

@@ -15,14 +15,14 @@ export type ScopeContext = {
   global_db: string;
 };
 
-export function createScopeContext(cwd = process.cwd()): ScopeContext {
-  const resolvedCwd = resolveScopePath(cwd);
-  const projectRoot = findProjectRoot(resolvedCwd);
+export function createScopeContext(cwd = process.cwd(), home?: string): ScopeContext {
+  const resolvedCwd = resolveScopePath(cwd, home ?? cwd);
+  const projectRoot = findProjectRoot(resolvedCwd, home);
   return {
     cwd: resolvedCwd,
     project_root: projectRoot,
     project_db: projectRoot ? scopePath.join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
-    global_db: getGlobalDB(),
+    global_db: getGlobalDB(home),
   };
 }
 
@@ -36,8 +36,8 @@ export class ScopedRepositoryContext {
   private globalRepository?: TrapRepository;
   private projectRepository?: TrapRepository;
 
-  constructor(cwd = process.cwd(), private readonly embedder?: EmbeddingProvider) {
-    this.context = createScopeContext(cwd);
+  constructor(cwd = process.cwd(), private readonly embedder?: EmbeddingProvider, private readonly home?: string) {
+    this.context = createScopeContext(cwd, home);
   }
 
   hasProject(): boolean {
@@ -94,7 +94,7 @@ export class ScopedRepositoryContext {
 
   private globalRepo(): TrapRepository {
     if (!this.globalRepository) {
-      this.globalRepository = new TrapRepository(openGlobal(), this.embedder);
+      this.globalRepository = new TrapRepository(openGlobal(this.home), this.embedder);
     }
     return this.globalRepository;
   }

package/src/lib/scope.ts

@@ -5,14 +5,14 @@ import { defaultScopePathResolver, resolveScopePath, ScopePathResolver } from ".
 
 export { resolveScopePath, ScopePathResolver } from "./scope-path";
 
-export function getGlobalDir(): string {
-  const dir = defaultScopePathResolver.join(homedir(), CODETRAP_DIR);
+export function getGlobalDir(homeDir = homedir()): string {
+  const dir = defaultScopePathResolver.join(homeDir, CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   return dir;
 }
 
-export function getGlobalDB(): string {
-  return defaultScopePathResolver.join(getGlobalDir(), TRAPS_DB_FILE);
+export function getGlobalDB(homeDir = homedir()): string {
+  return defaultScopePathResolver.join(getGlobalDir(homeDir), TRAPS_DB_FILE);
 }
 
 export function findProjectRoot(

package/src/lib/search-eval.ts

@@ -56,6 +56,11 @@ export type SearchEvalMetrics = {
   semantic_error_count: number;
 };
 
+export type SearchEvalNextAction = {
+  command: string;
+  reason: string;
+};
+
 export type SearchEvalReport = {
   mode: "deterministic" | "live";
   fixture: string;
@@ -71,6 +76,7 @@ export type SearchEvalReport = {
   failures: EvalCaseReport[];
   misses: EvalCaseReport[];
   noisy_hits: EvalCaseReport[];
+  next_actions: SearchEvalNextAction[];
 };
 
 export type RecordDogfoodResult = {
@@ -111,17 +117,22 @@ export async function reportDogfood(fixturePath: string, live: boolean): Promise
   const fixture = readEvalFixture(fixturePath);
   const provider = live ? createDefaultEmbeddingProvider() : new EvalEmbedder();
   const evaluated = await evaluateSearchFixture(fixture, provider);
-  return {
-    mode: live ? "live" : "deterministic",
+  const mode: SearchEvalReport["mode"] = live ? "live" : "deterministic";
+  const report: Omit<SearchEvalReport, "next_actions"> = {
+    mode,
     fixture: fixturePath,
     ...evaluated,
   };
+  return {
+    ...report,
+    next_actions: buildSearchEvalNextActions(report),
+  };
 }
 
 export async function evaluateSearchFixture(
   fixture: EvalFixture,
   provider: EmbeddingProvider | undefined
-): Promise<Omit<SearchEvalReport, "mode" | "fixture">> {
+): Promise<Omit<SearchEvalReport, "mode" | "fixture" | "next_actions">> {
   const repo = fixtureRepository(fixture, provider);
 
   let providerError: string | null = null;
@@ -153,6 +164,9 @@ export async function evaluateSearchFixture(
   }
 
   const dogfoodCases = cases.filter((item) => item.phaseGate === "dogfood" || item.judgment !== undefined);
+  const failures = cases.filter((item) => !item.passed);
+  const misses = cases.filter((item) => item.judgment === "miss" || item.recallAt5 < (fixtureQuery(item, fixture)?.minRecallAt5 ?? 1));
+  const noisyHits = cases.filter((item) => item.judgment === "noisy_hit");
   const metrics = aggregateMetrics(cases);
   return {
     provider: provider ? embeddingConfig(provider) : null,
@@ -173,9 +187,9 @@ export async function evaluateSearchFixture(
         no_relevant_trap: dogfoodCases.filter((item) => item.judgment === "no_relevant_trap").length,
       },
     },
-    failures: cases.filter((item) => !item.passed),
-    misses: cases.filter((item) => item.judgment === "miss" || item.recallAt5 < (fixtureQuery(item, fixture)?.minRecallAt5 ?? 1)),
-    noisy_hits: cases.filter((item) => item.judgment === "noisy_hit"),
+    failures,
+    misses,
+    noisy_hits: noisyHits,
   };
 }
 
@@ -211,11 +225,90 @@ export function formatSearchEvalReport(report: SearchEvalReport): string {
     `MRR: ${report.metrics.mrr}`,
     `Hybrid fallback count: ${report.metrics.hybrid_fallback_count}`,
     `Semantic error count: ${report.metrics.semantic_error_count}`,
-    `Dogfood cases: ${report.dogfood.total}`
+    `Dogfood cases: ${report.dogfood.total}`,
+    `Judgments: ${formatJudgmentCounts(report.dogfood.judgment_counts)}`
   );
+  appendCaseSection(lines, "Failures", report.failures);
+  appendCaseSection(lines, "Misses to inspect", report.misses);
+  appendCaseSection(lines, "Noisy hits to inspect", report.noisy_hits);
+  lines.push("Next actions:", ...formatNextActions(report.next_actions));
   return lines.join("\n");
 }
 
+function buildSearchEvalNextActions(
+  report: Omit<SearchEvalReport, "next_actions">
+): SearchEvalNextAction[] {
+  const actions: SearchEvalNextAction[] = [];
+  if (report.mode === "live" && !report.semantic_available) {
+    actions.push({
+      command: "export JINA_API_KEY=<your-jina-api-key>",
+      reason: "Enable live semantic checks, then rerun bun run eval:dogfood -- report --live.",
+    });
+  }
+  if (report.failures.length > 0) {
+    actions.push({
+      command: "bun run eval:dogfood -- report --json",
+      reason: "Inspect expected ids, top results, and errors before changing search behavior or fixture expectations.",
+    });
+  }
+  if (report.misses.length > 0) {
+    actions.push({
+      command: 'codetrap search "<miss query>" --mode hybrid --ranking-signals --json',
+      reason: "Replay a miss with ranking signals before deciding whether to tune search or promote a fixture case.",
+    });
+  }
+  if (report.noisy_hits.length > 0) {
+    actions.push({
+      command: 'codetrap search "<noisy query>" --mode hybrid --ranking-signals --json',
+      reason: "Inspect why noisy results ranked before deciding whether the case belongs in dogfood eval.",
+    });
+  }
+  if (actions.length === 0) {
+    actions.push({
+      command: 'codetrap search "<task keywords>" --mode hybrid --json',
+      reason: "Keep logging real pre-edit searches in dogfood-log.md before automating promotion.",
+    });
+  }
+  return actions;
+}
+
+function formatJudgmentCounts(counts: Record<DogfoodJudgment, number>): string {
+  return DOGFOOD_JUDGMENTS.map((judgment) => `${judgment}=${counts[judgment]}`).join(", ");
+}
+
+function appendCaseSection(lines: string[], title: string, cases: EvalCaseReport[]): void {
+  if (cases.length === 0) return;
+  lines.push(`${title}:`);
+  for (const item of cases.slice(0, 5)) {
+    lines.push(`  - [${item.mode}] ${item.query}`);
+    if (item.goldTrapIds.length > 0) {
+      lines.push(`    expected: ${formatExpected(item)}`);
+    }
+    lines.push(`    top: ${formatTopResults(item)}`);
+    if (item.error) lines.push(`    error: ${item.error}`);
+  }
+  if (cases.length > 5) lines.push(`  ... ${cases.length - 5} more`);
+}
+
+function formatExpected(item: EvalCaseReport): string {
+  return item.goldTrapIds
+    .map((id, index) => `#${id} ${item.expectedTitles[index] ?? ""}`.trim())
+    .join(", ");
+}
+
+function formatTopResults(item: EvalCaseReport): string {
+  if (item.topResults.length === 0) return "(none)";
+  return item.topResults
+    .slice(0, 3)
+    .map((result) => `#${result.id} ${result.title}`)
+    .join("; ");
+}
+
+function formatNextActions(actions: SearchEvalNextAction[]): string[] {
+  if (actions.length === 0) return ["  (none)"];
+  return actions.map((action) => `  - ${action.command} # ${action.reason}`);
+}
+
 function fixtureRepository(fixture: EvalFixture, provider: EmbeddingProvider | undefined): TrapRepository {
   const repo = new TrapRepository(openDatabase(":memory:"), provider);
   for (const trap of fixture.traps) repo.add(trap);

package/src/lib/session-operations.ts

@@ -1,11 +1,15 @@
 import type { CandidateTrap } from "../domain/session";
 import { buildTrapInput } from "../domain/trap";
+import type { Scope } from "./constants";
 import type { TrapOperations } from "./trap-operations";
 import { findCandidateConflicts, type CandidateConflict } from "./session-conflicts";
 import type {
   AcceptCandidateResult,
   AddSessionNoteArgs,
   CloseSessionResult,
+  DeleteSessionResult,
+  PruneSessionsResult,
+  RemoveSessionCandidatesResult,
   SessionStore,
   StartSessionArgs,
 } from "./session-store";
@@ -30,6 +34,12 @@ export type SessionRejectRequest = {
   reason?: string | null;
 };
 
+export type SessionPruneRequest = {
+  olderThanDays: number;
+  apply: boolean;
+  now?: Date;
+};
+
 export type SessionConflictResult = {
   success: false;
   session_id: string;
@@ -155,6 +165,29 @@ export class SessionOperations {
       reason: request.reason,
     });
   }
+
+  deleteSession(sessionId: string): DeleteSessionResult {
+    return this.sessions.deleteSession(sessionId);
+  }
+
+  pruneSessions(request: SessionPruneRequest): PruneSessionsResult {
+    const now = request.now ?? new Date();
+    const cutoff = new Date(now.getTime() - request.olderThanDays * 24 * 60 * 60 * 1000);
+    return this.sessions.pruneSessions({ cutoff, dryRun: !request.apply });
+  }
+
+  cleanupDeletedTrapCandidates(sessionId?: string): RemoveSessionCandidatesResult {
+    const document = this.sessions.candidateDocument(sessionId);
+    const missingCandidateIds = document.candidates
+      .filter((candidate) => candidate.status === "accepted")
+      .filter((candidate) => {
+        const trapId = candidate.accepted_trap_id;
+        if (trapId === undefined) return true;
+        return !this.traps.getTrapDetails(trapId, acceptedScope(candidate));
+      })
+      .map((candidate) => candidate.id);
+    return this.sessions.removeCandidates(sessionId, missingCandidateIds);
+  }
 }
 
 function candidateWithTrapEdits(candidate: CandidateTrap, edit: Record<string, unknown> | undefined): CandidateTrap {
@@ -209,6 +242,10 @@ function candidateRelatedFiles(candidate: CandidateTrap): string[] {
   return uniqueStrings(candidate.evidence.flatMap((evidence) => evidence.related_files ?? []));
 }
 
+function acceptedScope(candidate: CandidateTrap): Scope {
+  return candidate.accepted_scope ?? (candidate.trap.scope === "global" ? "global" : "project");
+}
+
 function uniqueStrings(values: string[]): string[] {
   return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }