@winspan/claude-forge 9.2.0 → 9.12.0

package/dist/core/storage/base.js

@@ -8,6 +8,12 @@
  * - 一次性 sessions 回填
  *
  * 不涉及业务读写。所有业务读写由 *Operations 类组合 db 实例实现。
+ *
+ * 迁移机制（无编号 .sql runner）：schema.sql 是当前 schema 的唯一真相
+ * （全 idempotent CREATE ... IF NOT EXISTS，每次启动 db.exec 重放）+
+ * 本文件 runColumnMigrations()/runIndexMigrations()/runPostMigrations()
+ * 对旧库就地补列/补索引/补 CHECK。migrations/ 目录下不存在被读取的编号 .sql。
+ * 详见 migrations/README.md。
  */
 import Database from 'better-sqlite3';
 import { readFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
@@ -15,6 +21,48 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DATABASE } from '../constants.js';
 import { logger } from '../utils/logger.js';
+import { extractSpawnFields } from '../event-fields.js';
+import { decodeToolInput } from './codec/tool-input-codec.js';
+/**
+ * Backfill window for events.decision_id / subagent_type (decision c425f26f,
+ * spec 1544 § 1.3, user ruling #4). The spec aligns the window to existing
+ * retention; the only retention constant that bounds recoverability is the
+ * event-ttl-sweep WARM TTL (default 7 days), past which `tool_input` is NULLed
+ * (gzip blob gone — nothing left to decode). We use 10 days (spec default) as a
+ * conservative-but-safe ceiling: rows older than the warm TTL simply have NULL
+ * tool_input and are skipped by the WHERE (`tool_input IS NOT NULL` implied by a
+ * successful decode). base.ts is in the leaf-most `core` layer and MUST NOT
+ * depend on the daemon ConfigStore (decision ed98c8e8), so this is a static
+ * constant, not a config read.
+ */
+export const SPAWN_FIELD_BACKFILL_WINDOW = "-10 days";
+/**
+ * Backfill window for the one-shot tasks.parent_task_id historical linkage
+ * (decision f47c2c90, spec 1711 § Phase 1.1, user ruling Q2 = -10 days). Aligned
+ * with SPAWN_FIELD_BACKFILL_WINDOW so the two boot-time backfills cover the same
+ * recent slice. Historical rows cannot read the in-memory agentJustReturned flag,
+ * so the backfill uses a WEAKER pure-SQL heuristic (ack-title + same session +
+ * ≤30min prior non-ack user task); anything ambiguous stays NULL (宁缺毋滥).
+ */
+export const TASK_PARENT_BACKFILL_WINDOW = "-10 days";
+/**
+ * Resume window in minutes (mirrors TASK_RESUME_WINDOW_MS=30min in the daemon
+ * TaskSegmenter). The parent backfill only links a follow-up ack task to a prior
+ * user task started within this window. Kept as a static constant here because
+ * base.ts is leaf-most core and MUST NOT depend on the daemon config (ed98c8e8).
+ */
+const TASK_PARENT_BACKFILL_WINDOW_MIN = 30;
+/**
+ * Conservative ack-title set for the parent backfill (decision f47c2c90). A
+ * follow-up task whose title is one of these short acknowledgements is treated
+ * as an approval/continue turn that should chain back to the prior user task.
+ * Mirrors the segmenter's ACK_CONTINUE_KEYWORDS spirit but is a SQL-side
+ * lowercase exact-match list (titles are short ack tokens, not free text).
+ */
+const TASK_PARENT_ACK_TITLES = [
+    '批准', '同意', 'approve', '好', '好的', '嗯', 'ok', 'okay',
+    '可以', '是', '是的', '继续', 'yes', '对', '行', '没问题',
+];
 export class SQLiteBase {
     db;
     dbPath;
@@ -212,10 +260,49 @@ export class SQLiteBase {
         this.addColumnIfMissing('sessions', 'first_prompt', 'TEXT');
         this.addColumnIfMissing('routing_events', 'skill_confidence', 'REAL');
         this.addColumnIfMissing('routing_events', 'skill_source', 'TEXT');
+        // R9 (decision 1544, 2026-06-10): routing row provenance. NULL for normal
+        // hook-driven events; 'programmatic' for rows minted by code paths. Nullable,
+        // DEFAULT NULL keeps every legacy row untouched.
+        this.addColumnIfMissing('routing_events', 'source', 'TEXT');
         this.addColumnIfMissing('skill_invocations', 'workflow', 'TEXT');
         this.addColumnIfMissing('skill_invocations', 'phase', 'TEXT');
         this.addColumnIfMissing('skill_invocations', 'feature_slug', 'TEXT');
         this.addColumnIfMissing('skill_invocations', 'artifact_path', 'TEXT');
+        // audit #2 (decision f61b8a0c, 2026-06-09): distinguish "injected" rows from
+        // "really invoked" rows. The UserPromptSubmit auto-match path writes a row
+        // with success=1 the moment a skill is INJECTED — it never observes whether
+        // the skill was actually followed. That made every web "skill hit /
+        // effectiveness" metric (weekly-report / drift-detector / skill-stats) read
+        // injection counts as if they were real-call counts.
+        //
+        // Fix without breaking the old `success` semantics (5+ readers depend on the
+        // old column): add a NULLABLE marker `recorded_at_inject`. Auto-match
+        // injection rows stamp it 1; real-call rows (MCP skill_invoke /
+        // events.tool_name='Skill') leave it NULL. Readers filter on it to separate
+        // "injected" from "really invoked". DEFAULT NULL keeps legacy rows untouched.
+        this.addColumnIfMissing('skill_invocations', '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 whether a pulled skill's CONTENT was actionable
+        // on THIS project's task. DISTINCT from `success` (which only means the
+        // invoke call didn't throw) — usefulness measures content transfer.
+        //   usefulness      = 'helped' | 'partial' | 'not-actionable' (advisory enum,
+        //                     stored as free TEXT, nullable, DEFAULT NULL).
+        //   usefulness_note = one-line "what was/wasn't applicable", nullable.
+        // Nullable + no backfill → every legacy row reads usefulness=NULL untouched,
+        // verbatim mirror of the reason/workflow/recorded_at_inject additive columns.
+        this.addColumnIfMissing('skill_invocations', 'usefulness', 'TEXT');
+        this.addColumnIfMissing('skill_invocations', 'usefulness_note', 'TEXT');
+        // Project scope (decision 39839e30 Part 2, 2026-06-13): the project a skill
+        // pull belongs to, so the workplace "Skill 调用" KPI can filter by project
+        // like the other 3 KPIs already do. Mirror of kb_query_log.project_path.
+        // Nullable, DEFAULT NULL → every legacy row reads project_path=NULL untouched;
+        // aggregations only add `AND project_path = ?` when a project is passed
+        // (additive, back-compat with Phase 2c / Skill 详情页 / cf skill usefulness).
+        // Historical rows are one-shot back-filled from sessions.project_path in
+        // runPostMigrations → backfillSkillInvocationsProjectPathIfNeeded (join miss
+        // → stays NULL).
+        this.addColumnIfMissing('skill_invocations', 'project_path', 'TEXT');
         // Outcome instrumentation (v9.x). NOTE: SQLite ALTER TABLE ADD COLUMN can
         // only add CHECK constraints that don't reference other rows — the
         // outcome CHECK is therefore embedded in the column type clause below.
@@ -260,6 +347,17 @@ export class SQLiteBase {
         // to their granular kind via title-prefix sniff. The CHECK constraint
         // here is the same one schema.sql declares for fresh DBs.
         this.addColumnIfMissing('tasks', 'task_kind', `TEXT NOT NULL DEFAULT 'user' CHECK(task_kind IN ('user','agent-callback','image','system'))`);
+        // decision f47c2c90 (二期B, spec 1711): parent_task_id self-referencing FK
+        // for cross-turn workflow linkage on tasks that carry NO decision_id. The
+        // TaskSegmenter fills it (conservatively, triple-gate) for approval/continue
+        // follow-up turns; timeline aggregates the parent chain only when the task
+        // has no decision_id (else-branch fallback, strictly mutually exclusive with
+        // the decision_id path). Nullable, DEFAULT NULL → every legacy row untouched.
+        // SQLite ALTER ADD COLUMN cannot carry inline REFERENCES, so legacy DBs get
+        // a plain TEXT column with no FK enforcement — the app layer never relies on
+        // SQLite FK enforce (logical FK only). The one-shot backfill runs in
+        // runPostMigrations (backfillTasksParentIfNeeded).
+        this.addColumnIfMissing('tasks', 'parent_task_id', 'TEXT');
         // C1 (spec 0854, 2026-06-02): the pending_specs table was retired and is
         // DROPped by schema.sql. Its former `source` column migration + spec_path
         // index migration were removed here — schema.sql runs AFTER these column
@@ -268,13 +366,49 @@ export class SQLiteBase {
         // v9.x MVP1: KB injection metadata column. Stores JSON array of KB hits
         // (page name + score + refs) for the 'UserPromptSubmitHandler:kb' source.
         this.addColumnIfMissing('injections', 'metadata_json', 'TEXT');
+        // KB 采纳 telemetry（decision 148f7a0a, 2026-06-10 审计）：注入后同会话
+        // 出现主动 KB MCP 调用（mcp__claude-forge__knowledge*）时，PostToolUse
+        // handler 给该会话所有 source_handler LIKE '%:kb' 且 adopted_at IS NULL
+        // 的注入行盖 epoch-ms 时间戳。4 周后用一条 SQL 即可回答「注入的 KB 被
+        // 用了没」（adopted/total）。Nullable INTEGER；NULL = 从未被采纳。
+        this.addColumnIfMissing('injections', 'adopted_at', 'INTEGER');
         // F3 (audit-20260522 migration 009): writer-side tool_output 50KB truncation
         // marker. Legacy rows default to 0 (full content preserved).
         this.addColumnIfMissing('events', 'tool_output_truncated', 'INTEGER DEFAULT 0');
+        // decision c425f26f (spec 1544): cross-task execution-chain aggregation.
+        // decision_id + subagent_type are extracted to PLAINTEXT columns so a SQL
+        // GROUP BY decision_id can stitch a workflow fragmented across per-prompt
+        // tasks. Both nullable, DEFAULT NULL → every legacy row untouched.
+        // CRITICAL: these are plaintext TEXT — they NEVER flow through the gzip
+        // codec (gzip one-way-door); the go-forward writer (events.ts) extracts them
+        // pre-codec, the one-shot backfill (runPostMigrations) decodes gzip once to
+        // fill historical rows. ALTER ADD COLUMN nullable is an O(1) metadata op
+        // (no row rewrite) so this is cheap even on the 295 MB events table.
+        this.addColumnIfMissing('events', 'decision_id', 'TEXT');
+        this.addColumnIfMissing('events', 'subagent_type', 'TEXT');
         // decision-flow-overhaul (2026-05-28): link routing rows back to the decision
         // that triggered the spawn. Both columns default NULL (additive).
         this.addColumnIfMissing('routing_events', 'decision_id', 'TEXT');
         this.addColumnIfMissing('routing_events', 'spawn_id', 'TEXT');
+        // decision d24cd3a2 Task B (2026-06-11): make agent KB pulls attributable.
+        // kb_query_log gains the same attribution fields as skill_invocations so a
+        // deliberate `cf knowledge query --reason` pull (source='cli') is
+        // distinguishable from the daemon's automatic per-prompt probe
+        // (source='daemon-probe'). All nullable — legacy rows stay NULL, no backfill.
+        this.addColumnIfMissing('kb_query_log', 'reason', 'TEXT');
+        this.addColumnIfMissing('kb_query_log', 'source', 'TEXT');
+        this.addColumnIfMissing('kb_query_log', 'agent_id', 'TEXT');
+        this.addColumnIfMissing('kb_query_log', 'workflow', 'TEXT');
+        this.addColumnIfMissing('kb_query_log', 'phase', 'TEXT');
+        // decision 096309e4 batch 1 item ① (2026-06-13): KB post-use usefulness
+        // self-assessment, mirroring skill_invocations.usefulness. An agent that
+        // pulled KB via `cf knowledge query/fetch --reason` rates whether the CONTENT
+        // helped on THIS task. Nullable + no backfill → legacy / daemon-probe rows
+        // read usefulness=NULL untouched. This is the real "KB was used AND helped"
+        // signal that the dead injections.adopted_at path (MCP-only, subagents have
+        // zero MCP) could never capture.
+        this.addColumnIfMissing('kb_query_log', 'usefulness', 'TEXT');
+        this.addColumnIfMissing('kb_query_log', 'usefulness_note', 'TEXT');
         // decision-flow-overhaul (2026-05-28): update pending_specs.source CHECK to
         // include 'decision'. SQLite does NOT support altering CHECK constraints on
         // existing columns via ALTER TABLE, so for existing DBs the guard lives in
@@ -322,6 +456,8 @@ export class SQLiteBase {
     runIndexMigrations() {
         this.createIndexIfMissing('idx_skill_invocations_workflow', `CREATE INDEX IF NOT EXISTS idx_skill_invocations_workflow ON skill_invocations(workflow, phase)`);
         this.createIndexIfMissing('idx_skill_invocations_feature', `CREATE INDEX IF NOT EXISTS idx_skill_invocations_feature ON skill_invocations(feature_slug)`);
+        // decision 39839e30 Part 2: project-scoped skill KPI filtering.
+        this.createIndexIfMissing('idx_skill_invocations_project', `CREATE INDEX IF NOT EXISTS idx_skill_invocations_project ON skill_invocations(project_path)`);
         this.createIndexIfMissing('idx_sessions_start_time', `CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC)`);
         // Composite indexes for high-frequency session-scoped queries
         this.createIndexIfMissing('idx_events_session_ts', `CREATE INDEX IF NOT EXISTS idx_events_session_ts ON events(session_id, timestamp DESC)`);
@@ -329,9 +465,21 @@ export class SQLiteBase {
         this.createIndexIfMissing('idx_skill_invocations_session_ts', `CREATE INDEX IF NOT EXISTS idx_skill_invocations_session_ts ON skill_invocations(session_id, timestamp DESC)`);
         // spec b1480935 (2026-06-01): task_kind index for hot WHERE filters.
         this.createIndexIfMissing('idx_tasks_kind', `CREATE INDEX IF NOT EXISTS idx_tasks_kind ON tasks(task_kind)`);
+        // decision f47c2c90 (二期B): index on the parent FK column so the timeline
+        // chain query's `WHERE parent_task_id = ?` (向下收子 task) hits an index.
+        this.createIndexIfMissing('idx_tasks_parent', `CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_task_id)`);
         // Phase 1 Refactor: Additional performance indexes
         this.createIndexIfMissing('idx_routing_events_obeyed_ts', `CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts ON routing_events(obeyed, ts DESC)`);
         this.createIndexIfMissing('idx_events_session_hook', `CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC)`);
+        // decision 7a3d07b5: covering index for the agent-board top_tools join.
+        // (event_id, hook_type, tool_name) lets the per-row events lookup satisfy the
+        // PostToolUse + tool_name filter and project tool_name without a table hit;
+        // paired with `INDEXED BY idx_task_events_task` in tasks.queryAgentBoardTasks
+        // it flips the join driver off the full PostToolUse scan (485ms → ~10ms).
+        this.createIndexIfMissing('idx_events_eid_hook_tool', `CREATE INDEX IF NOT EXISTS idx_events_eid_hook_tool ON events(event_id, hook_type, tool_name)`);
+        // decision c425f26f (spec 1544): cross-task decision_id aggregation indexes.
+        this.createIndexIfMissing('idx_events_decision_id', `CREATE INDEX IF NOT EXISTS idx_events_decision_id ON events(decision_id)`);
+        this.createIndexIfMissing('idx_events_decision_spawn', `CREATE INDEX IF NOT EXISTS idx_events_decision_spawn ON events(decision_id, hook_type, tool_name, timestamp)`);
         this.createIndexIfMissing('idx_injections_session_handler', `CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler)`);
         this.createIndexIfMissing('idx_routing_events_type_ts', `CREATE INDEX IF NOT EXISTS idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC)`);
         // Outcome instrumentation indexes (v9.x)
@@ -360,12 +508,17 @@ export class SQLiteBase {
         this.backfillSessionsIfNeeded();
         this.rebuildWorkflowRecommendationsCheckIfNeeded();
         this.rebuildOutcomeCheckIfNeeded();
+        this.widenDecisionsStatusCheckIfNeeded();
+        this.dropDecisionsWorkflowTypeIfNeeded();
         this.dropDeadKbQueryLogColumnsIfNeeded();
         this.dropTokenUsageIfNeeded();
         this.dropRoutingIsForcedIfNeeded();
         this.backfillRoutingRoutedToTypePending();
         this.backfillTasksIsNoiseIfNeeded();
         this.backfillTasksTaskKindIfNeeded();
+        this.backfillSkillInvocationsProjectPathIfNeeded();
+        this.backfillEventsDecisionIdIfNeeded();
+        this.backfillTasksParentIfNeeded();
         const deprecatedTables = [
             'quality_issues', 'distill_results', 'v2_decisions',
             'v2_tool_events', 'experiment_assignments', 'routing_rule_states',
@@ -577,6 +730,228 @@ export class SQLiteBase {
             logger.warn(`[SQLiteStorage] migration: backfill routed_to_type='pending' failed: ${err}`);
         }
     }
+    /**
+     * One-shot back-fill of skill_invocations.project_path from
+     * sessions.project_path (decision 39839e30 Part 2). A skill pull's session_id
+     * JOINs sessions to recover the project it belonged to. Idempotent: the WHERE
+     * clause restricts to `project_path IS NULL AND session_id IS NOT NULL`, so a
+     * second startup touches 0 rows. Rows whose session can't be joined (sentinel
+     * session 'cli-no-session', or a session not in the sessions table) stay NULL
+     * — we deliberately do NOT invent a project for them.
+     *
+     * Errors are warn-logged and swallowed — daemon startup must not fail on a
+     * data back-fill; worst case some legacy rows stay project_path=NULL and only
+     * the all-projects view counts them.
+     */
+    backfillSkillInvocationsProjectPathIfNeeded() {
+        if (!this.hasTable('skill_invocations'))
+            return;
+        if (!this.hasColumn('skill_invocations', 'project_path'))
+            return;
+        try {
+            const res = this.db.prepare(`
+        UPDATE skill_invocations
+        SET project_path = (
+          SELECT s.project_path FROM sessions s
+          WHERE s.session_id = skill_invocations.session_id
+        )
+        WHERE project_path IS NULL
+          AND session_id IS NOT NULL
+          AND EXISTS (
+            SELECT 1 FROM sessions s2
+            WHERE s2.session_id = skill_invocations.session_id
+              AND s2.project_path IS NOT NULL
+          )
+      `).run();
+            if (res.changes > 0) {
+                logger.info(`[SQLiteStorage] migration: back-filled skill_invocations.project_path on ${res.changes} rows from sessions`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[SQLiteStorage] migration: backfill skill_invocations.project_path failed: ${err}`);
+        }
+    }
+    /**
+     * decision f47c2c90 (二期B, spec 1711 § Phase 1.1): one-shot, idempotent,
+     * gzip-free backfill of `tasks.parent_task_id` for recent ack/continue-class
+     * follow-up tasks that have no parent linked yet.
+     *
+     * Why gzip-free + weaker than go-forward: this runs over HISTORY, which has no
+     * in-memory `agentJustReturned` flag to read (R2). It uses a pure-SQL heuristic
+     * over the plaintext tasks columns ONLY (title / start_time / session_id —
+     * never the gzip events.tool_input, R7). Conservatism over recall:
+     *   - child candidate: task_kind='user', parent_task_id IS NULL, title is a
+     *     short ack token (TASK_PARENT_ACK_TITLES), start_time within the window.
+     *   - parent: the MOST RECENT same-session task_kind='user' task whose
+     *     start_time is STRICTLY earlier than the child AND within 30min AND whose
+     *     title is NOT itself an ack token (avoid ack→ack chains, prefer a
+     *     substantive originating task). No qualifying parent → stays NULL.
+     *   - never self-links (parent.id != child.id is implied by strict earlier
+     *     start_time + the explicit guard below).
+     *
+     * Idempotent gate: only runs when at least one un-linked recent ack child
+     * exists; the UPDATE itself only touches `parent_task_id IS NULL` rows, so a
+     * second boot updates 0 rows (success criterion: `backfilled 0 rows`).
+     *
+     * Wrapped in a transaction. Errors are warn-logged and swallowed — daemon
+     * startup must not fail on a data backfill. Time math uses
+     * `datetime('now', ?)` + ISO lexical comparison (tasks.start_time is ISO TEXT;
+     * NO numeric probe — DB column type landmine, MEMORY).
+     */
+    backfillTasksParentIfNeeded() {
+        if (!this.hasTable('tasks'))
+            return;
+        if (!this.hasColumn('tasks', 'parent_task_id'))
+            return;
+        try {
+            const ackPh = TASK_PARENT_ACK_TITLES.map(() => '?').join(',');
+            // Idempotent gate: any un-linked recent ack child left to consider?
+            const pending = this.db.prepare(`SELECT 1 FROM tasks
+          WHERE task_kind = 'user'
+            AND parent_task_id IS NULL
+            AND LOWER(trim(title)) IN (${ackPh})
+            AND start_time >= datetime('now', ?)
+          LIMIT 1`).get(...TASK_PARENT_ACK_TITLES, TASK_PARENT_BACKFILL_WINDOW);
+            if (!pending)
+                return;
+            // Correlated UPDATE: for each eligible ack child, pick the most recent
+            // same-session non-ack user task strictly earlier and within 30min.
+            const upd = this.db.prepare(`UPDATE tasks AS child
+            SET parent_task_id = (
+              SELECT p.id FROM tasks p
+               WHERE p.session_id = child.session_id
+                 AND p.task_kind = 'user'
+                 AND p.id != child.id
+                 AND p.start_time < child.start_time
+                 AND p.start_time >= datetime(child.start_time, '-${TASK_PARENT_BACKFILL_WINDOW_MIN} minutes')
+                 AND LOWER(trim(p.title)) NOT IN (${ackPh})
+               ORDER BY p.start_time DESC
+               LIMIT 1
+            )
+          WHERE child.task_kind = 'user'
+            AND child.parent_task_id IS NULL
+            AND LOWER(trim(child.title)) IN (${ackPh})
+            AND child.start_time >= datetime('now', ?)
+            AND EXISTS (
+              SELECT 1 FROM tasks p2
+               WHERE p2.session_id = child.session_id
+                 AND p2.task_kind = 'user'
+                 AND p2.id != child.id
+                 AND p2.start_time < child.start_time
+                 AND p2.start_time >= datetime(child.start_time, '-${TASK_PARENT_BACKFILL_WINDOW_MIN} minutes')
+                 AND LOWER(trim(p2.title)) NOT IN (${ackPh})
+            )`);
+            let changes = 0;
+            const tx = this.db.transaction(() => {
+                const res = upd.run(...TASK_PARENT_ACK_TITLES, // parent NOT IN (subquery)
+                ...TASK_PARENT_ACK_TITLES, // child IN (WHERE)
+                TASK_PARENT_BACKFILL_WINDOW, ...TASK_PARENT_ACK_TITLES);
+                changes = res.changes;
+            });
+            tx();
+            if (changes > 0) {
+                logger.info(`[SQLiteStorage] migration: backfilled tasks.parent_task_id on ${changes} rows`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[SQLiteStorage] migration: backfillTasksParentIfNeeded failed: ${err}`);
+        }
+    }
+    /**
+     * decision c425f26f (spec 1544 § 1.3): one-shot, idempotent backfill of the
+     * PLAINTEXT `events.decision_id` / `events.subagent_type` columns for recent
+     * Task/Agent spawn rows whose values still live only inside the gzip
+     * `tool_input` blob.
+     *
+     * Idempotent gate: only spawn rows in the backfill window where BOTH new
+     * columns are still NULL are touched, so a second daemon boot updates 0 rows
+     * (success criterion: `backfilled 0 rows`).
+     *
+     * gzip one-way-door: we DECODE `tool_input` via the codec (sniffs gzip magic),
+     * run `extractSpawnFields` on the decoded object, then write the extracted
+     * strings to the plaintext columns. The columns themselves never see gzip.
+     * Rows whose `tool_input` was already NULLed by the warm-TTL sweep have
+     * nothing to decode and are skipped (decode → undefined → both NULL, but the
+     * WHERE already excludes most via `tool_input IS NOT NULL`).
+     *
+     * Per-row try/catch: one malformed gzip blob never aborts the batch. Wrapped
+     * in a single transaction. Errors are warn-logged and swallowed — daemon
+     * startup must not fail on a data backfill.
+     *
+     * This is the boot-time wrapper (gated). The re-runnable engine lives in
+     * {@link backfillEventsDecisionId} so `cf maintenance backfill-spawn-fields`
+     * can force a full re-scan of the window.
+     */
+    backfillEventsDecisionIdIfNeeded() {
+        if (!this.hasTable('events'))
+            return;
+        if (!this.hasColumn('events', 'decision_id') || !this.hasColumn('events', 'subagent_type'))
+            return;
+        try {
+            // Idempotent gate: any un-backfilled recent spawn row left?
+            const pending = this.db.prepare(`SELECT 1 FROM events
+          WHERE hook_type = 'PreToolUse'
+            AND tool_name IN ('Task','Agent')
+            AND tool_input IS NOT NULL
+            AND decision_id IS NULL AND subagent_type IS NULL
+            AND timestamp >= datetime('now', ?)
+          LIMIT 1`).get(SPAWN_FIELD_BACKFILL_WINDOW);
+            if (!pending)
+                return;
+            const n = this.backfillEventsDecisionId();
+            if (n > 0) {
+                logger.info(`[SQLiteStorage] migration: backfilled events.decision_id/subagent_type on ${n} rows`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[SQLiteStorage] migration: backfillEventsDecisionIdIfNeeded failed: ${err}`);
+        }
+    }
+    /**
+     * Re-runnable engine for the decision_id / subagent_type backfill (decision
+     * c425f26f, user ruling #3 manual fallback). Scans the backfill window for
+     * Pre/Post Task/Agent spawn rows that still have NULL plaintext columns,
+     * decodes their gzip `tool_input`, and writes the extracted fields. Returns
+     * the number of rows updated. Safe to call repeatedly (idempotent: only NULL
+     * rows are touched). Exposed via the SQLiteStorage facade for the
+     * `cf maintenance backfill-spawn-fields` command.
+     */
+    backfillEventsDecisionId() {
+        if (!this.hasTable('events'))
+            return 0;
+        if (!this.hasColumn('events', 'decision_id') || !this.hasColumn('events', 'subagent_type'))
+            return 0;
+        const rows = this.db.prepare(`SELECT event_id, tool_name, tool_input FROM events
+        WHERE hook_type IN ('PreToolUse','PostToolUse')
+          AND tool_name IN ('Task','Agent')
+          AND tool_input IS NOT NULL
+          AND decision_id IS NULL AND subagent_type IS NULL
+          AND timestamp >= datetime('now', ?)`).all(SPAWN_FIELD_BACKFILL_WINDOW);
+        if (rows.length === 0)
+            return 0;
+        const upd = this.db.prepare(`UPDATE events SET decision_id = ?, subagent_type = ? WHERE event_id = ?`);
+        let updated = 0;
+        const tx = this.db.transaction(() => {
+            for (const row of rows) {
+                try {
+                    const decoded = decodeToolInput(row.tool_input);
+                    const { decisionId, subagentType } = extractSpawnFields(row.tool_name, decoded);
+                    // Only write when we actually extracted something — leaving both NULL
+                    // for unparseable / field-less rows keeps the idempotent gate honest
+                    // (they'd otherwise be re-scanned but never spuriously marked done).
+                    if (decisionId === null && subagentType === null)
+                        continue;
+                    upd.run(decisionId, subagentType, row.event_id);
+                    updated++;
+                }
+                catch (err) {
+                    logger.warn(`[SQLiteStorage] backfillEventsDecisionId: skip row ${row.event_id}: ${err}`);
+                }
+            }
+        });
+        tx();
+        return updated;
+    }
     /**
      * Migration 010: widen workflow_recommendations.outcome CHECK to include
      * 'partial_accepted'. SQLite cannot ALTER a CHECK constraint in place — we
@@ -745,6 +1120,154 @@ export class SQLiteBase {
             }
         }
     }
+    /**
+     * Migration 012 (decision 0fc1883c, 2026-06-08): DROP the dead
+     * `decisions.workflow_type` column. It was hard-coded to the literal
+     * 'pending' by decision-hint.ts (daemon no longer pre-classifies) and had
+     * ZERO consumers — no UPDATE path, no business logic branch. (The
+     * `intent.workflow_type` read by rules/pipeline-rollup is a DIFFERENT field
+     * sourced from injection metadata, NOT this column.)
+     *
+     * SQLite cannot reliably DROP COLUMN on older engines, so we mirror the
+     * migration-010/011 table-rebuild pattern: read the table's stored CREATE
+     * statement, strip the `workflow_type` line, CREATE the temp table, copy
+     * every OTHER column by EXPLICIT name (never `SELECT *` — the live column
+     * ORDER differs from schema.sql because migration-added columns are appended),
+     * DROP old, RENAME, replay indexes.
+     *
+     * Robustness choices:
+     *   - **Idempotent**: guarded by hasColumn — if workflow_type is already gone
+     *     (fresh DB from current schema.sql, or a prior boot) this is a no-op.
+     *   - **Data-preserving**: copies all non-workflow_type columns by name, so
+     *     every decision row keeps its other fields verbatim.
+     *   - **Index-preserving**: snapshots user indexes before the drop and replays
+     *     each `sql` after rename (made IF NOT EXISTS so schema.sql's recreate on
+     *     the same boot doesn't clash).
+     *
+     * Errors are warn-logged, never thrown — daemon startup must not fail on a
+     * migration. Worst case the dead column lingers (harmless — nothing reads it).
+     */
+    /**
+     * Migration 013 (decision 93e8fff1, 2026-06-08): widen the
+     * `decisions.status` CHECK to include 'advisory'. The advisory mint default
+     * (writeDecision) writes status='advisory', which the legacy CHECK
+     * (`status IN ('pending','resolved','bypassed','expired')`) would REJECT on
+     * existing live DBs — SQLite cannot ALTER a CHECK in place, so we mirror the
+     * migration-011/012 table-rebuild pattern: read the stored CREATE, string-
+     * replace ONLY the status CHECK fragment, CREATE temp → INSERT SELECT * →
+     * DROP → RENAME → replay indexes.
+     *
+     * Robustness:
+     *   - **Idempotent**: detected by sniffing the stored CREATE for the legacy
+     *     status enum WITHOUT 'advisory'. New DBs (schema.sql already carries
+     *     'advisory') and a second boot are no-ops.
+     *   - **Data-preserving**: copies every column verbatim via `SELECT *`.
+     *   - **Index-preserving**: snapshots non-autoindexes before the drop, replays
+     *     each (made IF NOT EXISTS so schema.sql's recreate on the same boot is
+     *     harmless).
+     *
+     * Errors are warn-logged, never thrown — daemon startup must not fail on a
+     * migration. Worst case the old CHECK lingers and a fresh advisory write is
+     * rejected at write time (writeDecision callers fail-silent), and the operator
+     * can re-run after the next build.
+     */
+    widenDecisionsStatusCheckIfNeeded() {
+        try {
+            if (!this.hasTable('decisions'))
+                return;
+            const sqlRow = this.db
+                .prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='decisions'`)
+                .get();
+            if (!sqlRow || !sqlRow.sql)
+                return;
+            // Already widened? The new CHECK contains 'advisory'. Skip if present.
+            if (/status\s+IN\s*\([^)]*'advisory'/i.test(sqlRow.sql))
+                return;
+            // Only act when the legacy status CHECK enum is present.
+            if (!/status\s+IN\s*\(\s*'pending'/i.test(sqlRow.sql))
+                return;
+            logger.info('[SQLiteStorage] migration 013: widening decisions.status CHECK to include advisory via table rebuild');
+            const newTableName = 'decisions_st_new';
+            const newCreate = sqlRow.sql
+                .replace(
+            // Match the status CHECK fragment regardless of internal whitespace.
+            /status\s+IN\s*\(\s*'pending'\s*,\s*'resolved'\s*,\s*'bypassed'\s*,\s*'expired'\s*\)/i, "status IN ('advisory','pending','resolved','bypassed','expired')")
+                .replace(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?decisions["'`]?/i, `CREATE TABLE ${newTableName}`);
+            if (newCreate === sqlRow.sql || !/'advisory'/i.test(newCreate)) {
+                logger.warn('[SQLiteStorage] migration 013: could not rewrite decisions.status CHECK (unexpected DDL shape) — skipping');
+                return;
+            }
+            const indexRows = this.db
+                .prepare(`SELECT sql FROM sqlite_master WHERE type='index' AND tbl_name='decisions' AND sql IS NOT NULL`)
+                .all();
+            const rebuild = this.db.transaction(() => {
+                this.db.exec(newCreate);
+                this.db.exec(`INSERT INTO ${newTableName} SELECT * FROM decisions;`);
+                this.db.exec(`DROP TABLE decisions;`);
+                this.db.exec(`ALTER TABLE ${newTableName} RENAME TO decisions;`);
+                for (const idx of indexRows) {
+                    const ddl = idx.sql.replace(/CREATE\s+(UNIQUE\s+)?INDEX\s+/i, (m) => /IF\s+NOT\s+EXISTS/i.test(idx.sql) ? m : `${m}IF NOT EXISTS `);
+                    this.db.exec(ddl);
+                }
+            });
+            rebuild();
+            logger.info('[SQLiteStorage] migration 013: decisions.status CHECK widened');
+        }
+        catch (err) {
+            logger.warn(`[SQLiteStorage] migration 013: widen status CHECK failed: ${err}`);
+        }
+    }
+    dropDecisionsWorkflowTypeIfNeeded() {
+        try {
+            if (!this.hasTable('decisions'))
+                return;
+            if (!this.hasColumn('decisions', 'workflow_type'))
+                return; // already dropped
+            const sqlRow = this.db
+                .prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='decisions'`)
+                .get();
+            if (!sqlRow || !sqlRow.sql)
+                return;
+            logger.info('[SQLiteStorage] migration 012: dropping dead decisions.workflow_type column via table rebuild');
+            const newTableName = 'decisions_wf_new';
+            // Strip the entire `workflow_type ...` column line (up to and including
+            // its trailing comma + newline). The column is declared NOT NULL with a
+            // trailing comment, e.g.:
+            //   workflow_type TEXT NOT NULL,          -- intent.workflow_type (...)
+            let newCreate = sqlRow.sql.replace(/^[ \t]*workflow_type\b[^\n]*\n/im, '');
+            // Point CREATE at the temp table (first occurrence of the table name).
+            newCreate = newCreate.replace(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?decisions["'`]?/i, `CREATE TABLE ${newTableName}`);
+            if (newCreate === sqlRow.sql || /\bworkflow_type\b/.test(newCreate)) {
+                logger.warn('[SQLiteStorage] migration 012: could not strip decisions.workflow_type from DDL (unexpected shape) — skipping');
+                return;
+            }
+            // Explicit column list (every column EXCEPT workflow_type), preserving the
+            // live table's order. Never `SELECT *` — live order != schema.sql order.
+            const liveCols = this.db.prepare(`PRAGMA table_info(decisions)`).all()
+                .map((c) => c.name)
+                .filter((name) => name !== 'workflow_type');
+            const colList = liveCols.join(', ');
+            // Snapshot user indexes (auto-indexes have NULL sql and are skipped).
+            const indexRows = this.db
+                .prepare(`SELECT sql FROM sqlite_master WHERE type='index' AND tbl_name='decisions' AND sql IS NOT NULL`)
+                .all();
+            const rebuild = this.db.transaction(() => {
+                this.db.exec(newCreate);
+                this.db.exec(`INSERT INTO ${newTableName} (${colList}) SELECT ${colList} FROM decisions;`);
+                this.db.exec(`DROP TABLE decisions;`);
+                this.db.exec(`ALTER TABLE ${newTableName} RENAME TO decisions;`);
+                for (const idx of indexRows) {
+                    const ddl = idx.sql.replace(/CREATE\s+(UNIQUE\s+)?INDEX\s+/i, (m) => /IF\s+NOT\s+EXISTS/i.test(idx.sql) ? m : `${m}IF NOT EXISTS `);
+                    this.db.exec(ddl);
+                }
+            });
+            rebuild();
+            logger.info('[SQLiteStorage] migration 012: decisions.workflow_type dropped');
+        }
+        catch (err) {
+            logger.warn(`[SQLiteStorage] migration 012: drop workflow_type failed: ${err}`);
+        }
+    }
     /**
      * 将 events 表按 session_id 聚合回填到 sessions 表，仅在 sessions 尚未对齐
      * （没有任何一行带 first_prompt）时触发。