@winspan/claude-forge 8.54.4 → 9.12.0

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

@@ -7,6 +7,21 @@ import type Database from 'better-sqlite3';
 import type { ForgeEvent } from '../types.js';
 import type { SkillInvocationRow } from './rows.js';
 import type { Injection } from './injections.js';
+/**
+ * 单条任务窗内 KB 主动 pull（decision 93b3075b）。queryTaskKbPulls 返回，
+ * 任务详情端点透传为 kbPulls[]。query 是 KB page/topic 明文（NOT gzip），
+ * reason 形如 `<workflow>/kb-precedent`，usefulness 为 pull 后自评（可空）。
+ */
+export interface TaskKbPullRow {
+    ts: number;
+    query: string;
+    reason: string | null;
+    workflow: string | null;
+    phase: string | null;
+    usefulness: string | null;
+    usefulness_note: string | null;
+    result_count: number;
+}
 export interface TaskRecord {
     id: string;
     session_id: string;
@@ -20,7 +35,47 @@ export interface TaskRecord {
     /** First UserPromptSubmit user_prompt text for this task's session window.
      *  Populated by queryTasksFiltered via correlated subquery on idx_events_session_hook. */
     first_prompt?: string | null;
+    outcome?: 'success' | 'partial' | 'failed' | 'abandoned' | null;
+    outcome_reason?: string | null;
+    commit_count?: number | null;
+    reverted_commits?: number | null;
+    user_violation_count?: number | null;
+    classified_at?: string | null;
+    /**
+     * decision 265f59d5 (2026-06-08): LLM task-boundary classifier idempotency
+     * marker. ISO timestamp stamped once the async classifier has processed the
+     * prompt that minted this task. NULL = not yet classified (or never eligible).
+     */
+    llm_classified_at?: string | null;
+    /**
+     * Task-tracking overhaul (2026-05-27): write-time noise flag. 1 when title
+     * matched an envelope / sub-3-char / single-word slash command pattern at
+     * createTask time, else 0. Filter SQL uses this column instead of the old
+     * length+blocklist LIKE expression — see queryAgentBoardTasks WHERE clause.
+     *
+     * DEPRECATED since 2026-06-01 (spec b1480935 Option A) — `task_kind` is the
+     * successor. Read-side callers should branch on `task_kind` first and only
+     * fall back to is_noise on rows where backfill hasn't run yet.
+     */
+    is_noise?: number | null;
+    /**
+     * spec b1480935 (2026-06-01 Option A): per-task classification.
+     * Defaults to 'user' on legacy rows + new createTask writes from
+     * NormalPrompts; segmenter tags callback / image / system rows at
+     * write time. See `core/utils/noise-prompt.ts#classifyPromptKind`.
+     */
+    task_kind?: 'user' | 'agent-callback' | 'image' | 'system';
+    /**
+     * decision f47c2c90 (二期B, spec 1711): self-referencing FK to the user task
+     * that spawned this approval/continue follow-up turn. NULL for root tasks and
+     * for any task that didn't meet the conservative triple-gate linkage criteria.
+     * Used by the timeline parent-chain aggregation fallback when the task carries
+     * no decision_id. Exposed verbatim by mapRow.
+     */
+    parent_task_id?: string | null;
 }
+/** spec b1480935: canonical task-kind enum (single source of truth). */
+export type TaskKind = 'user' | 'agent-callback' | 'image' | 'system';
 export interface TaskFilter {
     session_id?: string;
     limit?: number;
@@ -29,6 +84,8 @@ export interface TaskFilter {
     from?: string;
     to?: string;
     search?: string;
+    /** spec b1480935 (2026-06-01): filter rows by task_kind whitelist. */
+    include_kinds?: ReadonlyArray<'user' | 'agent-callback' | 'image' | 'system'>;
 }
 export interface TaskPage {
     items: TaskRecord[];
@@ -38,19 +95,193 @@ export interface TaskPage {
 export declare class TaskOperations {
     private db;
     constructor(db: Database.Database);
+    /**
+     * Insert a task row.
+     *
+     * `is_noise` (deprecated since 2026-06-01, spec b1480935) is still accepted
+     * for back-compat — callers that haven't been migrated to `task_kind` will
+     * keep working; new writers should pass `task_kind` directly.
+     *
+     * `task_kind` (spec b1480935 Option A): when omitted, defaults to `'user'`
+     * via the schema DEFAULT. TaskSegmenter passes the classified kind from
+     * `classifyPromptKind()` so envelope rows surface in Web with a muted
+     * `agent-callback`/`image`/`system` chip instead of being hidden.
+     */
     writeTask(task: {
         id: string;
         session_id: string;
         title: string;
         start_time: string;
+        is_noise?: boolean;
+        task_kind?: TaskKind;
+        /**
+         * decision f47c2c90 (二期B): optional self-FK to the originating user task.
+         * Only TaskSegmenter passes it, and ONLY when the conservative triple-gate
+         * fires. Omitted → NULL (the default for every legacy / non-linked task).
+         */
+        parent_task_id?: string | null;
     }): void;
+    /**
+     * decision f47c2c90 (二期B, spec 1711 § Phase 2): link a task to its parent
+     * user task, but ONLY when no parent is set yet (idempotent — never overwrites
+     * an existing link). Also refuses to self-link (parentTaskId === taskId). This
+     * is the resume-path补链 hook; go-forward创建路径 passes parent_task_id directly
+     * to writeTask instead. Defense-in-depth for R4 (no cycles / no self-link).
+     */
+    setTaskParent(taskId: string, parentTaskId: string): void;
+    /**
+     * decision f47c2c90 (二期B, spec 1711 § Phase 2): find the most recent prior
+     * user task in the same session for the triple-gate parent linkage.
+     *
+     * Conservative selection (mirrors the backfill heuristic):
+     *   - same session, task_kind='user'
+     *   - start_time STRICTLY earlier than `beforeIso` (parent must precede child)
+     *   - start_time within `windowMs` of `beforeIso` (default 30min)
+     *   - PREFERS a non-ack-titled task as the substantive originator; falls back
+     *     to the most recent qualifying user task if none is non-ack.
+     *
+     * Returns the task id, or null when no qualifying prior task exists.
+     * Time math uses ISO lexical comparison (start_time is ISO TEXT — no numeric
+     * probe, DB column type landmine). `ackTitles` is the lowercase ack-token set
+     * supplied by the caller (single source of truth lives in the segmenter).
+     */
+    getMostRecentUserTaskBefore(opts: {
+        session_id: string;
+        beforeIso: string;
+        windowMs: number;
+        ackTitles: ReadonlyArray<string>;
+    }): string | null;
+    /**
+     * decision f47c2c90 (二期B, spec 1711 § Phase 3.1): aggregate ALL Task/Agent
+     * spawns across the parent_task_id chain that `anchorTaskId` belongs to —
+     * the timeline's fallback for workflows that have NO decision_id.
+     *
+     * Algorithm (two bounded recursive CTEs, R4 cycle-safe):
+     *   1. 向上找根: walk parent_task_id up from the anchor to the root
+     *      (parent_task_id IS NULL), depth ≤ 8.
+     *   2. 向下收子: from that root, collect all descendants (depth ≤ 8).
+     *   The union of both walks is the chain's task-id set. SQLite recursive CTEs
+     *   with UNION (set semantics) dedup automatically; the explicit depth column
+     *   guard caps a pathological cycle (a.parent=b, b.parent=a) at 8 hops so the
+     *   query always terminates with a finite result.
+     *
+     * Output shape is IDENTICAL to EventOperations.queryWorkflowSpawnsByDecisionId
+     * so task-timeline.ts can feed both through the same buildAgentSpawnEvents
+     * helper. subagent_type is read from the PLAINTEXT column (no gzip);
+     * tool_input / tool_output are decoded via the codec (same path as the A query)
+     * for the prompt / output previews. task_count = distinct chain task ids that
+     * actually carry ≥1 spawn (the "跨 N 轮" N for the B path).
+     *
+     * gzip note: only tool_input/tool_output flow through the codec; the chain walk
+     * itself touches plaintext tasks columns only (R7-safe).
+     */
+    queryParentTaskChainSpawns(anchorTaskId: string): {
+        spawns: Array<{
+            event_id: string;
+            session_id: string;
+            task_id: string | null;
+            timestamp: string;
+            hook_type: 'PreToolUse' | 'PostToolUse';
+            subagent_type: string | null;
+            tool_input: Record<string, unknown> | undefined;
+            tool_output: unknown;
+        }>;
+        task_count: number;
+    };
+    /**
+     * Read the plaintext `user_prompt` of every `UserPromptSubmit` event linked to
+     * any task in `taskIds` (decision ed5c3e93, spec 0909 per-turn-human-input).
+     *
+     * Used by the timeline route's two cross-task aggregation arms to collect the
+     * per-turn human inputs that live in OTHER per-prompt tasks of the same
+     * workflow (the originating task only sees its own first turn). The caller
+     * passes the distinct task_id set already computed from the spawn rows.
+     *
+     * CRITICAL (gzip event-content landmine, MEMORY note): `events.user_prompt` is
+     * a PLAINTEXT TEXT column — read it directly. It is NOT a gzip blob; do NOT run
+     * it through `decodeToolInput`/`decodeToolOutput` (those are for tool_input /
+     * tool_output only).
+     *
+     * Ordering: `ORDER BY e.timestamp ASC` — timestamp is ISO TEXT, lexically
+     * sortable (DB time-column-type landmine: do not treat it as ms INTEGER).
+     * Empty `taskIds` → `[]` (avoid an empty `IN ()` clause).
+     */
+    queryUserPromptsByTaskIds(taskIds: string[]): Array<{
+        event_id: string;
+        timestamp: string;
+        user_prompt: string;
+        task_id: string | null;
+    }>;
     updateTask(taskId: string, updates: {
         end_time?: string;
         status?: string;
         event_count?: number;
         title?: string;
+        outcome?: 'success' | 'partial' | 'failed' | 'abandoned' | 'answered';
+        outcome_reason?: string;
+        commit_count?: number;
+        reverted_commits?: number;
+        user_violation_count?: number;
+        classified_at?: string;
     }): void;
     linkEventToTask(taskId: string, eventId: string): void;
+    /**
+     * Task-tracking overhaul (2026-05-27 spec §3.3 Q3): pure-attachment variant
+     * of linkEventToTask. Inserts the task_events row + increments event_count
+     * BUT does NOT advance task.end_time. Used by the orphan-recovery fallback
+     * in TaskSegmenter.linkEvent so attaching a late-arriving sub-agent event
+     * to a recently-completed task doesn't stretch its duration KPI.
+     *
+     * Tradeoff: KPIs that count events get the orphan back, KPIs that read
+     * end_time stay honest. Outcome / commit_count rollups already ran at Stop
+     * time so they're unaffected either way.
+     */
+    attachEventToTask(taskId: string, eventId: string): void;
+    /**
+     * Orphan-event robustness fix (2026-06-01): direct lookup of a session's
+     * single active *user* task.
+     *
+     * Replaces the old `queryTasks(limit:5).find(...)` heuristic in
+     * TaskSegmenter.recoverActiveTask, which broke on high-task-count sessions:
+     * the active user task could be pushed out of the most-recent-5 window by a
+     * burst of newer agent-callback / completed rows, so `.find()` returned null
+     * and every subsequent event orphaned.
+     *
+     * SQL pins the predicate at the DB layer (no LIMIT truncation):
+     *   WHERE session_id = ? AND status = 'active'
+     *     AND (task_kind = 'user' OR (task_kind IS NULL AND is_noise = 0))
+     *   ORDER BY start_time DESC LIMIT 1
+     *
+     * The `task_kind IS NULL AND is_noise = 0` arm preserves backward compat for
+     * legacy rows written before the task_kind backfill (spec b1480935).
+     */
+    /**
+     * decision c6613590 P0 缺陷 B: cheap PK existence check for status='active'.
+     *
+     * Used by TaskSegmenter.getTrustedCurrent to PK-recheck a map hit before
+     * trusting it, so a task the stale-GC already flipped to 'completed' can't
+     * keep absorbing new events via a dangling in-memory pointer. Returns false
+     * for unknown / completed / abandoned ids.
+     */
+    isTaskActive(taskId: string): boolean;
+    getActiveUserTask(sessionId: string): TaskRecord | null;
+    /**
+     * Orphan-event robustness fix (2026-06-01): every session that currently has
+     * at least one active *user* task, with that task's id + start_time anchor.
+     *
+     * Drives TaskSegmenter.hydrateActiveTasks() so a freshly-restarted daemon can
+     * re-populate its in-memory `currentTasks` map up-front, instead of relying
+     * on per-event lazy recovery (which misses buffered/replayed events whose
+     * recovery heuristic doesn't fire).
+     *
+     * One row per session (the most recently started active user task wins) —
+     * mirrors getActiveUserTask's tie-break so hydrate and lazy-recover agree.
+     */
+    queryActiveUserTaskSessions(): Array<{
+        session_id: string;
+        task_id: string;
+        start_time: string;
+    }>;
     /** Legacy simple query — returns bare array (used by detail route internally) */
     queryTasks(filter?: {
         session_id?: string;
@@ -69,13 +300,119 @@ export declare class TaskOperations {
     /** Returns distinct project paths that have at least one task. */
     queryTaskProjects(): string[];
     getTaskEventIds(taskId: string): string[];
+    /**
+     * 批量把 event_id 反查到 task_id（用 task_events 关联表）。
+     *
+     * 场景：pipeline 视图想为每个 prompt 行附上 task_id（让用户点 prompt 直接
+     * 跳 task drawer 看"这个任务实际干了什么"，而不是噪音重的 session 视图）。
+     *
+     * 实现：一条 IN(...) 查询，event_id 通常 ≤ pipeline limit（默认 50，
+     * 上限 200）— 远低于 SQLite 单语句参数限制 (999)，无需分批。
+     */
+    queryTaskIdsByEventIds(eventIds: string[]): Map<string, string>;
+    /**
+     * Task-tracking overhaul (2026-05-27 spec §3.3): orphan-event recovery.
+     *
+     * After StopHandler completes the current task, late-arriving sub-agent
+     * PostToolUse events (the spawn's Bash/Read/etc tool calls that fire
+     * AFTER Stop closes the parent task) used to orphan because
+     * TaskSegmenter.linkEvent could not find an active task. Spec § 3.3
+     * Option C: when no active task exists, attach the event to the most
+     * recently completed task on the same session if it's within
+     * `sinceMs` of the event timestamp.
+     *
+     * Q3 (spec § 11): we do NOT update `task.end_time` here — the fallback
+     * is pure attachment (event_count grows by the linkEventToTask path in
+     * the caller). Updating end_time would stretch the duration KPI for
+     * every orphan that lands inside the recovery window and corrupt the
+     * outcome / task duration analytics.
+     *
+     * Order: most-recently-ended task first. event_time bound via SQLite
+     * julianday() — sinceMs is the look-back window in ms (typically 5 min).
+     * Returns null if no candidate within the window.
+     */
+    findRecentCompletedTaskForOrphan(opts: {
+        session_id: string;
+        event_ts_iso: string;
+        sinceMs: number;
+    }): TaskRecord | null;
+    /**
+     * Task-tracking deep fix (2026-05-27 spec §3.A): smart orphan-recovery helper.
+     *
+     * Finds the most recently completed task on the same session whose end_time
+     * is before the event timestamp AND there is no other task that started
+     * between that completed task's end_time and the event timestamp.
+     *
+     * Algorithm (plain English):
+     *   - candidate: status='completed', end_time IS NOT NULL, end_time <= event_ts
+     *   - guard: NOT EXISTS t2 where t2.session_id = t.session_id
+     *            AND t2.start_time > t.end_time AND t2.start_time <= event_ts
+     *   - if multiple candidates, take end_time DESC (most recent)
+     *   - returns null if no qualifying candidate
+     *
+     * Unlike findRecentCompletedTaskForOrphan (5-min window), this function has
+     * NO time-window cap. If the idle gap is 2h and no new task started during
+     * that gap, the event still attaches to the completed task. The "newer task
+     * block" guard prevents cross-task mis-attribution.
+     */
+    findCompletedTaskForOrphanSmart(opts: {
+        session_id: string;
+        event_ts_iso: string;
+    }): TaskRecord | null;
+    /**
+     * Task-tracking deep fix (2026-05-27 spec §5.C): UNION fallback query.
+     *
+     * Returns all events associated with the task via two sources:
+     *   1. linked (linked=1): events directly linked via task_events JOIN
+     *   2. fallback (linked=0): events in the same session+time window that are
+     *      NOT in task_events for this task AND NOT linked to any OTHER task
+     *      on the same session (prevents event theft across tasks)
+     *
+     * The `linked` field lets callers (web timeline) badge unlinked events.
+     */
+    queryEventsByTaskIdWithFallback(taskId: string, opts?: {
+        limit?: number;
+    }): Array<ForgeEvent & {
+        linked: 0 | 1;
+    }>;
+    /**
+     * B+ spec: 30min smart window 续命 helper.
+     *
+     * Reactivates a previously completed task so that a new UserPromptSubmit
+     * that arrives within TASK_RESUME_WINDOW_MS of its end_time can continue
+     * the same task instead of creating a new one.
+     *
+     * Mutations:
+     *   - status  → 'active'
+     *   - end_time → NULL  (cleared; duration KPI will re-anchor at Stop time)
+     *
+     * start_time is intentionally left untouched (spec §B+: "不改 start_time").
+     * Outcome / commit_count / classified_at columns are not touched here — they
+     * would have been NULL anyway (no outcome had landed in a gap of < 30min).
+     */
+    resumeTask(taskId: string): void;
     /**
      * 将 idle 超过阈值的 active task 批量转为 completed。
      * 条件：status='active' AND end_time IS NOT NULL
      *       AND (now - end_time) > idleMinutes 分钟。
-     * 返回：受影响行数。
+     *
+     * 返回：被关闭的 task id 列表（decision c6613590 P0 缺陷 B）。
+     *
+     * 此前返回行数（number），调用方拿不到具体被关的 task id，导致
+     * daemon 的 GC 把任务在 DB 标 completed 后，TaskSegmenter.currentTasks
+     * 内存 map 仍留着指向这些已关任务的悬空指针——后续事件经
+     * linkEventToTask 推进其 end_time，骗过 30min resume 窗，把多条独立
+     * prompt 错并进陈旧任务。改为返回 id 列表后，daemon 可据此从内存
+     * map 驱逐这些 entry，使 GC 与内存 map 保持一致。
+     *
+     * 实现：先 SELECT 出符合条件的 id（带 task_kind / session 信息以便
+     * 调用方按 session 驱逐），再用同一谓词 UPDATE。两步在 better-sqlite3
+     * 同步事务语义下原子。
      */
-    completeStaleActiveTasks(idleMinutes: number): number;
+    completeStaleActiveTasks(idleMinutes: number): Array<{
+        id: string;
+        session_id: string;
+    }>;
     /**
      * 按 taskId 直查单个 task（LEFT JOIN sessions 取 project_path）。
      * 替代旧 detail route 的「拉 5000 tasks 再 find(id)」。
@@ -105,9 +442,414 @@ export declare class TaskOperations {
     querySkillInvocationsByTaskWindow(taskId: string, opts?: {
         now_ms?: number;
     }): SkillInvocationRow[];
+    /**
+     * 该任务执行窗内 agent 主动 pull 的 KB（decision 93b3075b）—— 任务详情页右栏
+     * 「用了什么 → KB 主动 pull」从「无主动 pull」降级占位接成真实数据。
+     *
+     * scope 口径（与 querySkillInvocationsByTaskWindow 同思路，但 kb_query_log
+     * **没有 session_id 列**，故纯按时间窗 + project 圈到具体任务）：
+     *   - 时间窗：kb_query_log.ts(INTEGER ms) BETWEEN task.start_time(→ms) 和
+     *     COALESCE(task.end_time→ms+999, now_ms)。task.start/end 是 ISO TEXT，
+     *     用 strftime('%s', ...)*1000 转 ms 比较（kb_query_log.ts 地雷：是 ms 整数，
+     *     别打成 1970）。end_time IS NULL（active task）→ 取 now_ms 兜底。
+     *   - **project 圈定**：JOIN tasks t LEFT JOIN sessions s 取 project_path，
+     *     仅取 kb_query_log.project_path = 该任务 project 的 pull。本 session 多任务
+     *     共享 session_id，且同一时间窗可能并发别项目的 pull（实测 64d37b1d 窗内有
+     *     /prm 项目的 coder pull），故 project 过滤 + 时间窗一起把 pull 圈到本任务
+     *     的本项目，不串别项目/别任务。project_path 为 NULL（孤儿 task）→ 不串任何
+     *     pull（IS NOT NULL guard）。
+     *   - **只取真实 agent pull**：reason LIKE '%kb-precedent%'（coder/verify/
+     *     safetynet/decision 的 pull-reason 约定），与 countAgentKbPulls 同口径，
+     *     排掉 `cf knowledge query foo` 探针（同时 NULL-safe 排 sentinel
+     *     agent_id='cli-no-session'，decision 2d6d59b0）。
+     *
+     * `now_ms` 通过参数注入（end_time IS NULL 时取此值），便于测试 mock。
+     */
+    queryTaskKbPulls(taskId: string, opts?: {
+        now_ms?: number;
+    }): TaskKbPullRow[];
+    queryAgentBoardTasks(opts: {
+        windowDays: number;
+        projectPath?: string;
+        limit?: number;
+        /** 0-based offset for paginated list view (added 2026-05-26).
+         *  Kanban view always uses offset=0; only the list view paginator drives this. */
+        offset?: number;
+        now_ms?: number;
+        /**
+         * Task-tracking overhaul (2026-05-27 spec §3.2): include rows with
+         * `is_noise=1` (envelope / single-char / single-word slash command).
+         * Defaults to false — Web dashboards stay clean. Set true for audit /
+         * `?include_noise=1` API access.
+         *
+         * DEPRECATED since 2026-06-01 (spec b1480935) — translated internally
+         * to `includeKinds=['user','agent-callback','image','system']`. New
+         * callers should use `includeKinds` directly.
+         */
+        includeNoise?: boolean;
+        /**
+         * spec b1480935 (2026-06-01 Option A): filter rows by task_kind. When
+         * omitted defaults to `['user']` — only real human tasks reach Web.
+         * Pass the full set (or call with `includeNoise:true`) to surface
+         * envelope rows muted in the UI.
+         */
+        includeKinds?: ReadonlyArray<TaskKind>;
+    }): AgentBoardTaskRow[];
+    /**
+     * Shared task_kind filter resolution (decision b509fd91, 2026-06-08).
+     *
+     * Extracted so queryAgentBoardTasks / countAgentBoardTasks /
+     * queryAgentBoardPromptRows / countAgentBoardPromptRows all resolve the
+     * effective kind whitelist identically — no copy-paste drift. Resolution
+     * order matches the pre-existing inline logic:
+     *   1) explicit includeKinds      → use as-is
+     *   2) includeNoise=true (legacy) → all 4 kinds
+     *   3) default                     → ['user'] only
+     *
+     * Returns { effectiveKinds, kindFilter } where kindFilter is the SQL
+     * fragment (empty string when the caller wants all kinds — no filter needed).
+     */
+    private resolveKindFilter;
+    /**
+     * Shared outcome-bucket filter resolution (decision 0c1549ec, 2026-06-11).
+     *
+     * The TasksHub「我的任务」list view's outcome chips push their selection to
+     * the backend so filtering happens over the WHOLE window (not the page-local
+     * ~120 rows). The bucket classification here MUST mirror the CASE expression
+     * in queryAgentBoardPromptWindowAggregates so the chip COUNTS and the chip
+     * FILTER agree exactly — otherwise we re-introduce the count/filter 口径
+     * split that commit 40e03283 caused.
+     *
+     * Bucket → predicate over the `t` (tasks) alias:
+     *   - 'all' / undefined → '' (no filter, backward compatible)
+     *   - 'success'|'partial'|'failed' → t.outcome = '<bucket>'
+     *   - 'abandoned' → t.outcome='abandoned' OR (t.outcome IS NULL AND status='abandoned')
+     *   - 'answered'  → t.outcome='answered'
+     *   - 'none'      → residual catch-all (the in-progress / no-terminal-outcome
+     *                   bucket + any unknown/legacy outcome string), exactly the
+     *                   complement of the five buckets above.
+     * Returns the bare predicate (no leading AND); caller wraps in `AND (...)`.
+     * The `t` alias is parameterless (no bind values), so callers don't push args.
+     */
+    private resolveOutcomeFilter;
+    /**
+     * Shared free-text search filter for the TasksHub「我的任务」list view
+     * (decision 540ed063, 2026-06-11). Same downsink shape as resolveOutcomeFilter
+     * above: the search box pushes its term to the backend so matching happens
+     * over the WHOLE window (every page), not just the page-local ~120 rows a
+     * client `.filter` could see.
+     *
+     * Matching 口径 (must stay in lockstep between query and count):
+     *   - case-insensitive substring (`LIKE '%term%'`, LOWER on both sides);
+     *   - OR'd across two PLAINTEXT columns — `e.user_prompt` (the prompt text)
+     *     and `t.title` (the task title).
+     *
+     * ⚠️ gzip One-way Door (KB landmine): `events.tool_input` / `tool_output` hold
+     * GZIP-compressed blobs (declared TEXT but binary content) — a bare SQL LIKE
+     * over them silently matches nothing. This predicate therefore touches ONLY
+     * the two plaintext columns above and NEVER tool_input/tool_output.
+     *
+     * Empty / whitespace-only term → '' (no predicate), so absent or blank search
+     * is backward-compatible (= no filter). Returns { predicate, params }: the
+     * predicate has two `?` placeholders, so unlike resolveOutcomeFilter the caller
+     * MUST push the two bind values in clause order.
+     */
+    private resolveSearchFilter;
+    queryAgentBoardPromptRows(opts: {
+        windowDays: number;
+        projectPath?: string;
+        limit?: number;
+        offset?: number;
+        now_ms?: number;
+        includeNoise?: boolean;
+        includeKinds?: ReadonlyArray<TaskKind>;
+        /** decision 0c1549ec (2026-06-11): window-level outcome chip filter. */
+        outcome?: AgentBoardOutcomeFilter;
+        /** decision 540ed063 (2026-06-11): window-level free-text search (prompt + title). */
+        search?: string;
+    }): AgentBoardPromptRow[];
+    /**
+     * Unbounded count companion for queryAgentBoardPromptRows — the number of
+     * prompt rows (not tasks) in the window, for the list paginator's
+     * total-pages math. Same WHERE clause minus LIMIT/ORDER (decision b509fd91).
+     */
+    countAgentBoardPromptRows(opts: {
+        windowDays: number;
+        projectPath?: string;
+        now_ms?: number;
+        includeNoise?: boolean;
+        includeKinds?: ReadonlyArray<TaskKind>;
+        /** decision 0c1549ec (2026-06-11): window-level outcome chip filter. */
+        outcome?: AgentBoardOutcomeFilter;
+        /** decision 540ed063 (2026-06-11): window-level free-text search (prompt + title). */
+        search?: string;
+    }): number;
+    /**
+     * Window-level task aggregates for the prompt-rows list view (2026-06-10).
+     *
+     * Why: the list view's KPI bar ("总任务数 / 失败 / 平均时长") and outcome tab
+     * counts were derived client-side from `queryAgentBoardPromptRows` groups —
+     * i.e. from ONE PAGE (LIMIT default 120) — so they showed page-local numbers
+     * (e.g. 34) instead of true window totals (e.g. 709). This method runs the
+     * SAME WHERE 口径 as countAgentBoardPromptRows (window / project / kind
+     * whitelist, prompt-bearing tasks only) but dedupes to distinct tasks and
+     * aggregates outcome distribution + average duration in SQL.
+     *
+     * Semantics intentionally mirror the page's previous client-side math:
+     *   - task_total        = COUNT(DISTINCT task) — a task with N prompts counts once.
+     *   - outcome_abandoned = outcome='abandoned' OR (outcome IS NULL AND
+     *                         status='abandoned') — same fold the outcome chips did.
+     *   - outcome_answered  = outcome='answered' (spec 1100 Option C, 2026-06-02 —
+     *                         a first-class fifth value; no UI tab, but live data
+     *                         has hundreds of these so it must not vanish).
+     *   - outcome_none      = residual catch-all: outcome IS NULL with a
+     *                         non-abandoned status, OR any unknown/legacy outcome
+     *                         string (the column CHECK only enforces non-empty).
+     *   - avg_duration_sec  = AVG over tasks with duration > 0, where duration is
+     *                         the same CASE expression queryAgentBoardPromptRows
+     *                         computes for group_duration_sec (end-start, or
+     *                         now-start while active). Rounded to whole seconds.
+     *
+     * Invariant (tested, holds for ARBITRARY outcome strings thanks to the
+     * catch-all): success+partial+failed+abandoned+answered+none == task_total.
+     * MUST keep the inner WHERE in sync with queryAgentBoardPromptRows /
+     * countAgentBoardPromptRows above.
+     */
+    queryAgentBoardPromptWindowAggregates(opts: {
+        windowDays: number;
+        projectPath?: string;
+        now_ms?: number;
+        includeNoise?: boolean;
+        includeKinds?: ReadonlyArray<TaskKind>;
+    }): AgentBoardPromptWindowAggregates;
+    countAgentBoardTasks(opts: {
+        windowDays: number;
+        projectPath?: string;
+        now_ms?: number;
+        /**
+         * Task-tracking overhaul (2026-05-27 spec §3.2): mirrors
+         * queryAgentBoardTasks.includeNoise so the KPI count matches whatever
+         * the lane query returned for the same opts.
+         *
+         * DEPRECATED since 2026-06-01 (spec b1480935) — see queryAgentBoardTasks.
+         */
+        includeNoise?: boolean;
+        /** spec b1480935: mirror queryAgentBoardTasks.includeKinds. */
+        includeKinds?: ReadonlyArray<TaskKind>;
+    }): number;
+    /**
+     * Count "trivial" tasks since `sinceIso` — driven by DaemonObserverBadge's
+     * `trivial_passed_7d` field (spec 1750 § B1-3).
+     *
+     * Definition: tasks the task-segmenter marked as `is_noise=1` AT INSERT TIME
+     * (single-char prompt / single-word slash command / envelope task title). This
+     * is the closest server-side proxy for "daemon never engaged" — the trivial
+     * filter in `task-segmenter.ts` runs at write time using the same heuristics
+     * that gate decision-hint emission. Frontend's `isTrivialPath()` uses a finer
+     * signal (all daemon-intervention sections empty) but we don't have that
+     * aggregated; this proxy is good enough for the weekly counter chip.
+     *
+     * `datetime()` wrap normalises ISO 'T' vs SQLite default ' ' separator
+     * (see DecisionsOperations.countDecisionsSince for the reasoning).
+     */
+    countTrivialTasksSince(sinceIso: string): number;
+    /**
+     * Daily commit + task activity over a window (default 30 days).
+     *
+     * Used by `/api/insights/commit-activity` to drive the HealthHomePage
+     * 30d "Commit calendar" without the lane LIMIT undercount that the
+     * agent-board path suffered. Aggregates straight off the `tasks` table
+     * by `DATE(start_time)` so the result is unbounded by perf caps.
+     *
+     * The day buckets are filled with zeros for days with no tasks so the
+     * caller doesn't have to fill gaps client-side. Days ordered oldest→newest.
+     *
+     * Added 2026-05-26 — see docs/implementation changelog.
+     */
+    queryCommitActivityDaily(opts: {
+        days: number;
+        projectPath?: string;
+        now_ms?: number;
+    }): Array<{
+        date: string;
+        total: number;
+        succeeded: number;
+        failed: number;
+        commits: number;
+    }>;
+    /**
+     * Task-tracking deep fix (spec 1551 §6.D): Dry-run query for backfill-orphans CLI.
+     *
+     * Returns stats about how many orphan events can be attached via the smart-window
+     * algorithm. No writes are performed.
+     */
+    queryOrphanStats(): {
+        total_orphans: number;
+        attachable: number;
+        unattachable: number;
+        pct: string;
+    };
+    /**
+     * Task-tracking deep fix (spec 1551 §6.D): Sample orphan→task pairs for dry-run display.
+     *
+     * Returns up to `limit` (default 5) sample pairs showing which events would be attached.
+     */
+    sampleAttachablePairs(limit?: number): Array<{
+        event_id: string;
+        task_id: string;
+        task_title: string;
+        gap_min: number;
+    }>;
+    /**
+     * Task-tracking deep fix (spec 1551 §6.D.3): Apply backfill in a single atomic transaction.
+     *
+     * Inserts orphan→task links using INSERT OR IGNORE (idempotent).
+     * Then synchronizes event_count on updated tasks.
+     *
+     * Returns the number of rows inserted.
+     */
+    backfillOrphans(): number;
+    /**
+     * The first `limit` user-prompt texts of a task, oldest-first. Feeds the
+     * classifier the "what was the previous task about" context. Reads only the
+     * plaintext `user_prompt` column (never gzip tool_input).
+     */
+    getTaskUserPrompts(taskId: string, limit?: number): string[];
+    /** True once the async boundary classifier has stamped this task. */
+    isLlmClassified(taskId: string): boolean;
+    /** Stamp the idempotency marker without re-attributing (CONTINUATION verdict). */
+    markLlmClassified(taskId: string, atIso: string): void;
+    /**
+     * Re-attribute a single prompt event off `fromTaskId` onto a brand-new task,
+     * because the async classifier judged it NEW_TASK. Atomic + idempotent.
+     *
+     * Safety / idempotency guards (spec OQ #3 "re-check"):
+     *   1. `fromTaskId` must not already be llm_classified (double-write guard).
+     *   2. the event must STILL be linked to `fromTaskId` (no other path moved it
+     *      during the LLM delay window).
+     *   3. all writes run in ONE better-sqlite3 transaction.
+     *
+     * On success: creates the new task row, moves ONLY this event's
+     * task_events.task_id FK, decrements the old task's event_count / increments
+     * the new one, and stamps `llm_classified_at` on BOTH rows. Returns the new
+     * task id. On any guard failure returns null and writes nothing.
+     *
+     * Explicitly NOT done: deleting events, editing event content, closing or
+     * reactivating the source task (its lifecycle is owned by the segmenter /
+     * stop handler). OQ1 = "trust the LLM": no conservative event-count/time guard.
+     */
+    reattributePromptToNewTask(opts: {
+        fromTaskId: string;
+        eventId: string;
+        newTask: {
+            id: string;
+            session_id: string;
+            title: string;
+            start_time: string;
+            task_kind?: TaskKind;
+        };
+        atIso: string;
+    }): string | null;
     /** Map a raw events row to ForgeEvent (parses JSON columns). */
     private rowToEvent;
     private buildWhereConditions;
     private mapRow;
+    /**
+     * Count this task's Edit/Write intent events. Drives the `edit_intent_count`
+     * signal: a task with >0 edit-intent → `success`, one with 0 edit-intent is a
+     * pure Q&A / research task → `answered`.
+     *
+     * `tool_name` is NOT gzip-compressed (only `tool_input` is), so this is a
+     * pure SQL COUNT — no decode needed. We count PreToolUse so a single logical
+     * edit (Pre + Post) is counted once; multi-edit / notebook variants included.
+     */
+    countEditIntentEventsByTask(taskId: string): number;
+    queryIdleUnclassifiedTasks(sessionId: string): TaskRecord[];
+}
+/** Raw row shape returned by queryAgentBoardTasks (route layer reshapes). */
+export interface AgentBoardTaskRow {
+    id: string;
+    session_id: string;
+    project_path: string | null;
+    title: string;
+    description: string | null;
+    start_time: string;
+    end_time: string | null;
+    status: 'active' | 'completed' | 'abandoned';
+    event_count: number | null;
+    outcome: 'success' | 'partial' | 'failed' | 'abandoned' | null;
+    outcome_reason: string | null;
+    commit_count: number | null;
+    reverted_commits: number | null;
+    user_violation_count: number | null;
+    /** spec b1480935 (2026-06-01 Option A): per-task classification. */
+    task_kind: TaskKind;
+    duration_sec: number | null;
+    top_tools_json: string | null;
+    spawned_json: string | null;
+    files_changed: number | null;
+    last_file: string | null;
+    deny_count: number | null;
+    warn_count: number | null;
+    kb_meta_concat: string | null;
+}
+/**
+ * Outcome-chip filter buckets for the TasksHub list view (decision 0c1549ec,
+ * 2026-06-11). Mirrors the six buckets of AgentBoardPromptWindowAggregates so
+ * the chip COUNT and the chip FILTER use one classification. 'all' = no filter.
+ *   - 'none' = the in-progress / no-terminal-outcome residual bucket (the
+ *     ~365 tasks that previously had no chip and made sub-buckets ≠ 全部).
+ */
+export type AgentBoardOutcomeFilter = 'all' | 'success' | 'partial' | 'failed' | 'abandoned' | 'answered' | 'none';
+/**
+ * Raw row shape returned by queryAgentBoardPromptRows (decision b509fd91,
+ * 2026-06-08). One row = one UserPromptSubmit event; `group_id` = the task it
+ * belongs to (zero-schema grouping). Lightweight — no per-prompt aggregations;
+ * group_* fields carry the owning task's lane/status metadata.
+ */
+export interface AgentBoardPromptRow {
+    /** prompt event id — primary key + `?prompt=<event_id>` drawer deep-link. */
+    event_id: string;
+    /** user_prompt text, substr(1,300); frontend ellipsises further. */
+    prompt_text: string;
+    /** events.timestamp of this prompt. */
+    prompt_ts: string;
+    session_id: string;
+    project_path: string | null;
+    /** = owning task id. The "group" key (zero new column). */
+    group_id: string;
+    group_title: string;
+    group_status: 'active' | 'completed' | 'abandoned';
+    group_outcome: 'success' | 'partial' | 'failed' | 'abandoned' | null;
+    group_task_kind: TaskKind;
+    group_start_time: string;
+    group_end_time: string | null;
+    group_event_count: number;
+    group_duration_sec: number | null;
+}
+/**
+ * Window-level aggregates over DISTINCT prompt-bearing tasks (2026-06-10).
+ * Returned by queryAgentBoardPromptWindowAggregates — drives the list view's
+ * KPI bar + outcome tab counts so they reflect the whole window instead of
+ * the current page. Invariant: the six outcome buckets sum to task_total.
+ */
+export interface AgentBoardPromptWindowAggregates {
+    /** COUNT(DISTINCT task) in the window — N prompts of one task count once. */
+    task_total: number;
+    outcome_success: number;
+    outcome_partial: number;
+    outcome_failed: number;
+    /** outcome='abandoned' OR (outcome IS NULL AND status='abandoned') — chip fold. */
+    outcome_abandoned: number;
+    /** outcome='answered' (spec 1100 Option C fifth value — no UI tab today). */
+    outcome_answered: number;
+    /**
+     * Residual catch-all: outcome IS NULL with non-abandoned status (active /
+     * pending), plus any unknown/legacy outcome string. Keeps the partition
+     * invariant true for arbitrary data (column CHECK only enforces non-empty).
+     */
+    outcome_none: number;
+    /** AVG over tasks with duration > 0 (rounded, whole seconds); null when none. */
+    avg_duration_sec: number | null;
 }
 //# sourceMappingURL=tasks.d.ts.map