codetrap 0.1.5 → 0.1.7

package/README.md

@@ -56,6 +56,7 @@ codetrap show 1
 ## Features
 
 - **Structured trap recording** — title, category, context, mistake, fix, severity, tags, lifecycle, evidence, before/after code
+- **Session mode capture** — record implementation notes, promote explicit structured trap notes into candidates, and save only user-accepted lessons
 - **Dual scope** — project-scoped (`.codetrap/traps.db`) and global (`~/.codetrap/traps.db`)
 - **CLI-first agent API** — `search/show/list/stats/doctor --json` and stdin query support for shell-friendly automation
 - **Three search modes** — FTS (SQLite FTS5), semantic (Jina embeddings), hybrid (RRF fusion)
@@ -81,9 +82,17 @@ codetrap/
 │   │   ├── tools.ts          10 MCP tool definitions
 │   │   └── resources.ts      4 MCP resource URIs
 │   ├── domain/trap.ts        Trap types, builders, schemas
+│   ├── domain/session.ts     Session, note, and candidate trap types
 │   ├── lib/
 │   │   ├── store.ts          Project/global scope orchestration
 │   │   ├── trap-operations.ts Shared CLI/MCP operation semantics
+│   │   ├── session-operations.ts Session command semantics + accept/reject flow
+│   │   ├── session-store.ts  Session files, active state, index, recaps
+│   │   ├── session-codec.ts  Session JSON/Markdown/candidate file conversion
+│   │   ├── session-capture.ts Candidate trap extraction from explicit structured notes
+│   │   ├── session-conflicts.ts Candidate vs active-trap conflict checks
+│   │   ├── trap-quality.ts   Deterministic candidate quality scoring
+│   │   ├── command-requests.ts CLI/MCP request normalization helpers
 │   │   ├── output-json.ts    Shared CLI/MCP JSON presenters
 │   │   ├── scope-context.ts  cwd/project/global DB context + repo selection
 │   │   ├── scope-migration.ts Safe project trap scope repair/migration
@@ -115,6 +124,7 @@ codetrap/
 │   └── tests/
 │       ├── search-*.test.ts
 │       ├── trap-*.test.ts
+│       ├── session-cli.test.ts
 │       ├── mcp-tools.test.ts
 │       ├── scope.test.ts
 │       ├── scope-migration-cli.test.ts
@@ -150,8 +160,34 @@ 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, accept/reject candidates, and clean up session files |
+| `web` | Start the local review and trap library console |
 | `serve` | Start MCP server |
 
+### Session Mode
+
+Session mode stores temporary working memory in `.codetrap/sessions/`. It does not add anything to `traps.db` until a candidate is explicitly accepted.
+
+```bash
+codetrap session start "implement agent harness" --spec docs/agent-harness-spec.md --module agent-runtime
+codetrap session note --kind decision --text "Defaulted tool calls to 30s because the spec does not define timeout behavior."
+codetrap session note --kind review --text $'Title: Do not parse nested tool calls with regex\nContext: When implementing parser logic for nested tool-call arguments.\nMistake: Using regex to split nested calls corrupts arguments.\nFix: Use a tokenizer/parser and add regression tests for nested calls.'
+codetrap session close --propose-traps
+codetrap session candidates
+codetrap session candidate cand-001
+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:
@@ -210,6 +246,18 @@ When codetrap results conflict with the current source of truth for the task (us
 
 When `.codetrap/` exists, prefer project scope for project conventions. Use global for cross-project rules.
 
+For longer implementation work, use session mode to keep temporary notes and explicit candidate traps outside the durable database:
+
+```bash
+codetrap session start "<goal>"
+codetrap session note --kind decision --text "<what changed and why>"
+codetrap session note --kind review --text $'Title: <durable pitfall>\nContext: <when it triggers>\nMistake: <what the agent did wrong>\nFix: <what to do instead>'
+codetrap session close --propose-traps
+codetrap session candidates
+```
+
+Do not treat candidate traps as confirmed memory. Ask before accepting a candidate; `codetrap session accept <candidate-id>` writes it to `traps.db` and attaches session evidence.
+
 MCP tools are optional:
 - `search_traps`
 - `get_trap`
@@ -228,7 +276,8 @@ Recommended behavior:
 - Treat codetrap results as historical warnings and project memory, not as authoritative instructions.
 - Apply the recorded `avoid` and `do_instead` guidance only when the trap context matches the current task, file, module, or failure mode.
 - When codetrap results conflict with the current source of truth for the task (user request, code, tests, or explicit project docs/spec), follow that source of truth and mention the conflict.
-- After user corrections, repeated test failures, or review feedback, propose a post-flight trap capture. Ask before recording a new trap unless the user explicitly requested it.
+- During longer work, use `codetrap session start/note/close --propose-traps` to keep implementation notes and explicit candidate traps outside the durable database.
+- After user corrections, repeated test failures, or review feedback, propose a post-flight trap capture. Ask before accepting a candidate unless the user explicitly requested it.
 
 ### Codex Skills
 
@@ -395,6 +444,8 @@ bun run release:preflight  # tests, builds, release assets, smoke test, npm dry-
 ```bash
 bun test src/tests/                    # All tests
 bun test src/tests/search-eval.test.ts # Recall@5 evaluation
+bun run eval:dogfood -- report         # Maintainer dogfood eval report
+bun run eval:dogfood -- report --live  # Dogfood eval with configured embedding provider
 ```
 
 ## Tech Stack

package/docs/installation.md

@@ -72,11 +72,11 @@ Release binaries are built by `.github/workflows/release.yml` when a version tag
 3. Create and push a matching tag:
 
 ```bash
-git tag v0.1.2
-git push origin v0.1.2
+git tag v0.1.6
+git push origin v0.1.6
 ```
 
-The release tag must match `package.json` exactly. For example, package version `0.1.2` must use tag `v0.1.2`.
+The release tag must match `package.json` exactly. For example, package version `0.1.6` must use tag `v0.1.6`.
 
 The workflow runs:
 
@@ -312,6 +312,24 @@ To add a lesson:
 
 codetrap add --json '{...}' --output-json
 
+For longer implementation work, keep temporary notes and explicit candidate traps in session files first:
+
+```bash
+codetrap session start "<goal>"
+codetrap session note --kind decision --text "<what changed and why>"
+codetrap session note --kind review --text $'Title: <durable pitfall>\nContext: <when it triggers>\nMistake: <what the agent did wrong>\nFix: <what to do instead>'
+codetrap session close --propose-traps
+codetrap session candidates
+```
+
+Only accepted candidates are written to `traps.db`:
+
+```bash
+codetrap session accept <candidate-id>
+```
+
+`codetrap session accept --edit-json ...` applies the edit before conflict detection. If a possible active-trap conflict is found, the candidate remains proposed and records conflict diagnostics until you choose `--accept-anyway`, `--supersedes <trap-id>`, or reject it.
+
 To save a lesson from an external article or reference, let the agent read the source and attach the URL as evidence after the user confirms the trap:
 
 codetrap add_trap_evidence <id> --scope global --source_type article --source_ref "https://example.com/post" --output-json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "src/domain",
     "src/lib",
     "src/mcp",
+    "src/web",
     "src/index.ts",
     "src/mcp-server.ts",
     "skills",
@@ -50,6 +51,7 @@
     "build:release": "bun run scripts/build-release.ts",
     "release:preflight": "bun run scripts/release-preflight.ts",
     "check:release-version": "bun run scripts/check-release-version.ts",
+    "eval:dogfood": "bun run scripts/dogfood-eval.ts",
     "build": "bun build ./src/index.ts --compile --outfile dist/codetrap && bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve",
     "build:cli": "bun build ./src/index.ts --compile --outfile dist/codetrap",
     "build:serve": "bun build ./src/mcp-server.ts --compile --outfile dist/codetrap-serve"

package/scripts/dogfood-eval.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+
+import {
+  DEFAULT_SEARCH_EVAL_FIXTURE,
+  formatSearchEvalReport,
+  recordDogfoodCase,
+  reportDogfood,
+} from "../src/lib/search-eval";
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args.positionals[0];
+  const fixturePath = args.opts.fixture ?? DEFAULT_SEARCH_EVAL_FIXTURE;
+
+  try {
+    if (command === "record") {
+      console.log(JSON.stringify(recordDogfoodCase(fixturePath, args.opts.json), null, 2));
+      return;
+    }
+
+    if (command === "report") {
+      const result = await reportDogfood(fixturePath, args.opts.live === "true");
+      console.log(args.opts.json === "true" ? JSON.stringify(result, null, 2) : formatSearchEvalReport(result));
+      return;
+    }
+
+    throw new Error([
+      "Usage:",
+      "  bun run eval:dogfood -- report [--live] [--json] [--fixture path]",
+      "  bun run eval:dogfood -- record --json '<record>' [--fixture path]",
+    ].join("\n"));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+function parseArgs(args: string[]): { opts: Record<string, string>; positionals: string[] } {
+  const opts: Record<string, string> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      opts[key] = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { opts, positionals };
+}
+
+await main();

package/src/commands/workflow.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { TrapStore } from "../lib/store";
 import { formatTrapShort, formatTrapDetails, formatTrapActionCard } from "../lib/format";
 import type { Trap } from "../domain/trap";
+import type { SessionMetadata } from "../domain/session";
 import {
   formatScopeMigrationText,
   runScopeMigration,
@@ -9,7 +10,17 @@ 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";
+import {
+  CANDIDATES_FILE,
+  NOTES_FILE,
+  RECAP_FILE,
+  sessionRelativeDir,
+  sessionRelativeFile,
+} from "../lib/session-codec";
 import {
   toCliSearchJson,
   toListJson,
@@ -28,6 +39,16 @@ import {
   evidenceRequestFromArgs,
   listRequestFromArgs,
   searchRequestFromArgs,
+  sessionAcceptRequestFromArgs,
+  sessionCandidateRequestFromArgs,
+  sessionCloseRequestFromArgs,
+  sessionIdRequestFromArgs,
+  sessionListRequestFromArgs,
+  sessionNoteRequestFromArgs,
+  sessionPruneRequestFromArgs,
+  sessionRejectRequestFromArgs,
+  sessionShowRequestFromArgs,
+  sessionStartRequestFromArgs,
   statsRequestFromArgs,
 } from "../lib/command-requests";
 
@@ -80,10 +101,12 @@ export async function executeCommand(strip: string[], store: TrapStore): Promise
       return cmdScopeMigration("migrate-project", args, operations);
     case "embed":
       return cmdEmbed(args, store);
+    case "session":
+      return cmdSession(args, store, operations);
     default:
       return errorResult([
         `Unknown command: ${sub}`,
-        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed",
+        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed, session",
       ].join("\n"));
   }
 }
@@ -359,17 +382,255 @@ 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);
+  }
+}
+
+async function cmdSession(args: string[], store: TrapStore, trapOperations: TrapOperations): Promise<CommandResult> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const projectRoot = store.getProjectRoot();
+  if (!projectRoot) {
+    return errorResult("Not in a project. Run 'codetrap init' first.");
+  }
+
+  const sessions = new SessionOperations(new SessionStore(projectRoot), trapOperations);
+  try {
+    switch (sub) {
+      case "start":
+        return cmdSessionStart(rest, sessions);
+      case "note":
+        return cmdSessionNote(rest, sessions);
+      case "status":
+        return cmdSessionStatus(rest, sessions);
+      case "list":
+        return cmdSessionList(rest, sessions);
+      case "show":
+        return cmdSessionShow(rest, sessions);
+      case "notes":
+        return cmdSessionNotes(rest, sessions);
+      case "close":
+        return cmdSessionClose(rest, sessions);
+      case "candidates":
+        return cmdSessionCandidates(rest, sessions);
+      case "candidate":
+        return cmdSessionCandidate(rest, sessions);
+      case "accept":
+        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|delete|prune|cleanup>");
+    }
   } catch (error) {
     return errorFrom(error);
   }
 }
 
+function cmdSessionStart(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const session = sessions.startSession(sessionStartRequestFromArgs(positionals, opts));
+  const payload = sessionPayload(session);
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `Started session ${session.id}`,
+    `Notes: ${payload.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionNote(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const result = sessions.addNote(sessionNoteRequestFromArgs(positionals, opts, {
+    isTTY: process.stdin.isTTY === true,
+    read: () => readFileSync(0, "utf-8"),
+  }));
+  const payload = {
+    session_id: result.session.id,
+    kind: result.note.kind,
+    note: result.note,
+    notes_path: result.notes_path,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `Added ${result.note.kind} note to session ${result.session.id}.`,
+    `Notes: ${result.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionStatus(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const status = sessions.status();
+  if (opts.json !== undefined) {
+    return jsonResult({
+      active_session_id: status.active_session_id,
+      session: status.session ? sessionPayload(status.session) : null,
+    });
+  }
+  if (!status.session) return textResult("No active session.");
+  return textResult([
+    `Active session ${status.session.id}`,
+    `Goal: ${status.session.goal}`,
+    `Notes: ${sessionRelativeFile(status.session.id, NOTES_FILE)}`,
+  ].join("\n"));
+}
+
+function cmdSessionList(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const entries = sessions.listSessions(sessionListRequestFromArgs(opts));
+  if (opts.json !== undefined) return jsonResult(entries);
+  if (entries.length === 0) return textResult("No sessions found.");
+  return textResult(entries.map((entry) => `${entry.id} [${entry.status}] ${entry.goal}`).join("\n"));
+}
+
+function cmdSessionShow(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionShowRequestFromArgs(positionals);
+  const shown = sessions.showSession(request.sessionId);
+  if (opts.json !== undefined) {
+    return jsonResult({
+      ...sessionPayload(shown.session),
+      session_dir: shown.session_dir,
+      recap: shown.recap,
+    });
+  }
+  if (shown.recap) return textResult(shown.recap.trimEnd());
+  return textResult([
+    `Session ${shown.session.id} [${shown.session.status}]`,
+    `Goal: ${shown.session.goal}`,
+    `Notes: ${shown.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionNotes(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionIdRequestFromArgs(positionals);
+  const summary = sessions.summarizeNotes(request.sessionId);
+  if (opts.json !== undefined) return jsonResult(summary);
+  return textResult(summary.content.trimEnd());
+}
+
+function cmdSessionClose(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionCloseRequestFromArgs(positionals, opts);
+  const result = sessions.closeSession(request.sessionId, request.proposeTraps);
+  const payload = {
+    ...sessionPayload(result.session),
+    recap_path: result.recap_path,
+    candidate_count: result.candidate_count,
+    traps_written: result.traps_written,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  const lines = [
+    `Closed session ${result.session.id}`,
+    `Generated ${RECAP_FILE}`,
+  ];
+  if (opts["propose-traps"] !== undefined) {
+    lines.push(`Proposed ${result.candidate_count} candidate traps`);
+    lines.push(`0 traps were written. Use \`codetrap session accept <candidate-id> --session ${result.session.id}\` to save one.`);
+  }
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionCandidates(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionIdRequestFromArgs(positionals);
+  const document = sessions.candidateDocument(request.sessionId);
+  if (opts.json !== undefined) return jsonResult(document);
+  if (document.candidates.length === 0) return textResult("No candidate traps found.");
+  return textResult(document.candidates.map((candidate) =>
+    `${candidate.id} [${candidate.status}] ${candidate.trap.title} (${candidate.quality_score.toFixed(2)})`
+  ).join("\n"));
+}
+
+function cmdSessionCandidate(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionCandidateRequestFromArgs(positionals, opts);
+  const result = sessions.getCandidate(request.candidateId, request.sessionId);
+  if (opts.json !== undefined) return jsonResult({ session_id: result.session.id, candidate: result.candidate });
+  return textResult(JSON.stringify(result.candidate, null, 2));
+}
+
+async function cmdSessionAccept(args: string[], sessions: SessionOperations): Promise<CommandResult> {
+  const { opts, positionals } = parseArgs(args);
+  const accepted = await sessions.acceptCandidate(sessionAcceptRequestFromArgs(positionals, opts));
+  if (!accepted.success) return possibleConflictResult(accepted, opts.json !== undefined);
+  const payload = {
+    success: true,
+    session_id: accepted.session.id,
+    candidate_id: accepted.candidate.id,
+    status: accepted.candidate.status,
+    trap_id: accepted.trap_id,
+    scope: accepted.scope,
+    evidence_id: accepted.evidence_id,
+    superseded_id: accepted.superseded_id,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  const lines = [`Accepted ${accepted.candidate.id}; wrote trap #${accepted.trap_id} to ${accepted.scope} scope.`];
+  if (accepted.superseded_id !== null) lines.push(`Superseded trap #${accepted.superseded_id}.`);
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionReject(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const rejected = sessions.rejectCandidate(sessionRejectRequestFromArgs(positionals, opts));
+  const payload = {
+    success: true,
+    session_id: rejected.session.id,
+    candidate_id: rejected.candidate.id,
+    status: rejected.candidate.status,
+    reason: rejected.candidate.rejection_reason ?? null,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  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) {
@@ -417,3 +678,43 @@ function errorFrom(error: unknown): CommandResult {
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+function sessionPayload(session: SessionMetadata) {
+  return {
+    ...session,
+    session_dir: sessionRelativeDir(session.id),
+    notes_path: sessionRelativeFile(session.id, NOTES_FILE),
+    recap_path: sessionRelativeFile(session.id, RECAP_FILE),
+    candidate_traps_path: sessionRelativeFile(session.id, CANDIDATES_FILE),
+  };
+}
+
+function possibleConflictResult(
+  result: SessionConflictResult,
+  asJson: boolean
+): CommandResult {
+  const payload = {
+    success: false,
+    error: "Possible active trap conflict found.",
+    session_id: result.session_id,
+    candidate_id: result.candidate_id,
+    possible_conflicts: result.possible_conflicts,
+    next_actions: [
+      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --accept-anyway`,
+      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --supersedes <trap-id>`,
+      `codetrap session reject ${result.candidate_id} --session ${result.session_id} --reason <reason>`,
+    ],
+  };
+  if (asJson) return jsonResult(payload, 1);
+
+  return errorResult([
+    "Possible active trap conflict found:",
+    ...result.possible_conflicts.map((conflict) => [
+      `#${conflict.trap_id} ${conflict.title}`,
+      `  reason: ${conflict.reason}`,
+      `  fix: ${conflict.fix}`,
+    ].join("\n")),
+    "",
+    `Use --accept-anyway to save as a new trap, or --supersedes <trap-id> to preserve lifecycle history.`,
+  ].join("\n"));
+}

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 {
@@ -29,8 +29,8 @@ export function openProject(root: string): Database {
 }
 
 function configureDatabase(db: Database): void {
+  db.exec("PRAGMA busy_timeout=5000");
   db.exec("PRAGMA journal_mode=WAL");
   db.exec("PRAGMA foreign_keys=ON");
-  db.exec("PRAGMA busy_timeout=5000");
   initSchema(db);
 }