@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/storage/schema.sql

@@ -1,6 +1,6 @@
 -- Claude Forge SQLite Schema (core tables)
 -- Active tables: events, sessions, injections, tasks, task_events,
--- routing_events, token_usage, skill_invocations
+-- routing_events, skill_invocations
 --
 -- ── Table Relationships ──────────────────────────────────────────────────────
 --
@@ -17,10 +17,7 @@
 --   └─ skill_invocations.session_id       → events.session_id (logical, no FK)
 --   └─ skill_invocations.route_request_id → routing_events.route_request_id (logical, no FK)
 --
--- token_usage (LLM token accounting)
---   └─ token_usage.session_id     → events.session_id (logical, no FK)
---
--- Why no FK on routing_events / skill_invocations / token_usage:
+-- Why no FK on routing_events / skill_invocations:
 --   1. routing_events.route_request_id is nullable and not UNIQUE — cannot be FK target
 --   2. Write order is not guaranteed: skill_invocations may be written before routing_events
 --   3. session_id references are maintained by application logic; sessions is an aggregate
@@ -42,6 +39,14 @@ CREATE TABLE IF NOT EXISTS events (
     user_prompt TEXT,
     ai_response TEXT,
     distilled INTEGER DEFAULT 0,
+    -- F3 (audit-20260522): tool_output 写入端 50KB 截断标记。1=truncated。
+    tool_output_truncated INTEGER DEFAULT 0,
+    -- decision c425f26f (spec 1544): spawn prompt 头 <!-- decision-id: XXXX --> 抽出的
+    -- 明文串联键（nullable，非 Task/Agent spawn 行为 NULL）。绝不走 gzip codec——
+    -- 解压一次写明文，供跨 task 按 decision_id 聚合 SQL 直接查询（gzip one-way-door 雷）。
+    decision_id TEXT,
+    -- decision c425f26f: Task/Agent spawn 的 subagent_type 明文抽出（nullable，非 spawn 为 NULL）。
+    subagent_type TEXT,
     created_at TEXT DEFAULT (datetime('now'))
 );
 
@@ -50,6 +55,9 @@ CREATE INDEX IF NOT EXISTS idx_events_project ON events(project_path);
 CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_events_distilled ON events(distilled);
 CREATE INDEX IF NOT EXISTS idx_events_hook_type ON events(hook_type);
+-- decision c425f26f: 跨 task 按 decision_id 聚合 spawn 的覆盖索引。
+CREATE INDEX IF NOT EXISTS idx_events_decision_id ON events(decision_id);
+CREATE INDEX IF NOT EXISTS idx_events_decision_spawn ON events(decision_id, hook_type, tool_name, timestamp);
 
 CREATE TABLE IF NOT EXISTS sessions (
     session_id TEXT PRIMARY KEY,
@@ -60,6 +68,28 @@ CREATE TABLE IF NOT EXISTS sessions (
     end_time TEXT,
     last_event_time TEXT,
     event_count INTEGER DEFAULT 0,
+    -- Outcome instrumentation (v9.x): rule-based classification at Stop time.
+    -- NULL means "not yet classified" (legacy rows or pre-classification reads).
+    --
+    -- spec 1100 Option C (2026-06-02): CHECK relaxed from a fixed value enum
+    -- ('success','partial','failed','abandoned') to a non-empty-string guard.
+    -- Adding the new `answered` outcome (and any future value) no longer
+    -- requires a table rebuild / CHECK-migration — the classifier is the single
+    -- source of truth for the value set; the column just stores it. Legacy DBs
+    -- with the old enum CHECK are widened in-place by base.ts
+    -- rebuildOutcomeCheckIfNeeded (one-shot, idempotent, data-preserving).
+    outcome TEXT CHECK(outcome IS NULL OR length(outcome) > 0),
+    outcome_reason TEXT,
+    commit_count INTEGER DEFAULT 0,
+    reverted_commits INTEGER DEFAULT 0,
+    user_violation_count INTEGER DEFAULT 0,
+    classified_at TEXT,
+    -- Phase 2 metrics rollup (master roadmap §2): per-session counters back-
+    -- filled by Stop handler from fact tables (tool_intercepts / injections /
+    -- skill_invocations). Default 0 so analytics queries can skip COALESCE.
+    intercept_count INTEGER DEFAULT 0,
+    kb_inject_count INTEGER DEFAULT 0,
+    skill_match_count INTEGER DEFAULT 0,
     created_at TEXT DEFAULT (datetime('now')),
     updated_at TEXT DEFAULT (datetime('now'))
 );
@@ -67,6 +97,8 @@ CREATE TABLE IF NOT EXISTS sessions (
 CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_path);
 CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
 CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_outcome ON sessions(outcome);
+CREATE INDEX IF NOT EXISTS idx_sessions_project_outcome ON sessions(project_path, outcome);
 
 -- ── Injections ─────────────────────────────────────────────────────
 
@@ -78,6 +110,12 @@ CREATE TABLE IF NOT EXISTS injections (
     source_handler TEXT NOT NULL,
     injection_type TEXT NOT NULL CHECK(injection_type IN ('systemMessage', 'additionalContext', 'reason')),
     content TEXT NOT NULL,
+    metadata_json TEXT,
+    -- KB 采纳 telemetry（decision 148f7a0a, 2026-06-10）：同会话后续出现
+    -- mcp__claude-forge__knowledge* 调用时，PostToolUse handler 把该会话
+    -- source_handler LIKE '%:kb' 且未标记的注入行盖上 epoch-ms 时间戳。
+    -- NULL = 注入后从未被采纳。
+    adopted_at INTEGER,
     created_at TEXT DEFAULT (datetime('now')),
     FOREIGN KEY (event_id) REFERENCES events(event_id) ON DELETE CASCADE
 );
@@ -97,6 +135,54 @@ CREATE TABLE IF NOT EXISTS tasks (
     end_time TEXT,
     status TEXT DEFAULT 'active' CHECK(status IN ('active', 'completed', 'abandoned')),
     event_count INTEGER DEFAULT 0,
+    -- Outcome instrumentation (v9.x): mirrors sessions.outcome at task granularity.
+    -- spec 1100 Option C (2026-06-02): CHECK relaxed to a non-empty guard so the
+    -- new `answered` value (and future ones) need no table rebuild. See the
+    -- matching note on sessions.outcome above.
+    outcome TEXT CHECK(outcome IS NULL OR length(outcome) > 0),
+    outcome_reason TEXT,
+    commit_count INTEGER DEFAULT 0,
+    reverted_commits INTEGER DEFAULT 0,
+    user_violation_count INTEGER DEFAULT 0,
+    classified_at TEXT,
+    -- decision 265f59d5 (2026-06-08): LLM task-boundary classifier idempotency
+    -- marker. ISO timestamp stamped once the async TaskBoundaryClassifier has
+    -- processed the prompt that minted this task; NULL = not yet / never
+    -- classified. Guards against a replayed event re-spawning claude or
+    -- re-attributing the same prompt twice.
+    llm_classified_at TEXT,
+    -- Task-tracking overhaul (2026-05-27): write-time noise classification.
+    -- Computed by TaskSegmenter.createTask via computeIsNoise(); replaces the
+    -- LOWER(title) IN (...) + length() blocklist in queryAgentBoardTasks /
+    -- countAgentBoardTasks (Bug 2: CJK short titles like '推送吧' were dropped).
+    -- 1 = noise (envelope / sub-3-char / single-word slash command).
+    -- 0 = real human task (default; legacy rows back-filled by base.ts post-migration).
+    --
+    -- DEPRECATED since 2026-06-01 (spec b1480935 Option A) in favour of the
+    -- richer `task_kind` column below. Writers stop populating is_noise (it
+    -- stays 0 for new rows); read paths fall back to is_noise=1 only on
+    -- legacy DBs where backfill hasn't yet populated task_kind. Column kept
+    -- to ease rollback; will be dropped in a future overhaul.
+    is_noise INTEGER NOT NULL DEFAULT 0,
+    -- spec b1480935 (2026-06-01): per-task classification covering the
+    -- previous is_noise=1 envelope buckets PLUS real human tasks. Values:
+    --   'user'           — real human prompt (default; the only kind that
+    --                       participates in continuation / KPI roll-ups)
+    --   'agent-callback' — `<task-notification>` envelope post-spawn
+    --   'image'          — `[Image #N]` attachment-only envelope
+    --   'system'         — framework reminders (system-reminder /
+    --                       local-command-stdout / command-message /
+    --                       command-name)
+    -- Boot-time backfill maps the legacy is_noise=1 rows to the appropriate
+    -- kind via title-prefix sniff (see base.ts backfillTasksTaskKindIfNeeded).
+    task_kind TEXT NOT NULL DEFAULT 'user'
+        CHECK(task_kind IN ('user', 'agent-callback', 'image', 'system')),
+    -- decision f47c2c90 (二期B): 无 decision_id 工作流的回退串联键。续接/批准类后续轮
+    -- 由 TaskSegmenter 指回发起它的 user task（自引用，nullable，根 task 为 NULL）。
+    -- 与一期A互补：timeline 有 decision_id 走 A，无则沿此父链聚合四段。
+    -- NOTE: SQLite ALTER TABLE ADD COLUMN 不支持 inline REFERENCES，故旧库该列无 FK
+    -- enforcement；应用层不依赖 SQLite FK enforce（仅逻辑外键），新库声明仅为文档。
+    parent_task_id TEXT REFERENCES tasks(id),
     created_at TEXT DEFAULT (datetime('now'))
 );
 
@@ -110,6 +196,12 @@ CREATE TABLE IF NOT EXISTS task_events (
 
 CREATE INDEX IF NOT EXISTS idx_tasks_session ON tasks(session_id);
 CREATE INDEX IF NOT EXISTS idx_tasks_start_time ON tasks(start_time DESC);
+CREATE INDEX IF NOT EXISTS idx_tasks_session_outcome ON tasks(session_id, outcome);
+-- spec b1480935: drives WHERE task_kind='user' on hot paths (agent-board,
+-- TasksHub, KPI counts). Without this every list query would full-scan tasks.
+CREATE INDEX IF NOT EXISTS idx_tasks_kind ON tasks(task_kind);
+-- decision f47c2c90: 向下收子 task（WHERE parent_task_id=?）的覆盖索引（外键列必建）。
+CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_task_id);
 CREATE INDEX IF NOT EXISTS idx_task_events_task ON task_events(task_id);
 CREATE INDEX IF NOT EXISTS idx_task_events_event ON task_events(event_id);
 
@@ -125,7 +217,6 @@ CREATE TABLE IF NOT EXISTS routing_events (
     intent_json TEXT NOT NULL,
     routed_to_type TEXT,
     routed_to_name TEXT,
-    is_forced INTEGER DEFAULT 0,
     obeyed INTEGER,
     classification_ms INTEGER,
     fallback_used INTEGER DEFAULT 0,
@@ -141,33 +232,27 @@ CREATE TABLE IF NOT EXISTS routing_events (
     experiment_group TEXT,
     skill_confidence REAL,
     skill_source TEXT,
+    -- R9 (decision 1544, 2026-06-10): provenance of the routing row. NULL for
+    -- normal hook-driven events; 'programmatic' for rows minted by code paths
+    -- (not a live user-prompt → route decision). Nullable, default NULL.
+    source TEXT,
+    -- decision-flow-overhaul (2026-05-28): links a routing row to the decision
+    -- that caused the spawn. Filled by pre-tool-use handler from the magic
+    -- marker `<!-- decision-id: X -->` in the Task prompt, or via fallback.
+    decision_id TEXT,
+    -- spawn_id: unique id for this spawn attempt (future dedup / pairing use)
+    spawn_id TEXT,
     created_at TEXT DEFAULT (datetime('now'))
 );
 
 CREATE INDEX IF NOT EXISTS idx_routing_events_session ON routing_events(session_id);
+CREATE INDEX IF NOT EXISTS idx_routing_decision ON routing_events(decision_id);
 CREATE INDEX IF NOT EXISTS idx_routing_events_route_request ON routing_events(route_request_id);
 CREATE INDEX IF NOT EXISTS idx_routing_events_ts ON routing_events(ts DESC);
 CREATE INDEX IF NOT EXISTS idx_routing_events_agent ON routing_events(routed_to_name, obeyed);
 CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed ON routing_events(obeyed);
 CREATE INDEX IF NOT EXISTS idx_routing_events_experiment ON routing_events(experiment_id, experiment_group);
 
--- ── Token Usage ──────────────────────────────────────────────────────
-
-CREATE TABLE IF NOT EXISTS token_usage (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    session_id TEXT NOT NULL,  -- logical ref → events.session_id; no FK due to write-order race (sessions is aggregate, may lag)
-    timestamp INTEGER NOT NULL,
-    input_tokens INTEGER NOT NULL,
-    output_tokens INTEGER NOT NULL,
-    total_tokens INTEGER NOT NULL,
-    model TEXT,
-    tool_name TEXT,
-    created_at TEXT DEFAULT (datetime('now'))
-);
-
-CREATE INDEX IF NOT EXISTS idx_token_usage_session ON token_usage(session_id);
-CREATE INDEX IF NOT EXISTS idx_token_usage_timestamp ON token_usage(timestamp DESC);
-
 -- ── Skill Invocations ─────────────────────────────────────────────────
 
 CREATE TABLE IF NOT EXISTS skill_invocations (
@@ -186,10 +271,34 @@ CREATE TABLE IF NOT EXISTS skill_invocations (
     success INTEGER DEFAULT 1,
     error TEXT,
     timestamp INTEGER NOT NULL,
+    -- audit #2 (decision f61b8a0c): NULLABLE marker. 1 = row was written at
+    -- UserPromptSubmit auto-MATCH/INJECT time (skill injected, NOT proven
+    -- invoked). NULL = real-call row (MCP skill_invoke / Skill tool). Lets web
+    -- metrics separate "injected" from "really invoked" without changing the
+    -- old `success` column semantics. See runColumnMigrations.
+    recorded_at_inject INTEGER,
+    -- Skill usefulness feedback (decision d24cd3a2 P0,
+    -- spec docs/design/2026-06-11/1524-skill-usefulness-feedback-spec.md):
+    -- agent POST-USE self-assessment of skill CONTENT actionability on THIS
+    -- project's task. DISTINCT from `success` (invoke didn't throw). Advisory
+    -- enum 'helped' | 'partial' | 'not-actionable' stored as free TEXT (no CHECK:
+    -- SQLite ADD COLUMN CHECK limits + forward-compat with new ratings). Nullable,
+    -- DEFAULT NULL → legacy rows untouched. usefulness_note = one-line rationale.
+    usefulness TEXT,
+    usefulness_note TEXT,
+    -- Project scope (decision 39839e30 Part 2): the project a skill pull belongs
+    -- to, so the workplace "Skill 调用" KPI can filter by project like the other
+    -- 3 KPIs do. Filled at write time (cf skill invoke → cwd/--project; MCP →
+    -- CF_PROJECT_ROOT/cwd) and historically back-filled from sessions.project_path
+    -- (join miss → stays NULL). Nullable, DEFAULT NULL → legacy rows untouched;
+    -- aggregations only add an `AND project_path = ?` clause when a project is
+    -- passed (additive, back-compat).
+    project_path TEXT,
     created_at TEXT DEFAULT (datetime('now'))
 );
 
 CREATE INDEX IF NOT EXISTS idx_skill_invocations_route_request ON skill_invocations(route_request_id);
+CREATE INDEX IF NOT EXISTS idx_skill_invocations_project ON skill_invocations(project_path);
 CREATE INDEX IF NOT EXISTS idx_skill_invocations_session ON skill_invocations(session_id);
 CREATE INDEX IF NOT EXISTS idx_skill_invocations_skill ON skill_invocations(skill_id);
 CREATE INDEX IF NOT EXISTS idx_skill_invocations_timestamp ON skill_invocations(timestamp DESC);
@@ -213,6 +322,15 @@ CREATE INDEX IF NOT EXISTS idx_tasks_start_time_session ON tasks(start_time DESC
 -- events: optimize session + hook_type composite queries
 CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC);
 
+-- events: covering index for the agent-board top_tools join (decision 7a3d07b5).
+-- Keyed by event_id (the join key from task_events) and carrying hook_type +
+-- tool_name so the per-row lookup satisfies `hook_type='PostToolUse' AND
+-- tool_name IS NOT NULL` and projects tool_name WITHOUT touching the events
+-- table. Combined with `INDEXED BY idx_task_events_task` on the task_events side,
+-- this flips the join driver to the ~40 page tasks (narrow probe) instead of
+-- scanning every PostToolUse row. Measured 485ms → ~10ms.
+CREATE INDEX IF NOT EXISTS idx_events_eid_hook_tool ON events(event_id, hook_type, tool_name);
+
 -- injections: optimize session + handler composite queries
 CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler);
 
@@ -222,3 +340,229 @@ CREATE INDEX IF NOT EXISTS idx_routing_events_type_ts ON routing_events(routed_t
 -- skill_invocations: optimize workflow/phase and feature_slug queries (H4 dedup: previously migration-only)
 CREATE INDEX IF NOT EXISTS idx_skill_invocations_workflow ON skill_invocations(workflow, phase);
 CREATE INDEX IF NOT EXISTS idx_skill_invocations_feature ON skill_invocations(feature_slug);
+
+-- ── KB Telemetry (v9.5) ───────────────────────────────────────────────
+-- Two append-only tables capturing knowledge-base query & build observability.
+-- Failures writing here MUST be swallowed (fail-silent) by callers; these
+-- tables are diagnostic and never on a request's critical path.
+
+CREATE TABLE IF NOT EXISTS kb_query_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts INTEGER NOT NULL,
+    project_path TEXT NOT NULL,
+    query TEXT NOT NULL,
+    result_count INTEGER NOT NULL,
+    ai_call_count INTEGER DEFAULT 0,
+    ai_input_tokens INTEGER,
+    ai_output_tokens INTEGER,
+    duration_ms INTEGER NOT NULL,
+    -- Attribution columns (decision d24cd3a2 Task B) — mirror skill_invocations.
+    -- Nullable; daemon-auto probes record source='daemon-probe', deliberate CLI/
+    -- agent pulls record source='cli' + verbatim reason, legacy rows stay NULL.
+    reason TEXT,
+    source TEXT,
+    agent_id TEXT,
+    workflow TEXT,
+    phase TEXT,
+    -- Post-use usefulness self-assessment (decision 096309e4 batch 1 item ①) —
+    -- mirrors skill_invocations.usefulness. An agent that pulled KB via
+    -- `cf knowledge query/fetch --reason` rates whether the CONTENT helped on
+    -- THIS task: 'helped' | 'partial' | 'not-actionable'. Nullable; legacy /
+    -- daemon-probe rows stay NULL (no backfill). This is the real "was KB used
+    -- AND did it help" signal — distinct from result_count (pages returned).
+    usefulness TEXT,
+    usefulness_note TEXT,
+    created_at TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_kb_query_log_ts ON kb_query_log(ts DESC);
+CREATE INDEX IF NOT EXISTS idx_kb_query_log_project ON kb_query_log(project_path);
+CREATE INDEX IF NOT EXISTS idx_kb_query_log_source ON kb_query_log(source);
+
+CREATE TABLE IF NOT EXISTS kb_build_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    build_id TEXT NOT NULL UNIQUE,
+    ts INTEGER NOT NULL,
+    project_path TEXT NOT NULL,
+    options_json TEXT NOT NULL,
+    stats_json TEXT,
+    duration_ms INTEGER,
+    status TEXT NOT NULL CHECK(status IN ('running', 'done', 'error')),
+    error_message TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    updated_at TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_kb_build_log_ts ON kb_build_log(ts DESC);
+CREATE INDEX IF NOT EXISTS idx_kb_build_log_project ON kb_build_log(project_path);
+CREATE INDEX IF NOT EXISTS idx_kb_build_log_project_ts ON kb_build_log(project_path, ts DESC);
+
+-- ── Forge Config (v9.x Phase 0) ────────────────────────────────────────
+-- Simple KV store for runtime feature flags / tuning knobs. Lets later phases
+-- ship behind a flag without recompilation. Default flags are seeded by the
+-- daemon at startup (only when the key is absent — user edits are preserved).
+
+CREATE TABLE IF NOT EXISTS forge_config (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- ── Tool Intercepts (v9.x Phase 1) ─────────────────────────────────────
+-- Records every PreToolUse decision made by the rules registry. While the
+-- `pre_tool_intercept.enabled` flag is OFF (default), the handler still runs
+-- in dry_run mode — rows are written with decision='dry_run' so the team can
+-- observe rule-hit distribution before flipping the kill switch.
+--
+-- decision contract:
+--   'deny'    — handler returned allow=false; tool execution blocked
+--   'warn'    — handler returned allow=true + additionalContext hint
+--   'bypass'  — rule matched but user supplied `forge:bypass=<reason>`
+--   'dry_run' — flag OFF; rule matched but never enforced (observability only)
+--
+-- outcome is back-filled by PostToolUse / Stop:
+--   'obeyed'   — AI heeded the hint (e.g. switched to Agent after deny)
+--   'override' — AI re-invoked the same tool / pattern despite hint
+--   'unknown'  — Stop fired without enough signal to classify
+
+CREATE TABLE IF NOT EXISTS tool_intercepts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_id TEXT,
+    session_id TEXT NOT NULL,
+    project_path TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    tool_name TEXT NOT NULL,
+    tool_input_summary TEXT,
+    rule_id TEXT NOT NULL,
+    decision TEXT NOT NULL CHECK(decision IN ('deny', 'warn', 'bypass', 'dry_run')),
+    hint TEXT,
+    outcome TEXT CHECK(outcome IS NULL OR outcome IN ('obeyed', 'override', 'unknown')),
+    bypass_token TEXT,
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (event_id) REFERENCES events(event_id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_tool_intercepts_session ON tool_intercepts(session_id);
+CREATE INDEX IF NOT EXISTS idx_tool_intercepts_rule ON tool_intercepts(rule_id);
+CREATE INDEX IF NOT EXISTS idx_tool_intercepts_ts ON tool_intercepts(timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_tool_intercepts_decision ON tool_intercepts(decision);
+
+-- ── Workflow Recommendations — RETIRED (decision fe6f98cd, 2026-06-10) ──
+-- Producers (workflow_classifier / skill_pairing) were deleted with spec 1200
+-- (2026-05-28); the consumption chain (deny rule, outcome marking, C7/C8,
+-- web display) was removed 2026-06-10. The table definition is kept so
+-- existing DBs preserve the 262 historical rows for audit; no code reads or
+-- writes it anymore.
+
+CREATE TABLE IF NOT EXISTS workflow_recommendations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    rule_id TEXT NOT NULL,
+    matched_keywords TEXT,
+    recommended_workflow TEXT NOT NULL,
+    recommended_agent_type TEXT NOT NULL,
+    reason TEXT,
+    outcome TEXT CHECK(outcome IS NULL OR outcome IN ('pending','accepted','partial_accepted','rejected','ignored','bypassed')),
+    outcome_at TEXT,
+    source TEXT DEFAULT 'workflow_classifier',
+    created_at TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_workflow_rec_session ON workflow_recommendations(session_id, outcome);
+CREATE INDEX IF NOT EXISTS idx_workflow_rec_ts ON workflow_recommendations(timestamp DESC);
+
+-- ── Decisions — 统一批准子系统 (2026-05-28 decision-flow-overhaul; C1 ──────
+-- convergence spec 0854, 2026-06-02) ──────────────────────────────────────
+-- Backs TWO row families via `kind`:
+--   kind='decision' — decision-maker lifecycle (pending → resolved | bypassed
+--     | expired). Daemon writes a row on [DECISION HINT]; decision-maker fills
+--     options/recommendation/risks via `cf decisions update`; user approves
+--     via Web UI or `cf decisions approve`.
+--   kind='spec'     — externally-registered spec files (absorbed from the
+--     retired pending_specs table). `cf decisions register --doc` writes the
+--     row with an 8-hex approval_token; user replies bare `批准 <token>` to
+--     short-circuit (status flips pending → resolved).
+--
+-- status contract:
+--   'advisory'  — (2026-06-08 decision 93e8fff1) daemon-minted decision-hint
+--                 bookkeeping row in the advisory model (interceptor removed,
+--                 decision 7c924678). NOT a "待批准" gate — it never blocks any
+--                 tool; it just records that a hint was emitted. This is now the
+--                 DEFAULT mint status for kind='decision' rows. Still 7-day TTL
+--                 expirable and still chat/CLI-approvable (advisory → resolved).
+--   'pending'   — hint emitted, decision-maker not yet spawned / doc not written.
+--                 For kind='spec' this is the real SpecGate approval gate; for
+--                 kind='decision' it is legacy (pre-93e8fff1 rows only).
+--   'resolved'  — user approved the decision (approved_at is set)
+--   'bypassed'  — main thread used bypass token / 'skip decision' keyword
+--   'expired'   — expires_at < now and no approval received
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id TEXT PRIMARY KEY,                  -- 8-char short id (nanoid/uuid slice)
+    session_id TEXT NOT NULL,
+    project_path TEXT NOT NULL,
+    trigger_event_id TEXT,                -- FK events.event_id (UserPromptSubmit)
+    trigger_prompt TEXT NOT NULL,         -- raw user prompt (≤500 chars)
+    suggested_agent TEXT,                 -- intent.suggested_agent
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK(status IN ('advisory','pending','resolved','bypassed','expired')),
+    -- Filled by decision-maker agent via `cf decisions update`:
+    options_json TEXT,                    -- JSON array of {name, what, pros, cons, loc, risk}
+    recommendation TEXT,                  -- recommended option name + rationale (≤2KB)
+    risks_json TEXT,                      -- JSON array of risk strings
+    open_questions_json TEXT,             -- JSON array of open question strings
+    decision_doc_path TEXT,               -- relative path under docs/design/
+    -- Filled by decision-maker agent (spec 1200 extension):
+    recommended_agents TEXT,              -- comma-separated agent ids (e.g. 'coder,planner')
+    recommended_skills TEXT,              -- comma-separated skill ids (e.g. 'safety-net,harness')
+    -- Unified approval subsystem (C1, 2026-06-02): decisions now also carries
+    -- externally-registered spec rows (kind='spec'), absorbing the retired
+    -- pending_specs table. 'decision' = daemon-minted decision-hint row;
+    -- 'spec' = a spec file registered via `cf decisions register` whose bare
+    -- `批准 <token>` short-circuits approval.
+    kind TEXT NOT NULL DEFAULT 'decision' CHECK(kind IN ('decision','spec')),
+    spec_source TEXT,                     -- spec-kind origin: planner/manual/decision/auto
+    spec_intent_json TEXT,                -- spec-kind intent payload (承接 pending_specs.intent_json)
+    -- decision-maker optimization Batch 1.1 (decision a5d5a85b, 2026-06-02):
+    -- implementation result, INDEPENDENT of `status` (approval lifecycle).
+    -- enum success|failed|partial is enforced in app code (writeDecisionOutcome);
+    -- relaxed non-empty CHECK mirrors sessions/tasks.outcome.
+    outcome TEXT CHECK(outcome IS NULL OR length(outcome) > 0),
+    -- Approve flow:
+    approval_token TEXT,
+    approved_at TEXT,
+    approved_by TEXT,                     -- 'user' | 'auto-bypass'
+    -- Option B (2026-05-29 decision b95e0956) bypass-governance audit fields:
+    --   bypass_flag: 1 when the approve happened WITHOUT a decision-maker
+    --                spawn trace within ±5min (main-thread self-approve path)
+    --   bypass_reason: free-text justification supplied by `cf decisions approve --reason`
+    --                or 'via decision-maker' when auto-filled because the maker
+    --                trace exists.
+    bypass_flag INTEGER NOT NULL DEFAULT 0 CHECK(bypass_flag IN (0, 1)),
+    bypass_reason TEXT,
+    -- Audit:
+    created_at TEXT DEFAULT (datetime('now')),
+    expires_at TEXT DEFAULT (datetime('now','+7 days')),
+    resolved_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_session ON decisions(session_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_decisions_status ON decisions(status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_decisions_trigger ON decisions(trigger_event_id);
+-- C1 (2026-06-02): spec-kind row lookups (rollup batch + listSpecsBySessionPending).
+CREATE INDEX IF NOT EXISTS idx_decisions_kind_session ON decisions(kind, session_id, status);
+-- C1: approval_token short-circuit lookup. Partial UNIQUE so the many
+-- decision-kind rows with NULL approval_token never collide.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_decisions_approval_token ON decisions(approval_token) WHERE approval_token IS NOT NULL;
+
+-- ── Pending Specs — RETIRED (C1 convergence, spec 0854, 2026-06-02) ───────
+-- The pending_specs table was a parallel "awaiting approval" subsystem. C1
+-- folded its semantics (spec file registration + bare `批准 <token>` short-
+-- circuit) into the decisions table (kind='spec', see above). The historical
+-- DDL + 8-hex approve token now live on decisions.approval_token /
+-- decision_doc_path / spec_source / spec_intent_json.
+--
+-- This DROP is the single delete point for the table on FRESH databases.
+-- Existing live DBs are dropped out-of-band by an operator after the data
+-- migration + backup (see spec 0854 Phase 4/5). Idempotent — IF EXISTS.
+--
+-- 关联 spec: docs/design/2026-06-02/0854-converge-pending-specs-into-decisions-C1-implementation-spec.md
+-- migrations/011_add_pending_specs.sql history is kept untouched.
+DROP TABLE IF EXISTS pending_specs;

package/dist/core/storage/sessions.d.ts

@@ -14,8 +14,26 @@ export interface SessionSummary {
     start_time: string;
     end_time: string;
 }
+/**
+ * Extended session row that exposes the Phase 2 metric rollup columns and
+ * outcome classification. Used by the Web timeline endpoint (`/api/insights/
+ * timeline`) to render the per-session header chips without joining four
+ * tables on every request.
+ *
+ * Keeps `SessionSummary` intact (sessions list views still rely on the
+ * narrow shape) — opt-in only via getSessionWithMetrics().
+ */
+export interface SessionWithMetrics extends SessionSummary {
+    project_path: string | null;
+    outcome: 'success' | 'partial' | 'failed' | 'abandoned' | null;
+    outcome_reason: string | null;
+    intercept_count: number;
+    kb_inject_count: number;
+    skill_match_count: number;
+}
 export declare class SessionOperations {
     private db;
+    private readonly upsertSessionStmt;
     constructor(db: Database.Database);
     /**
      * 将事件聚合到 sessions 表，供 querySessions 直接读取。
@@ -33,6 +51,15 @@ export declare class SessionOperations {
      * (e.g. from a hook payload or task row) — O(1) via primary key.
      */
     getSession(id: string): SessionSummary | null;
+    /**
+     * Phase 3 (master roadmap §2): fetch a session row with the rollup metric
+     * columns and outcome classification attached. Used by the Web timeline
+     * endpoint header so the React page can show intercept / KB / skill chips
+     * without a second round-trip.
+     *
+     * Accepts either a full PK or a >=8 char prefix (parity with getSession).
+     */
+    getSessionWithMetrics(idOrPrefix: string): SessionWithMetrics | null;
     /**
      * Look up a session by a session_id prefix. Used by web routes that accept
      * short ids from the URL bar.
@@ -45,8 +72,46 @@ export declare class SessionOperations {
     getSessionByPrefix(idPrefix: string): SessionSummary | null;
     querySessions(filter?: {
         project_path?: string;
+        /** LIKE %search% on first_prompt (case-insensitive via SQLite default) */
+        search?: string;
         limit?: number;
     }): SessionSummary[];
+    /**
+     * 写入 outcome 归因字段（v9.x outcome instrumentation）。
+     *
+     * 字段语义：
+     * - outcome: success/partial/failed/abandoned；null 表示尚未分类（不要覆盖）
+     * - outcome_reason: 自由文本，归因依据短文本（例 "commit+no_violation"）
+     * - commit_count / reverted_commits / user_violation_count: 信号原值，
+     *   保留下来便于回测调参 & 在 web 上展示
+     * - classified_at: ISO timestamp of classification call
+     *
+     * 调用方：daemon Stop handler；backfill 脚本；测试。
+     * 容错：每个字段都是可选；只更新提供的字段，避免误覆盖。
+     */
+    updateSessionOutcome(sessionId: string, updates: {
+        outcome?: 'success' | 'partial' | 'failed' | 'abandoned' | 'answered';
+        outcome_reason?: string;
+        commit_count?: number;
+        reverted_commits?: number;
+        user_violation_count?: number;
+        classified_at?: string;
+    }): void;
+    /**
+     * Phase 2 metrics rollup: 回填本 session 的三个事实表行数到 sessions 表。
+     *
+     * 调用方：Stop handler 在 classifyAndPersistOutcome 之后；这里只做写，不做
+     * 聚合逻辑（由 caller 用 facade 的 countToolInterceptsBySession /
+     * countInjectionsBySessionByHandler / countSkillInvocationsBySession 计算）。
+     *
+     * 容错：每个字段都是可选；只更新提供的字段。和 updateSessionOutcome 对称，
+     * 不重置未提供的列，避免被两个调用点互相覆盖。
+     */
+    updateSessionMetrics(sessionId: string, updates: {
+        interceptCount?: number;
+        kbInjectCount?: number;
+        skillMatchCount?: number;
+    }): void;
     /** Total session row count. */
     countAllSessions(): number;
     /** Per-day session counts (date(start_time) → count) within [since, until). */
@@ -62,10 +127,81 @@ export declare class SessionOperations {
         since: string;
         until?: string;
     }): SessionSummary[];
+    /**
+     * Phase 9.5 idle-session sweeper input.
+     *
+     * Sessions whose `outcome` is still NULL (never reached Stop hook — abnormal
+     * exit, experimental synthetic events, etc.) AND whose effective "last
+     * activity" timestamp is older than `cutoffIso`. We use
+     * `COALESCE(last_event_time, start_time)` so sessions that never recorded a
+     * non-UserPromptSubmit event still age out by their start time.
+     *
+     * Ordered by oldest-first so under a `LIMIT` cap the worst offenders go
+     * first (defensive against backlog bursts).
+     */
+    queryIdleUnclassifiedSessions(cutoffIso: string, limit: number): Array<{
+        session_id: string;
+        start_time: string;
+        last_event_time: string | null;
+        event_count: number | null;
+        user_violation_count: number | null;
+    }>;
     /** Count of sessions with start_time in [since, until?). */
     countSessionsByRange(opts: {
         since: string;
         until?: string;
     }): number;
+    /**
+     * Session-centric agent board projection (v2 rewrite, 2026-05-22).
+     *
+     * Returns one row per session in [since, now] with everything a Kanban card
+     * needs to show "what actually happened in this work unit":
+     *   - first user prompt (truncated)
+     *   - tool usage Top-3 (PostToolUse hook_type only)
+     *   - spawned subagents Top-3 (Task tool input.subagent_type)
+     *   - distinct edited files count + sample (Edit / Write tool_input.file_path)
+     *   - matched skills (skill_invocations)
+     *   - KB injection GROUP_CONCAT (route reshapes into page list)
+     *   - tool intercept decision counts (deny / warn / dry_run)
+     *   - git commit Bash count (heuristic: tool_input.command LIKE '%git commit%')
+     *   - session outcome + last_event_time so the route can lane-bucket
+     *
+     * Single SQL with correlated subqueries — every subquery hits a covered
+     * index (idx_events_session_hook / idx_tool_intercepts_session /
+     * idx_skill_invocations_session / idx_injections_session_handler), so the
+     * per-session fan-out is cheap. Limit-clamped 1..200.
+     */
+    queryAgentBoardSessions(opts: {
+        windowDays: number;
+        projectPath?: string;
+        limit?: number;
+    }): AgentBoardSessionRow[];
+}
+/** Raw row shape returned by queryAgentBoardSessions (route layer reshapes). */
+export interface AgentBoardSessionRow {
+    session_id: string;
+    project_path: string | null;
+    first_prompt: string | null;
+    start_time: string;
+    last_event_time: string;
+    end_time: string;
+    event_count: number | null;
+    outcome: 'success' | 'partial' | 'failed' | 'abandoned' | null;
+    outcome_reason: string | null;
+    intercept_count: number | null;
+    kb_inject_count: number | null;
+    skill_match_count: number | null;
+    commit_count: number | null;
+    user_violation_count: number | null;
+    top_tools_json: string | null;
+    spawned_json: string | null;
+    files_changed: number | null;
+    last_file: string | null;
+    bash_commit_count: number | null;
+    deny_count: number | null;
+    warn_count: number | null;
+    dryrun_count: number | null;
+    skills_json: string | null;
+    kb_meta_concat: string | null;
 }
 //# sourceMappingURL=sessions.d.ts.map