@winspan/claude-forge 8.50.6 → 8.51.1

package/docs/design/project-path-gitroot-spec-20260518-1715.md

@@ -0,0 +1,134 @@
+# project-path git root 修复 Spec
+
+## 目标
+让 5 个 hook 在 IDE 调用时把 `cwd`（可能是任意子目录）上溯为 git 仓库根目录后再发给 daemon，从根上阻止子目录被生成 `.claude-forge/`。
+
+## 调研结果
+
+| 位置 | 现状 | 改造需求 |
+|---|---|---|
+| `src/hooks/pre-tool-use.sh:15-16` | `PROJECT_PATH=$(jq -r '.cwd'); fallback $PWD` | 套上 `resolve_project_path` |
+| `src/hooks/post-tool-use.sh:17-18` | 同上 | 同上 |
+| `src/hooks/user-prompt-submit.sh:15-16` | 同上 | 同上 |
+| `src/hooks/stop.sh:11-12` | 同上 + 未引用 hook-lib.sh | 先 source hook-lib.sh 再用函数 |
+| `src/hooks/notification.sh:13-14` | 同上 | 同上 |
+| `src/hooks/hook-lib.sh` | 已有 `send_event_or_enqueue` 公共函数 | **新增 `resolve_project_path`** |
+| `src/daemon/handlers/history-exporter.ts:24` | `path.join(project_path,'.claude-forge','history')` | 不动（hook 端已传 git root） |
+| `src/cli/commands/executions.ts:16,53,85` | `process.cwd()` 拼 `.claude-forge` | 新增 `resolveGitRoot()` helper |
+| `src/templates/template-manager.ts:82,89` | `initProject(_, projectPath)` 由调用方传入 | 调用方传 git root 即可（init CLI 自身改） |
+
+观察：`hook-lib.sh` 已存在公共函数集，`stop.sh` 是唯一未 source 它的 hook（手写 nc + socket），改造时顺手补齐一致性。
+
+## 方案选择
+
+| | A. Hook 端解析 git root | B. Daemon 端解析 | C. 完全消除目录 | D. 混合 hash |
+|---|---|---|---|---|
+| 改动面 | 5 hook + lib + CLI | 1 处 | 涉及多模块迁移 | A+ 存储改造 |
+| 性能 | bash 上溯（O(深度)，无子进程）| 每次 spawn `git` | 同 A | 同 A |
+| 下游受益 | 全部 | 仅 history-exporter | 全部但破坏可见性 | 全部 |
+| 老数据 | 兼容（新数据用新值）| 兼容 | 需迁移 | 需迁移 |
+| 风险 | 0 测试 hook 改动 | 子进程开销 | discoverability 破坏 | 引入新维度 |
+
+**推荐 A**：根因解决 + 保留用户在项目根 `ls` 即可看到 history 的可见性 + 不引入子进程开销。bash `while` 上溯零依赖，daemon / CLI 自动受益。
+
+## 改造范围（约 70 行）
+
+| 文件 | 行数 | 说明 |
+|---|---|---|
+| `src/hooks/hook-lib.sh` | +25 | 新增 `resolve_project_path` |
+| `src/hooks/pre-tool-use.sh` | -2 +1 | 替换两行 |
+| `src/hooks/post-tool-use.sh` | -2 +1 | 同上 |
+| `src/hooks/user-prompt-submit.sh` | -2 +1 | 同上 |
+| `src/hooks/stop.sh` | -2 +2 | 先 source hook-lib.sh，再用函数 |
+| `src/hooks/notification.sh` | -2 +1 | 同上 |
+| `src/cli/commands/executions.ts` | +8 | 新增 `resolveGitRoot()` 替换 3 处 `process.cwd()` |
+| `src/cli/commands/init.ts`（调用 template-manager 处，需 grep 确认）| +2 | 把传给 `initProject` 的 `projectPath` 改成 git root |
+| 新增 `tests/unit/hooks/resolve-project-path.test.sh`（或 vitest 调 bash）| ~40 | safety-net |
+| 新增 `tests/integration/hook-gitroot.integration.test.ts` | ~50 | 端到端 |
+
+## hook-lib.sh 公共函数设计
+
+```bash
+# resolve_project_path <input_cwd>
+# 从 input_cwd 上溯查找最近的 .git 目录，输出 git root。
+# 非 git 项目 / 上溯到根 / 输入为空 → 回退到 input_cwd（再回退到 $PWD）。
+# 防御：最多上溯 64 层，避免符号链接环。
+resolve_project_path() {
+  local dir="${1:-$PWD}"
+  [ -z "$dir" ] && dir="$PWD"
+
+  # 规整为绝对路径（不依赖 realpath）
+  case "$dir" in
+    /*) ;;
+    *)  dir="$PWD/$dir" ;;
+  esac
+
+  local guard=0
+  while [ "$dir" != "/" ] && [ "$dir" != "." ] && [ $guard -lt 64 ]; do
+    if [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then  # 后者兼容 git worktree
+      printf '%s' "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+    guard=$((guard + 1))
+  done
+
+  # 未找到 → 回退到原 cwd
+  printf '%s' "${1:-$PWD}"
+}
+```
+
+调用方一行替换：
+```bash
+RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
+```
+
+## CLI / daemon 端兼容
+
+**daemon 端**：不改。`history-exporter.ts:24` 信任传入的 `event.project_path`（hook 端已是 git root）。
+
+**CLI 端 `executions.ts`**：新增 helper（放 `src/core/utils/git.ts`）：
+```typescript
+export function resolveGitRoot(start = process.cwd()): string {
+  try {
+    return execSync('git rev-parse --show-toplevel', { cwd: start, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString().trim() || start;
+  } catch { return start; }
+}
+```
+三处 `path.join(process.cwd(), '.claude-forge', ...)` → `path.join(resolveGitRoot(), '.claude-forge', ...)`。
+
+**template-manager.ts**：函数本身签名不变（接收 `projectPath`），改 init 命令调用侧。
+
+## 测试策略
+
+- **safety-net (单测 bash 函数)**：构造 fixture `/tmp/forge-test/repo/.git/`，对 `resolve_project_path /tmp/forge-test/repo/a/b/c` 断言返回 git root；非 git 目录断言回退；空输入断言回退到 `$PWD`。
+- **集成**：vitest 起一个 daemon，构造 `cwd=fixture/sub/dir` 的 INPUT，跑 `pre-tool-use.sh`，从 daemon storage queryEvents 断言 `project_path === fixture` 而非子目录。
+- **回归**：现有 daemon 集成测试不需要改（hook 端透明改造）。
+- **CLI 端**：单测 `resolveGitRoot()` 在 git 仓 / 非 git 仓两种 cwd 下的返回值。
+
+## 风险与回滚
+
+- **`.git` 是文件（worktree）场景**：`[ -f "$dir/.git" ]` 已兼容。
+- **非 git 项目**：fallback 原 cwd，行为不变。
+- **monorepo 子模块各自 .git**：返回最近的 git root，符合预期。
+- **历史数据**：旧 sessions.project_path 仍是子目录路径，不做迁移；可选清单：列出 sessions 表去重 project_path，提供 `cf admin remap-project-path` 工具（非本次范围）。
+- **bash on Linux/macOS 差异**：用 POSIX 内建（`dirname` / `case`），不依赖 `realpath`。
+- **回滚**：还原 6 个文件即可，无 schema 变更。
+
+## 实施顺序（refactor-safe）
+
+1. **safety-net 阶段**：先写 `tests/unit/hooks/resolve-project-path.test.sh`（或 vitest 用 `child_process.execSync('bash -c "source hook-lib.sh && resolve_project_path ..."')`）和 `tests/integration/hook-gitroot.integration.test.ts`（先红）
+2. **lib 阶段**：在 `hook-lib.sh` 新增 `resolve_project_path` → 单测转绿
+3. **hook 改造**：5 个 hook 替换两行；`stop.sh` 同时改为 `source hook-lib.sh`（顺手补一致性）→ 集成测试转绿
+4. **CLI 阶段**：新增 `src/core/utils/git.ts::resolveGitRoot`，改 `executions.ts` 3 处 + `init` 调用侧
+5. **验证**：`npx tsc --noEmit` + `npm test` + 手工到 fixture 子目录跑 `cf executions list` 确认走 git root
+6. **release**：bump patch 版本，changelog 注明"hooks 解析 git root，不再在子目录生成 .claude-forge"
+
+## 命名遵循
+
+- bash 函数：`resolve_project_path`（snake_case，与 hook-lib 现有 `send_event_or_enqueue` / `_enqueue_event_bg` 一致）
+- TS 工具函数：`resolveGitRoot`（camelCase，`get` 前缀不适用因为这是计算非查询）
+- 新文件：`src/core/utils/git.ts`（kebab 化已为单词，遵循现有 `time.ts` / `session.ts`）
+- 测试文件：`tests/unit/hooks/resolve-project-path.test.sh` 或 `.test.ts`、`tests/integration/hook-gitroot.integration.test.ts`

package/docs/design/task-active-gc-spec-20260518-1745.md

@@ -0,0 +1,146 @@
+# task active GC 修复 Spec
+
+## 目标
+
+通过周期 GC + completeCurrentTask recover fallback，消除因 ESC 中断、Stop hook 未触发、daemon 重启等场景导致的 task 永久滞留 `active` 状态。
+
+## Bug 复现路径
+
+| 场景 | 触发条件 | 为何漏掉 |
+|------|---------|---------|
+| A | 用户 ESC 中断 Claude Code，Stop hook 不触发 | completeCurrentTask 永远不被调用 |
+| B | daemon 重启后用户 ESC，Stop hook 触发但 `currentTasks` Map 为空 | completeCurrentTask 第 78 行：`const current = this.currentTasks.get(sessionId)` — Map 空直接 return |
+| C | 用户切到别的 session 后永不再 prompt 旧 session | shouldStartNewTask 从不被触发，task 无人收尾 |
+
+## 方案对比
+
+| 方案 | 修复场景 | 改动文件数 | 风险 |
+|------|---------|-----------|------|
+| A：周期 GC | A / C（idle 超阈值后兜底） | 3 | idle 阈值设太短可能误杀长任务 |
+| B：completeCurrentTask recover fallback | B | 1 | 仅修场景 B，A/C 仍漏 |
+| C：A + B 组合 | A / B / C 全覆盖 | 3 | 最全面，改动仍可控 |
+| D：新增 `auto_closed` 状态 | A / B / C + UI 语义区分 | 5+ | 改动大，可作后续优化 |
+
+**推荐：方案 C**。
+
+## 详细设计
+
+### 1. storage 新方法：`completeStaleActiveTasks`
+
+**位置**：`src/core/storage/tasks.ts`（TaskOperations 类内）
+
+```ts
+/**
+ * 将 idle 超过阈值的 active task 批量转为 completed。
+ * 条件：status='active' AND end_time IS NOT NULL
+ *       AND (now - end_time) > idleMinutes 分钟。
+ * 返回：受影响行数。
+ */
+completeStaleActiveTasks(idleMinutes: number): number {
+  const result = this.db.prepare(`
+    UPDATE tasks
+    SET status = 'completed'
+    WHERE status = 'active'
+      AND end_time IS NOT NULL
+      AND (julianday('now') - julianday(end_time)) * 24 * 60 > ?
+  `).run(idleMinutes);
+  return result.changes;
+}
+```
+
+同步在 `SQLiteStorage` facade（`sqlite.ts`）暴露同名代理方法。
+
+注意：`end_time` 由 `linkEventToTask` 持续更新，作为 idle 判定基准合理。没有 `end_time` 的 task（从未 link 过事件）不纳入 GC，避免误杀刚创建的 task。
+
+### 2. TaskSegmenter.completeCurrentTask 加 recover fallback
+
+**位置**：`src/daemon/services/task-segmenter.ts:77`
+
+```ts
+completeCurrentTask(sessionId: string, timestamp: string): void {
+  const current = this.currentTasks.get(sessionId) ?? this.recoverActiveTask(sessionId);
+  if (!current) return;
+  ...
+}
+```
+
+一行改动，与 `processPrompt` / `linkEvent` 模式一致。
+
+### 3. maintenanceInterval 加 GC 调度
+
+**位置**：`src/daemon/index.ts:105-116`
+
+现有 `maintenanceInterval` 是 **24 小时**，仅清理旧 events。需新增独立的**短周期 GC interval**：
+
+```ts
+// ── 5.6. Stale task GC (every 5 minutes) ──────────────────────────
+const STALE_TASK_GC_INTERVAL = 5 * 60 * 1000; // 5 分钟
+const STALE_TASK_IDLE_MINUTES = 10;            // idle 超 10 分钟视为滞留
+
+const staleTaskGcInterval = setInterval(() => {
+  try {
+    const closed = storage.completeStaleActiveTasks(STALE_TASK_IDLE_MINUTES);
+    if (closed > 0) {
+      logger.info(`[Maintenance] Auto-completed ${closed} stale active task(s)`);
+    }
+  } catch (err) {
+    logger.error(`[Maintenance] Stale task GC failed: ${err}`);
+  }
+}, STALE_TASK_GC_INTERVAL);
+```
+
+关闭时需调用 `clearInterval(staleTaskGcInterval)`（在现有 graceful shutdown 段追加）。
+
+## 改造范围
+
+| 文件 | 改动内容 | 估算行数 |
+|------|---------|---------|
+| `src/core/storage/tasks.ts` | 新增 `completeStaleActiveTasks` 方法 | +12 |
+| `src/core/storage/sqlite.ts` | facade 代理方法 | +3 |
+| `src/daemon/services/task-segmenter.ts` | completeCurrentTask recover fallback（1 行） | +1 |
+| `src/daemon/index.ts` | 新增 GC interval + clearInterval | +12 |
+
+共 4 文件，约 28 行净增。
+
+## 配置
+
+| 参数 | 值 | 说明 |
+|------|----|------|
+| `STALE_TASK_IDLE_MINUTES` | 10 | idle 超 10 分钟视为放弃，不可配置（硬编码常量） |
+| `STALE_TASK_GC_INTERVAL` | 5 分钟 | GC 轮询间隔，独立于 24h 维护周期 |
+
+如未来需要可迁移到 `config.yaml` 的 `tasks.stale_gc_minutes` 字段。
+
+## 测试策略
+
+| 测试类型 | 测试用例 | 文件位置 |
+|---------|---------|---------|
+| 单测：`completeStaleActiveTasks` | 空表返回 0 | 新增 `tests/unit/storage/tasks-stale-gc.test.ts` |
+| | 1 idle 超阈值 + 1 未超：只关超的 | 同上 |
+| | `status='completed'` 的 task 不被改动 | 同上 |
+| | `end_time IS NULL` 的 task 不被纳入 | 同上 |
+| 单测：recover fallback | Map 为空时仍能 complete DB 中 active task | 扩展现有 task-segmenter 测试 |
+
+## 风险与回滚
+
+| 风险 | 概率 | 缓解措施 |
+|------|------|---------|
+| 误杀正在进行的长任务 | 低（idle 阈值 10 分钟，linkEvent 持续刷新 end_time） | 阈值可调大；日志可审计 |
+| 旧库一次性批量 GC | 必然发生，且是预期行为 | 无需回滚，这正是修 bug 的目的 |
+| GC interval 异常退出 | 极低（try-catch 包裹） | 日志记录，不影响主流程 |
+
+**回滚**：删除 daemon/index.ts 中的 `staleTaskGcInterval` 代码块即可完全禁用 GC，其他改动无副作用。
+
+## 实施顺序
+
+1. `tasks.ts` — 新增 `completeStaleActiveTasks` + 单测
+2. `sqlite.ts` — facade 代理方法
+3. `task-segmenter.ts` — recover fallback 单行 + 单测
+4. `daemon/index.ts` — GC interval 注册 + clearInterval
+5. 全量测试 `npm test`
+
+## 命名遵循
+
+- `completeStaleActiveTasks`：`complete` 前缀（语义清晰，优于 `write`）
+- `STALE_TASK_GC_INTERVAL` / `STALE_TASK_IDLE_MINUTES`：全大写常量
+- `staleTaskGcInterval`：camelCase 变量，与 `maintenanceInterval` 风格一致

package/docs/implementation/h1-storage-aggregation-changelog-20260518-1121.md

@@ -0,0 +1,82 @@
+# H1 实施 Changelog
+
+**Date**: 2026-05-18 11:21
+**Spec**: `docs/design/h1-storage-aggregation-spec-20260518-1121.md`
+**Status**: 完成
+
+## 完成清单
+
+- [x] Storage 新方法（7 个）：
+  - `aggregateRoutingStats({ since_ts, project_path? })` → `RoutingOperations`
+  - `aggregateRoutingTrendByDay({ since_ts })` → `RoutingOperations`
+  - `aggregateSkillInvocationsBySkill({ since, limit? })` → `SkillOperations`
+  - `getTask(taskId)` → `TaskOperations`
+  - `queryEventsByTaskId(taskId, opts?)` → `TaskOperations`
+  - `queryInjectionsByTaskId(taskId)` → `TaskOperations`
+  - `querySkillInvocationsByTaskWindow(taskId, now_ms?)` → `TaskOperations`
+- [x] sqlite.ts facade 转发已加（7 个方法）
+- [x] 索引新增：`idx_routing_events_type_ts` (schema.sql + base.ts runMigrations 同步)
+- [x] Storage 单元测试（3 文件）：
+  - `tests/unit/storage/routing-aggregates.test.ts`
+  - `tests/unit/storage/skills-aggregates.test.ts`
+  - `tests/unit/storage/tasks-getById-aggregates.test.ts`
+- [x] Routes 改造（3 文件）：
+  - `src/web/routes/rules.ts` — hit-rate 改用 `aggregateRoutingStats` + `aggregateSkillInvocationsBySkill`
+  - `src/web/routes/skill-stats.ts` — 5 个 endpoint 全部下沉到 SQL 聚合
+  - `src/web/routes/tasks.ts` — `/:taskId` PK 直查 + JOIN
+- [x] 路由测试新增：`tests/unit/web/routes-rules.test.ts`（之前缺口）
+
+## 关键代码定位
+
+### Storage 新方法
+- `src/core/storage/routing.ts` — `aggregateRoutingStats`、`aggregateRoutingTrendByDay`（4 条独立 prepared statement 走索引；trend 用 `strftime('%Y-%m-%d', ts/1000, 'unixepoch')`）
+- `src/core/storage/skills.ts` — `aggregateSkillInvocationsBySkill`（按 `total DESC`）
+- `src/core/storage/tasks.ts` — `getTask` / `queryEventsByTaskId` / `queryInjectionsByTaskId` / `querySkillInvocationsByTaskWindow`（后者用 `task_events` JOIN + `tasks.start_time/end_time` 转 ms 做窗口过滤）
+- `src/core/storage/sqlite.ts` — facade 转发 7 个方法
+- `src/core/storage/schema.sql` 末尾 + `src/core/storage/base.ts` runMigrations — `idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC)`
+
+### Route 改造点
+- `src/web/routes/rules.ts` — `queryRoutingEvents{limit:100000}` + `querySkillInvocations{limit:100000}` JS reduce → `aggregateRoutingStats` + `aggregateSkillInvocationsBySkill`
+- `src/web/routes/skill-stats.ts:16` — `/distribution`：`agg.by_type` + 三桶兜底
+- `src/web/routes/skill-stats.ts:33` — `/frequency`：`agg.by_skill_routed.map(...)`
+- `src/web/routes/skill-stats.ts:43` — `/trend`：`aggregateRoutingTrendByDay` + JS skillRate 计算
+- `src/web/routes/skill-stats.ts:59` — `/invocations`：`aggregateSkillInvocationsBySkill`，`total` 改为 sum 行 total
+- `src/web/routes/skill-stats.ts:76` — `/api/routing/stats`：`agg.obeyed/total/by_agent`
+- `src/web/routes/tasks.ts:59` — `/:taskId`：`getTask` + `queryEventsByTaskId` + `queryInjectionsByTaskId` + `querySkillInvocationsByTaskWindow` 取代旧四段全表扫
+
+## 测试结果
+
+| 维度 | 数值 |
+|------|------|
+| storage + web unit | 171 通过 / 1 失败（pre-existing） |
+| 全量 `npm test` | **417 通过 / 1 失败 / 418 总** |
+| `npx tsc --noEmit` | **0 errors** |
+
+### Pre-existing failure（与 H1 无关，main 分支既有）
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > Task Operations > linkEventToTask associates events with tasks`
+  - 报错：`Invalid event data: ... event_id Invalid uuid`
+  - 原因：测试中传入的 `event_id` 不是 UUID 格式，与 `events.ts:73` 的 zod 校验不兼容
+  - 在 main 分支同样 fail，**未在本次任务范围**，未修
+
+## 超出 spec 的改动
+
+无。所有改动均严格按 spec 第 3 节执行。响应字段结构未变更（前端 React 组件契约保持）：
+- `/distribution` → `{ windowHours, distribution: [{type, count}] }` ✓
+- `/frequency` → `{ windowHours, frequency: [{name, count}] }` ✓
+- `/trend` → `{ windowHours, trend: [{day, skillRate}] }` ✓
+- `/invocations` → `{ days, total, invocations: [{skill_id, total, success, failed}] }` ✓
+- `/api/routing/stats` → `{ days, total, agentCalls, noAgent, agentRate, byAgent }` ✓
+- `/api/tasks/:taskId` → `{ task, userPrompts, injections, timeline, skillInvocations, artifacts }` ✓
+
+注：`/invocations` 的 `total` 字段语义不变（旧实现是 `invocations.length` = 原始记录数；新实现是 `sum(rows.total)` = 同样的原始记录数，因 GROUP BY skill_id 后各 group total 之和等于总行数）。
+
+## 已知问题
+
+- **Pre-existing**：`sqlite-refactor-harness.test.ts > linkEventToTask` — 与 H1 无关，main 分支同样失败。
+- 无其它已知问题。
+
+## 回滚提示
+
+纯增量改动。如需回滚：
+- revert `src/web/routes/{rules,skill-stats,tasks}.ts` 即可恢复旧行为
+- storage 新方法和索引保留无害（无人调用即无副作用）

package/docs/implementation/h2-final-changelog-20260518-1530.md

@@ -0,0 +1,61 @@
+# H2 完整实施 Changelog
+
+**Date**: 2026-05-18
+**Spec**: `docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md`
+**Status**: 全 4 Phase 完成
+**Workflow**: refactor-safe（safety-net → 新方法 → 替换 → 收尾）
+
+## 四阶段 commit 索引
+
+| Phase | Commit | 内容 |
+|---|---|---|
+| 1 | `0b494ed` | safety-net 17 test cases（web-stats / web-trace / stop-handler / web-analytics 增强） |
+| 2 | （上一 commit） | 20 个 Operations 新方法 + 44 个单测 + facade 转发 |
+| 3 | `bf3eb39` | 7 个调用方文件替换 db.prepare() → facade |
+| 4 | （本 commit） | getDatabase jsdoc 警告 + 总 changelog |
+
+## 累计影响
+
+- **改动 13 个 src 文件，新增 12 个测试文件**
+- **消除 27 处越权 SQL 直写**（spec 调研时 25 处 + 主线程封闭性扫描补 cli/commands/trace.ts 3 处）
+- **新增 20 个 Operations 方法**：EventOperations × 11 + SessionOperations × 4 + TaskOperations × 1 + SkillOperations × 4
+- **新增 61 个测试用例**：safety-net 17 + Operations 单测 44
+
+## 命名固化（H1 → H2 一致）
+
+- `aggregate*` 聚合（GROUP BY 类）
+- `count*` 计数
+- `query*` 列表查询
+- `get*` 单条查询
+
+## 关键决策
+
+1. **getDatabase 保留 public**（不改 protected）：架构非继承关系，protected 收益小风险大；改用 jsdoc `@internal` 标注 + CLAUDE.md 工作流提醒
+2. **SQL 行为零变更**：所有 SQL 直接搬入 Operations，不做"优化"，保证 safety-net 测试零回归
+3. **`LIKE '%error%'` 失败检测保留原 3 个 OR 条件**：与生产匹配
+4. **Phase 2 偏差**：`aggregateToolUsage` 缺 `until` 参数 → Phase 3 改用 `queryEventsByTimeRange + 内存聚合` 兜底，保留 `[since, until)` 语义
+
+## 测试结果（最终）
+
+- safety-net 集成测试：17/17 ✓
+- Operations 单测：44/44 ✓
+- 现有回归：541/542 通过
+- **唯一失败**：pre-existing `linkEventToTask` (Zod UUID 校验，与 H2 无关)
+- `npx tsc --noEmit`: 0 errors
+
+## 残留 `db.prepare` 检查
+
+```bash
+$ grep -rn "db\.prepare" src/web/ src/cli/commands/trace.ts src/daemon/handlers/ --include="*.ts" | grep -v ".test."
+src/web/routes/stats.ts:7: * H2 Phase 3: 替换原 db.prepare 直写 SQL 为 SQLiteStorage facade 聚合方法。
+src/web/routes/trace.ts:95:    // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+src/daemon/handlers/stop.ts:151:      // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+```
+
+**3 处均为注释**，无 SQL 直写。
+
+## 后续 follow-up
+
+- **可选**：补完 `aggregateToolUsage` 的 `until` 参数支持，weekly-report 改回单条 SQL
+- **可选**：ESLint 规则禁止 `web/routes/` `web/analytics/` `daemon/handlers/` import storage 后调用 `getDatabase()`
+- **不建议**：把 `getDatabase` 改 protected（架构非继承）

package/docs/implementation/h2-phase1-safety-net-changelog-20260518-1450.md

@@ -0,0 +1,70 @@
+# H2 Phase 1 safety-net Changelog
+
+**Date**: 2026-05-18 14:50
+**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
+**Status**: Phase 1 完成（Phase 2-4 待后续）
+
+## 完成清单
+
+- [x] web-stats 集成测试 (`tests/integration/web-stats.integration.test.ts`, 4 cases)
+- [x] web-trace 集成测试 (`tests/integration/web-trace.integration.test.ts`, 6 cases — 全分支覆盖)
+- [x] stop-handler-behavior-summary 单测 (`tests/unit/daemon/stop-handler-behavior-summary.test.ts`, 5 cases)
+- [x] web-analytics 集成测试增强 (+2 value-level cases)
+
+## 关键代码定位
+
+| 测试文件 | 行号 | 内容 |
+|---|---|---|
+| `tests/integration/web-stats.integration.test.ts:38` | empty database 200 shape |
+| `tests/integration/web-stats.integration.test.ts:60` | totalEvents/totalSessions/toolUsage 聚合 |
+| `tests/integration/web-stats.integration.test.ts:83` | dailyActivity 字段形状 |
+| `tests/integration/web-stats.integration.test.ts:103` | skillInvocations 计数 |
+| `tests/integration/web-trace.integration.test.ts:84-118` | 4 个 4xx 错误分支 |
+| `tests/integration/web-trace.integration.test.ts:120-130` | 200 + 空 sessions[]（无 git note）|
+| `tests/integration/web-trace.integration.test.ts:132-167` | 200 + 完整 session 详情（含 event_breakdown）|
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:69` | 无事件时不附加 summary |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:82` | tool-only summary |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:110` | Agent 委托计数 + agent 名 |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:141` | skill 调用计数 |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:169` | session 隔离（不串扰）|
+| `tests/integration/web-analytics.integration.test.ts:92` | weekly report value 断言 |
+| `tests/integration/web-analytics.integration.test.ts:107` | insights summary.total = patterns.length |
+
+## 测试结果
+
+- **新增/增强 safety-net 测试**: 17 passed (4 stats + 6 trace + 5 stop + 2 analytics 增强)
+- **跨 Phase 1 范围全量**:
+  - `tests/integration/` + `tests/unit/daemon/`: 33 / 33 passed
+- **tsc**: 0 errors
+- **npm test 全量**: 497 / 498 passed (1 failed = pre-existing `linkEventToTask`)
+
+## 实施决策
+
+1. **trace 测试覆盖方案**：采用方案 A（tmp git repo）。在 `os.tmpdir()` 用 `execFileSync('git', ...)` 创建真实仓库 + 两次 commit + `git notes add`，覆盖：
+   - 缺 `?project` query → 400
+   - 相对路径 → 400
+   - 非 git 目录 → 400
+   - commit 不存在 → 404
+   - HEAD 有 commit 但无 note → 200 + 空 sessions[]
+   - 有 forge-session note + storage 有对应 events → 200 + 完整 session 详情（event_breakdown 等）
+   - **覆盖度高于 spec 最低要求**（spec 只要求 commit 不存在 4xx + 无 note 空 sessions 两条），实际跑得快且稳定。
+2. **stop-handler 测试路径调整**：spec 写 `src/tests/stop-handler-behavior-summary.test.ts`，但 `vitest.config.ts` 只包含 `tests/unit/**` 与 `tests/integration/**`。如放到 `src/tests/` 会被 collect 排除导致永远不跑。改放到 `tests/unit/daemon/stop-handler-behavior-summary.test.ts` 以确保实际生效，已在测试文件顶部 NOTE 注释中说明决策。
+3. **`generateBehaviorSummary` 私有方法访问**：经由 `handle()` 入口 + mock `ResumeManager.save` 捕获最终 resume content 进行断言。比反射访问私有方法更接近生产实际路径，且更稳健。
+4. **web-analytics 增强保守原则**：只加 2 个新 case（weekly value + insights consistency），不重写既有 shape 断言。所有原 case 仍保留并通过。
+5. **fixture 时间戳策略**：weekly-report 按 ISO week 范围过滤事件，所以 fixture 用 `new Date().toISOString()`（当下时间）确保进入 `weekOffset: 0` 窗口；stats endpoint 用 `date('now', '-7 days')`，同样满足。
+
+## 待 Phase 2 处理
+
+下一步 Phase 2（新增 ~20 个 Operations 方法）的提示：
+
+- Phase 2 应在 `src/core/storage/{events,sessions,tasks,skills}.ts` 加方法，**不删旧 SQL**，并行存在。
+- Phase 2 同时增加 4 个新单测文件：`tests/unit/storage/{event,session,skill}-operations-aggregates.test.ts`（spec 表 116 行所列）。
+- Phase 3 才会替换调用方（每文件 1 commit），届时本 Phase 1 的 safety-net 会兜底回归。
+- Phase 4 给 `getDatabase()` 加 jsdoc `@internal` 警告。
+- 改造涉及 `daemon/handlers/stop.ts` 时，本次新加的 `stop-handler-behavior-summary.test.ts` 5 个 case 是关键回归依据。
+- trace 测试包含一次真实 `git init`，单测耗时 ~600ms，未来 Phase 2/3 增加新测试时不必再做 git 操作。
+
+## 已知问题
+
+- **pre-existing 失败**：`SQLiteStorage - Characterization Tests (Pre-Refactor) > Task Operations > linkEventToTask associates events with tasks` —— Zod uuid 校验失败，与本 Phase 1 改动无关，按纪律不修。
+- **未覆盖**：`cli/commands/trace.ts` 3 段 SQL 暂无对应集成测试（spec 第 71 行已标注"可补"）。Phase 2/3 替换 CLI trace 时可考虑加 CLI smoke test，或先依赖 web-trace 同模式断言间接保护。

package/docs/implementation/h2-phase2-operations-changelog-20260518-1450.md

@@ -0,0 +1,120 @@
+# H2 Phase 2 Operations 新方法 Changelog
+
+**Date**: 2026-05-18 14:50 (Phase 2)
+**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
+**Status**: Phase 2 完成（Phase 3 待替换调用方）
+
+## 完成清单
+
+- [x] EventOperations 11 方法（events.ts）
+- [x] SessionOperations 4 方法（sessions.ts）
+- [x] TaskOperations 1 方法（tasks.ts）
+- [x] SkillOperations 4 方法（skills.ts）
+- [x] sqlite.ts facade 转发（20 个方法）
+- [x] 4 文件单测（44 个 case 全过）
+- [x] tsc 通过 0 errors
+- [x] 旧 SQL 并行存在（Phase 3 才替换）
+
+## 新增方法清单
+
+### EventOperations（src/core/storage/events.ts:179-358）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countAllEvents()` | stats.ts:13 |
+| `aggregateToolUsage({ since?, limit?, hook_type? })` | stats.ts:17-21 + weekly-report.ts:214-222 |
+| `aggregateDailyEventCounts({ since, until? })` | stats.ts:28-33 |
+| `aggregateHookTypeBySession(session_id)` | trace.ts:106-109 + cli/trace.ts:115 |
+| `aggregateAgentTypeBySession(session_id)` | trace.ts:111-116 + cli/trace.ts:124 + stop.ts:163-168 |
+| `aggregateToolUsageBySession(session_id)` | stop.ts:154-158 |
+| `countActiveDays({ since, until? })` | drift-detector.ts:154-157 |
+| `aggregateOverviewByRange({ since, until })` | weekly-report.ts:100-109 |
+| `queryDistinctProjects({ since, until })` | weekly-report.ts:111-116 |
+| `aggregateToolFailureRate({ since, until })` | weekly-report.ts:228-244（保留 3 OR LIKE 分支） |
+| `queryFileEditInputs({ since, until, tool_names })` | weekly-report.ts:261-268（内部 IN 展开） |
+| `queryEventsByTimeRange({ since, until? })` | anti-pattern-detector.ts:83-86 |
+
+### SessionOperations（src/core/storage/sessions.ts:107-178）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countAllSessions()` | stats.ts:14 |
+| `aggregateDailySessionCounts({ since, until? })` | stats.ts:35-40 |
+| `querySessionsByTimeRange({ since, until? })` | anti-pattern-detector.ts:104-114 |
+| `countSessionsByRange({ since, until? })` | drift-detector.ts:185-187 |
+
+### TaskOperations（src/core/storage/tasks.ts:120-131）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countTasksByRange({ since, until? })` | drift-detector.ts:190-192 + weekly-report.ts:118-122 |
+
+### SkillOperations（src/core/storage/skills.ts:203-232）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countAllSkillInvocations()` | stats.ts:50 |
+| `countSkillInvocationsBySession(session_id)` | stop.ts:176-178 |
+| `countDistinctSkillsSince(since_ms)` | drift-detector.ts:125-128 |
+| `queryDistinctSkillIdsBySession(session_id)` | trace.ts:118-120 + cli/trace.ts:135 |
+
+### sqlite.ts facade（src/core/storage/sqlite.ts:94-160）
+
+20 个方法签名严格按 spec，全部 `delegate to this.events / this.sessions / this.tasks / this.skills`。
+
+## 关键代码定位
+
+- `src/core/storage/events.ts:179-358` — EventOperations 11 新方法
+- `src/core/storage/sessions.ts:107-178` — SessionOperations 4 新方法
+- `src/core/storage/tasks.ts:120-131` — TaskOperations countTasksByRange
+- `src/core/storage/skills.ts:203-232` — SkillOperations 4 新方法
+- `src/core/storage/sqlite.ts:94-160` — facade 转发段
+
+## 测试结果
+
+- 新增单测: **44 passed / 44**
+  - event-operations-aggregates.test.ts: 23 tests
+  - session-operations-aggregates.test.ts: 9 tests
+  - task-operations-counts.test.ts: 3 tests
+  - skill-operations-counts.test.ts: 9 tests
+- 旧 storage 测试回归: 通过（除 pre-existing failure）
+- tsc: **0 errors**
+- npm test: **541 passed / 542**（仅 pre-existing `linkEventToTask` 失败）
+
+## 实施决策
+
+1. **LIKE '%error%' 失败检测保持原 SQL 三个 OR 分支**
+   - `tool_output LIKE '%"error"%' OR LIKE '%"is_error":true%' OR LIKE '%"isError":true%'`
+   - 测试覆盖三种 tool_output JSON 形态，确认全部命中
+
+2. **时间区间统一 `[since, until)` 半开半闭语义**
+   - 调用方负责 ISO 字符串构造（`new Date(since).toISOString()`）
+   - until 一律 `<`（与 weekly-report.ts 原 `start_time < ?` 一致）
+   - 与 stats.ts 原 `date('now', '-7 days')` 语义不同：新方法不再隐含 now()，调用方计算
+
+3. **`queryFileEditInputs` 内部展开 placeholders**
+   - tool_names 通过参数注入，避免外部拼 SQL
+   - 空 list 直接返回空数组（避免 `IN ()` SQL 错误）
+
+4. **`aggregateToolUsage` 合并 stats / weekly-report 两个用例**
+   - 通过 `hook_type` 可选过滤 + `since` 可选过滤兼顾两种调用
+   - `tool_name IS NOT NULL AND tool_name != ''` 始终生效（stats.ts 原行为）
+
+5. **`aggregateAgentTypeBySession` 与 `aggregateToolUsageBySession` 分离**
+   - 前者 `tool_name IN ('Agent','Task')` + json_extract subagent_type（stop.ts:163 / trace.ts:111）
+   - 后者纯 `tool_name IS NOT NULL`（stop.ts:154）
+   - 两段语义不同，分别封装
+
+## 待 Phase 3 处理
+
+- 替换 src/web/routes/stats.ts（5 段 SQL）
+- 替换 src/web/routes/trace.ts（3 段 SQL）
+- 替换 src/cli/commands/trace.ts（3 段 SQL）
+- 替换 src/daemon/handlers/stop.ts:154-178（3 段 SQL）
+- 替换 src/web/analytics/drift-detector.ts（4 段 SQL）
+- 替换 src/web/analytics/weekly-report.ts（6 段 SQL）
+- 替换 src/web/analytics/anti-pattern-detector.ts（2 段 SQL）
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` pre-existing 失败（与 Phase 2 改动无关，event_id 未传 UUID 导致 zod schema 拒收）