@lelouchhe/webagent 0.8.0 → 0.10.0

package/lib/store.js

@@ -1,41 +1,231 @@
 import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { formatTaskPath, formatTaskReference, } from "./shared/task-reference.js";
+export const ROOT_TASK_ID = "root";
 export class MessageNotFoundError extends Error {
     constructor(messageId) {
         super(`Message not found: ${messageId}`);
         this.name = "MessageNotFoundError";
     }
 }
+function stringField(data, key) {
+    return typeof data[key] === "string" ? data[key] : undefined;
+}
+/** Normalize pre-title system events before any replay or egress path sees them. */
+function migrateSystemMessageData(raw) {
+    const data = JSON.parse(raw);
+    const existingTitle = stringField(data, "title");
+    const body = stringField(data, "body");
+    // Older task-created rows used `title` for the child task title, while the
+    // new payload uses it for the visible system-message title. Their `body`
+    // already contains the old visible text, so preserve it as title-only.
+    if (data.kind === "task_created" &&
+        data.taskTitle === undefined &&
+        existingTitle !== undefined &&
+        body !== undefined) {
+        const migrated = { ...data, title: body };
+        delete migrated.body;
+        return JSON.stringify(migrated);
+    }
+    if (existingTitle?.trim())
+        return null;
+    const messageBody = stringField(data, "messageBody");
+    const migrated = { ...data };
+    if (data.kind === "collaboration" && messageBody !== undefined) {
+        const source = stringField(data, "sourceLabel") ??
+            stringField(data, "sourceTaskId") ??
+            "?";
+        const target = stringField(data, "targetLabel") ??
+            stringField(data, "targetTaskId") ??
+            "?";
+        migrated.title = `${formatTaskReference(source)} sent ${formatTaskReference(target)}`;
+        migrated.body = messageBody;
+    }
+    else {
+        migrated.title = body?.trim() ? body : "System message";
+        delete migrated.body;
+    }
+    delete migrated.messageBody;
+    return JSON.stringify(migrated);
+}
 export class Store {
     db;
-    constructor(dataDir) {
+    dataDir;
+    agentKey;
+    constructor(dataDir, agentKey) {
+        if (!agentKey)
+            throw new Error("agentKey is required");
+        this.agentKey = agentKey;
+        this.dataDir = dataDir;
         mkdirSync(dataDir, { recursive: true });
         this.db = new Database(join(dataDir, "webagent.db"));
-        this.db.pragma("journal_mode = WAL");
-        this.migrate();
-        // Enforce foreign keys *after* migrate() so the one-time orphan cleanup
-        // can run without pragma interfering with legacy cleanup queries.
-        this.db.pragma("foreign_keys = ON");
+        try {
+            this.db.pragma("journal_mode = WAL");
+            this.db.pragma("foreign_keys = ON");
+            this.assertSupportedSchema();
+            this.initializeSchema();
+            this.migrateSystemMessagePayloads();
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
+    }
+    assertSupportedSchema() {
+        const legacy = this.db
+            .prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = 'sessions'")
+            .get();
+        const requiredColumns = {
+            tasks: [
+                "id",
+                "cwd",
+                "title",
+                "brief",
+                "workflow_status",
+                "parent_id",
+                "pending_compact_summary",
+                "model",
+                "mode",
+                "reasoning_effort",
+                "source",
+                "deleted_at",
+                "created_at",
+                "last_active_at",
+            ],
+            agent_sessions: [
+                "agent_key",
+                "agent_session_id",
+                "task_id",
+                "created_at",
+            ],
+            events: [
+                "id",
+                "task_id",
+                "seq",
+                "type",
+                "data",
+                "created_at",
+                "from_ref",
+            ],
+            shares: [
+                "token",
+                "task_id",
+                "shared_at",
+                "share_snapshot_seq",
+                "ttl_hours",
+                "display_name",
+                "owner_label",
+                "created_at",
+                "last_accessed_at",
+            ],
+            attachments: [
+                "id",
+                "task_id",
+                "kind",
+                "name",
+                "mime",
+                "size",
+                "realpath",
+                "upload_seq",
+                "width",
+                "height",
+                "created_at",
+            ],
+            inbox_messages: [
+                "id",
+                "from_ref",
+                "from_label",
+                "to_ref",
+                "deliver",
+                "dedup_key",
+                "title",
+                "body",
+                "cwd",
+                "created_at",
+            ],
+            messages: [
+                "id",
+                "source_task_id",
+                "direct_target_task_id",
+                "source_actor",
+                "body",
+                "created_at",
+            ],
+            message_projections: ["message_id", "task_id", "role", "created_at"],
+            deliveries: [
+                "id",
+                "message_id",
+                "recipient_task_id",
+                "idempotency_key",
+                "status",
+                "queued_at",
+                "claimed_at",
+                "delivered_at",
+                "failed_at",
+                "failure_reason",
+            ],
+        };
+        const incompatible = legacy
+            ? "legacy sessions table"
+            : Object.entries(requiredColumns).find(([table, columns]) => {
+                const exists = this.db
+                    .prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?")
+                    .get(table);
+                if (!exists)
+                    return false;
+                const actual = new Set(this.db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+                return (columns.some((column) => !actual.has(column)) ||
+                    [...actual].some((column) => !columns.includes(column)) ||
+                    (table === "events" &&
+                        this.db
+                            .prepare("SELECT 1 AS present FROM events WHERE from_ref IS NULL LIMIT 1")
+                            .get() !== undefined));
+            })?.[0];
+        if (incompatible) {
+            throw new Error(`Pre-1.0 data directory detected (${incompatible}). Back up and delete the data directory before restarting: ${this.dataDir}`);
+        }
     }
-    migrate() {
+    initializeSchema() {
         this.db.exec(`
-      CREATE TABLE IF NOT EXISTS sessions (
+      CREATE TABLE IF NOT EXISTS tasks (
         id TEXT PRIMARY KEY,
         cwd TEXT NOT NULL,
         title TEXT,
+        brief TEXT NOT NULL DEFAULT '',
+        workflow_status TEXT NOT NULL DEFAULT 'idle'
+          CHECK (workflow_status IN ('running', 'idle', 'blocked', 'done')),
+        parent_id TEXT REFERENCES tasks(id),
+        pending_compact_summary TEXT,
+        model TEXT,
+        mode TEXT,
+        reasoning_effort TEXT,
+        source TEXT NOT NULL DEFAULT 'auto',
+        deleted_at INTEGER,
         created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now')),
         last_active_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
       );
+      CREATE TABLE IF NOT EXISTS agent_sessions (
+        agent_key TEXT NOT NULL,
+        agent_session_id TEXT NOT NULL,
+        task_id TEXT REFERENCES tasks(id) ON DELETE CASCADE,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now')),
+        PRIMARY KEY (agent_key, agent_session_id)
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_sessions_task
+        ON agent_sessions(task_id)
+        WHERE task_id IS NOT NULL;
       CREATE TABLE IF NOT EXISTS events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
-        session_id TEXT NOT NULL REFERENCES sessions(id),
+        task_id TEXT NOT NULL REFERENCES tasks(id),
         seq INTEGER NOT NULL,
         type TEXT NOT NULL,
         data TEXT NOT NULL DEFAULT '{}',
-        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now')),
+        from_ref TEXT NOT NULL
       );
-      CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id, seq);
+      CREATE INDEX IF NOT EXISTS idx_events_task ON events(task_id, seq);
       CREATE TABLE IF NOT EXISTS push_subscriptions (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         endpoint TEXT NOT NULL UNIQUE,
@@ -44,39 +234,13 @@ export class Store {
         created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
       );
     `);
-        // Migrate existing tables: add columns if missing
-        const cols = this.db.prepare("PRAGMA table_info(sessions)").all();
-        const colNames = new Set(cols.map((c) => c.name));
-        if (!colNames.has("title")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN title TEXT");
-        }
-        if (!colNames.has("last_active_at")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN last_active_at TEXT");
-            // Backfill from created_at
-            this.db.exec("UPDATE sessions SET last_active_at = created_at WHERE last_active_at IS NULL");
-        }
-        if (!colNames.has("model")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN model TEXT");
-        }
-        if (!colNames.has("mode")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN mode TEXT");
-        }
-        if (!colNames.has("reasoning_effort")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN reasoning_effort TEXT");
-        }
-        if (!colNames.has("source")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN source TEXT NOT NULL DEFAULT 'auto'");
-        }
-        if (!colNames.has("deleted_at")) {
-            this.db.exec("ALTER TABLE sessions ADD COLUMN deleted_at INTEGER");
-        }
-        // messages — pending unbound notifications. POST /api/v1/messages with
+        // inbox_messages — pending unbound notifications. POST /api/v1/messages with
         // `to = "user"` lands here; consumeMessageTx transactionally moves the
-        // content into an existing ACP-backed session's events and deletes the
-        // row. Bound messages (to = session id) skip this table entirely and go
+        // content into an existing ACP-backed task's events and deletes the
+        // row. Bound messages (to = task id) skip this table entirely and go
         // straight to `events`.
         this.db.exec(`
-      CREATE TABLE IF NOT EXISTS messages (
+      CREATE TABLE IF NOT EXISTS inbox_messages (
         id              TEXT PRIMARY KEY,
         from_ref        TEXT NOT NULL,
         from_label      TEXT,
@@ -88,85 +252,85 @@ export class Store {
         cwd             TEXT,
         created_at      INTEGER NOT NULL
       );
-      CREATE INDEX IF NOT EXISTS idx_messages_created ON messages (created_at);
-      CREATE INDEX IF NOT EXISTS idx_messages_dedup   ON messages (to_ref, dedup_key);
+      CREATE INDEX IF NOT EXISTS idx_inbox_messages_created ON inbox_messages (created_at);
+      CREATE INDEX IF NOT EXISTS idx_inbox_messages_dedup ON inbox_messages (to_ref, dedup_key);
+
+      CREATE TABLE IF NOT EXISTS messages (
+        id TEXT PRIMARY KEY,
+        source_task_id TEXT NOT NULL,
+        direct_target_task_id TEXT NOT NULL,
+        source_actor TEXT NOT NULL CHECK (source_actor IN ('user', 'agent', 'system')),
+        body TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_messages_source_created
+        ON messages (source_task_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_messages_target_created
+        ON messages (direct_target_task_id, created_at);
+
+      CREATE TABLE IF NOT EXISTS message_projections (
+        message_id TEXT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+        task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+        role TEXT NOT NULL CHECK (role IN ('source', 'target', 'supervisor')),
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY (message_id, task_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_message_projections_task_created
+        ON message_projections (task_id, created_at);
+
+      CREATE TABLE IF NOT EXISTS deliveries (
+        id TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+        recipient_task_id TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        status TEXT NOT NULL CHECK (status IN ('queued', 'draining', 'delivered', 'failed')),
+        queued_at INTEGER NOT NULL,
+        claimed_at INTEGER,
+        delivered_at INTEGER,
+        failed_at INTEGER,
+        failure_reason TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_deliveries_recipient_status_queued
+        ON deliveries (recipient_task_id, status, queued_at);
     `);
         // client-server-split M2: idempotency for mutating REST calls. Stores
-        // the cached response per (session_id, client_op_id) so retries (after
+        // the cached response per (task_id, client_op_id) so retries (after
         // network/SSE reconnect) return the same result instead of re-executing
         // side effects.
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS client_ops (
-        session_id   TEXT NOT NULL,
+        task_id   TEXT NOT NULL,
         client_op_id TEXT NOT NULL,
         result_json  TEXT NOT NULL,
         created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now')),
-        PRIMARY KEY (session_id, client_op_id)
+        PRIMARY KEY (task_id, client_op_id)
       );
     `);
         // recent_paths: LRU path list for /new menu
-        const rpExists = this.db
-            .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='recent_paths'")
-            .get();
-        if (!rpExists) {
-            this.db.exec(`
-        CREATE TABLE recent_paths (
-          cwd TEXT PRIMARY KEY,
-          last_used_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
-        );
-      `);
-            // Backfill from existing sessions
-            this.db.exec(`
-        INSERT OR IGNORE INTO recent_paths (cwd, last_used_at)
-        SELECT cwd, MAX(COALESCE(last_active_at, created_at))
-        FROM sessions GROUP BY cwd;
-      `);
-        }
-        // events.from_ref — origin marker for every event row.
-        // Values: 'user' | 'system' | 'agent' | 'msg:<id>'. The 'msg:<id>'
-        // form is reserved for events authored by consuming an inbox message
-        // (see C7+). Bucketed backfill runs once for legacy rows.
-        const eventCols = this.db
-            .prepare("PRAGMA table_info(events)")
-            .all();
-        const eventColNames = new Set(eventCols.map((c) => c.name));
-        if (!eventColNames.has("from_ref")) {
-            this.db.exec("ALTER TABLE events ADD COLUMN from_ref TEXT");
-            // Buckets:
-            //   user   — user-authored input
-            //   system — client-originated side-channel actions + host responses
-            //            (permission responses, local bash, system messages)
-            //   agent  — everything else (assistant_message, thinking, tool_call,
-            //            tool_call_update, plan, prompt_done, permission_request,
-            //            etc.)
-            this.db.exec(`
-        UPDATE events SET from_ref = CASE
-          WHEN type = 'user_message' THEN 'user'
-          WHEN type IN ('permission_response', 'bash_command', 'bash_result',
-                        'system_message') THEN 'system'
-          ELSE 'agent'
-        END
-        WHERE from_ref IS NULL
-      `);
-        }
-        // One-time orphan cleanup: rows whose session_id no longer exists in
-        // `sessions`. Pre-FK writes could leave these behind (a session DELETE
-        // that didn't cascade because the FK pragma was off). Must run before
-        // enabling FK pragma.
-        this.db.exec("DELETE FROM events WHERE session_id NOT IN (SELECT id FROM sessions)");
-        // Secondary index for events queried by (session_id, type, created_at)
-        // -- used by upcoming inbox/message consume queries.
-        this.db.exec("CREATE INDEX IF NOT EXISTS idx_events_type ON events(session_id, type, created_at)");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS recent_paths (
+        cwd TEXT PRIMARY KEY,
+        last_used_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
+      );
+    `);
+        this.db.exec(`
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_parent_title_live
+        ON tasks (parent_id, title)
+        WHERE deleted_at IS NULL AND title IS NOT NULL;
+    `);
+        // Secondary index for events queried by (task_id, type, created_at)
+        // -- used by inbox/message consume queries.
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_events_type ON events(task_id, type, created_at)");
         // shares — public read-only share links (share-plan §4.1).
         // State machine: preview (shared_at NULL) → active (shared_at set).
         // Revocation = hard-delete the row (no audit trail kept).
-        // Multiple active siblings per session allowed (v4 multi-share).
+        // Multiple active siblings per task allowed (v4 multi-share).
         // Partial unique index enforces at most one un-activated preview per
-        // session at any time.
+        // task at any time.
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS shares (
         token TEXT PRIMARY KEY,
-        session_id TEXT NOT NULL REFERENCES sessions(id),
+        task_id TEXT NOT NULL REFERENCES tasks(id),
         shared_at INTEGER,
         share_snapshot_seq INTEGER NOT NULL,
         ttl_hours INTEGER,
@@ -175,32 +339,17 @@ export class Store {
         created_at INTEGER NOT NULL DEFAULT (CAST(strftime('%s','now') AS INTEGER) * 1000),
         last_accessed_at INTEGER
       );
-      CREATE INDEX IF NOT EXISTS idx_shares_session ON shares(session_id, created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_shares_task ON shares(task_id, created_at DESC);
     `);
-        // Migrate: drop revoked_at column from existing tables (v0.5+).
-        // Revocation is now hard-delete; kept rows are always live.
-        const shareCols = this.db
-            .prepare("PRAGMA table_info(shares)")
-            .all();
-        const shareColNames = new Set(shareCols.map((c) => c.name));
-        if (shareColNames.has("revoked_at")) {
-            // Hard-delete any pre-existing revoked rows so the migration
-            // doesn't resurrect them as "live" shares after dropping the column.
-            this.db.exec("DELETE FROM shares WHERE revoked_at IS NOT NULL");
-            // Drop the partial unique index that references revoked_at, then
-            // the column, then recreate the index without the revoked_at clause.
-            this.db.exec("DROP INDEX IF EXISTS shares_one_active_preview");
-            this.db.exec("ALTER TABLE shares DROP COLUMN revoked_at");
-        }
         this.db.exec(`
       CREATE UNIQUE INDEX IF NOT EXISTS shares_one_active_preview
-        ON shares(session_id)
+        ON shares(task_id)
         WHERE shared_at IS NULL;
     `);
-        // attachments — server-managed file uploads bound to a session.
-        // Lifecycle = session lifecycle: FK CASCADE removes the row when the
-        // session row is deleted (hard-delete path). Tombstoned (soft-deleted)
-        // sessions keep the row alive so the share viewer can still resolve
+        // attachments — server-managed file uploads bound to a task.
+        // Lifecycle = task lifecycle: FK CASCADE removes the row when the
+        // task row is deleted (hard-delete path). Tombstoned (soft-deleted)
+        // tasks keep the row alive so the share viewer can still resolve
         // file references for active shares.
         //
         // upload_seq = MAX(events.seq) at upload time. The share proxy uses
@@ -213,7 +362,7 @@ export class Store {
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS attachments (
         id           TEXT PRIMARY KEY,
-        session_id   TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        task_id   TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
         kind         TEXT NOT NULL,
         name         TEXT NOT NULL,
         mime         TEXT NOT NULL,
@@ -224,18 +373,8 @@ export class Store {
         height       INTEGER,
         created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
       );
-      CREATE INDEX IF NOT EXISTS idx_attachments_session ON attachments(session_id);
+      CREATE INDEX IF NOT EXISTS idx_attachments_task ON attachments(task_id);
     `);
-        const attachmentCols = this.db
-            .prepare("PRAGMA table_info(attachments)")
-            .all();
-        const attachmentColNames = new Set(attachmentCols.map((c) => c.name));
-        if (!attachmentColNames.has("width")) {
-            this.db.exec("ALTER TABLE attachments ADD COLUMN width INTEGER");
-        }
-        if (!attachmentColNames.has("height")) {
-            this.db.exec("ALTER TABLE attachments ADD COLUMN height INTEGER");
-        }
         // owner_prefs — key-value store for owner-scoped defaults (display_name,
         // last /by selection, etc). Single-user model = single owner scope.
         // Stored as plain key/value so we don't grow a new table per pref.
@@ -247,156 +386,519 @@ export class Store {
       );
     `);
     }
-    createSession(id, cwd, source = "auto") {
-        this.db
-            .prepare("INSERT INTO sessions (id, cwd, source) VALUES (?, ?, ?)")
-            .run(id, cwd, source);
-        return this.db
-            .prepare("SELECT * FROM sessions WHERE id = ?")
-            .get(id);
+    /** Normalize the pre-title system_message payload in place. This is
+     * idempotent and runs before any event can be replayed or returned. */
+    migrateSystemMessagePayloads() {
+        const rows = this.db
+            .prepare("SELECT id, data FROM events WHERE type = 'system_message'")
+            .all();
+        const update = this.db.prepare("UPDATE events SET data = ? WHERE id = ?");
+        this.db.transaction(() => {
+            for (const row of rows) {
+                const migrated = migrateSystemMessageData(row.data);
+                if (migrated !== null)
+                    update.run(migrated, row.id);
+            }
+        })();
+    }
+    /**
+     * Ensure the reserved Root record exists and attach existing live tasks
+     * that do not have a parent. This is additive and keeps every old task,
+     * event, attachment, and share intact; the Root's ACP binding is created by
+     * SessionManager after the bridge is ready.
+     *
+     * The default title is the literal "root": it is only applied while the
+     * title is still NULL, so a user rename survives restarts. The non-null
+     * title also keeps title generation from ever overwriting Root.
+     */
+    ensureRootTask(cwd) {
+        return this.db.transaction(() => {
+            this.db
+                .prepare("INSERT OR IGNORE INTO tasks (id, cwd, source, parent_id, title) VALUES (?, ?, 'root', NULL, 'root')")
+                .run("root", cwd);
+            this.db
+                .prepare("UPDATE tasks SET parent_id = NULL WHERE id = ?")
+                .run("root");
+            // Default title only while NULL so a user rename survives restarts.
+            this.db
+                .prepare("UPDATE tasks SET title = 'root' WHERE id = ? AND title IS NULL")
+                .run("root");
+            this.db
+                .prepare(`UPDATE tasks
+           SET parent_id = ?
+           WHERE id != ? AND parent_id IS NULL AND deleted_at IS NULL`)
+                .run("root", "root");
+            return this.db
+                .prepare("SELECT * FROM tasks WHERE id = ?")
+                .get("root");
+        })();
     }
-    listSessions(opts) {
+    createTask(id, cwd, source = "auto", agentSessionId = id, parentId = null, opts = {}) {
+        return this.db.transaction(() => {
+            this.db
+                .prepare(`INSERT INTO tasks
+           (id, cwd, source, parent_id, title, brief, workflow_status)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run(id, cwd, source, parentId, opts.title ?? id, opts.brief ?? "", opts.workflowStatus ?? "idle");
+            this.db
+                .prepare("INSERT INTO agent_sessions (agent_key, agent_session_id, task_id) VALUES (?, ?, ?)")
+                .run(this.agentKey, agentSessionId, id);
+            if (opts.initialMessage) {
+                this.createCollaborationMessage({
+                    ...opts.initialMessage,
+                    directTargetTaskId: id,
+                });
+            }
+            return this.db
+                .prepare("SELECT * FROM tasks WHERE id = ?")
+                .get(id);
+        })();
+    }
+    listTasks(opts) {
         if (opts?.source) {
             return this.db
-                .prepare("SELECT * FROM sessions WHERE source = ? AND deleted_at IS NULL ORDER BY COALESCE(last_active_at, created_at) DESC")
-                .all(opts.source);
+                .prepare(`SELECT s.*,
+             EXISTS (
+               SELECT 1 FROM events e
+               WHERE e.task_id = s.id AND e.type = 'user_message'
+             ) OR EXISTS (
+               SELECT 1 FROM messages m
+               WHERE m.source_actor = 'user'
+                 AND (m.source_task_id = s.id OR m.direct_target_task_id = s.id)
+             ) AS has_user_input
+           FROM tasks s
+           JOIN agent_sessions a ON a.task_id = s.id
+           WHERE a.agent_key = ? AND s.source = ? AND s.deleted_at IS NULL
+           ORDER BY COALESCE(s.last_active_at, s.created_at) DESC`)
+                .all(this.agentKey, opts.source);
         }
         return this.db
-            .prepare("SELECT * FROM sessions WHERE deleted_at IS NULL ORDER BY COALESCE(last_active_at, created_at) DESC")
-            .all();
+            .prepare(`SELECT s.*,
+           EXISTS (
+             SELECT 1 FROM events e
+             WHERE e.task_id = s.id AND e.type = 'user_message'
+           ) OR EXISTS (
+             SELECT 1 FROM messages m
+             WHERE m.source_actor = 'user'
+               AND (m.source_task_id = s.id OR m.direct_target_task_id = s.id)
+           ) AS has_user_input
+         FROM tasks s
+         JOIN agent_sessions a ON a.task_id = s.id
+         WHERE a.agent_key = ? AND s.deleted_at IS NULL
+         ORDER BY COALESCE(s.last_active_at, s.created_at) DESC`)
+            .all(this.agentKey);
     }
-    /** Returns live sessions only. Soft-deleted (tombstone) rows are hidden. */
-    getSession(id) {
+    /** Returns live tasks only. Soft-deleted (tombstone) rows are hidden. */
+    getTask(id) {
         return this.db
-            .prepare("SELECT * FROM sessions WHERE id = ? AND deleted_at IS NULL")
-            .get(id);
+            .prepare(`SELECT s.* FROM tasks s
+         JOIN agent_sessions a ON a.task_id = s.id
+         WHERE s.id = ? AND a.agent_key = ? AND s.deleted_at IS NULL`)
+            .get(id, this.agentKey);
+    }
+    registerInternalAgentSession(agentSessionId) {
+        this.db
+            .prepare("INSERT OR IGNORE INTO agent_sessions (agent_key, agent_session_id, task_id) VALUES (?, ?, NULL)")
+            .run(this.agentKey, agentSessionId);
+        const row = this.db
+            .prepare("SELECT * FROM agent_sessions WHERE agent_key = ? AND agent_session_id = ?")
+            .get(this.agentKey, agentSessionId);
+        if (row.task_id) {
+            throw new Error("Agent reused a user-visible task ID internally");
+        }
+        return row;
+    }
+    getAgentSessionId(taskId) {
+        return this.db
+            .prepare("SELECT agent_session_id FROM agent_sessions WHERE agent_key = ? AND task_id = ?")
+            .get(this.agentKey, taskId)?.agent_session_id;
+    }
+    getTaskId(agentSessionId) {
+        return this.db
+            .prepare("SELECT task_id FROM agent_sessions WHERE agent_key = ? AND agent_session_id = ? AND task_id IS NOT NULL")
+            .get(this.agentKey, agentSessionId)?.task_id;
+    }
+    getAgentSessionBinding(taskId) {
+        return this.db
+            .prepare("SELECT * FROM agent_sessions WHERE agent_key = ? AND task_id = ?")
+            .get(this.agentKey, taskId);
+    }
+    /**
+     * Replace the current ACP execution for a stable WebAgent task.
+     * The previous binding row is removed: its execution is explicitly
+     * retired by the caller and must never accept WebAgent events again.
+     */
+    rotateAgentSession(taskId, agentSessionId, cwd) {
+        return this.db.transaction(() => {
+            const current = this.getAgentSessionBinding(taskId);
+            if (!current)
+                throw new Error(`Task not found: ${taskId}`);
+            // Persist a requested cwd even when the agent returns the same
+            // execution id (no-op rotation); the caller decides whether to retire
+            // based on whether the binding actually moved.
+            if (cwd !== undefined) {
+                this.db
+                    .prepare("UPDATE tasks SET cwd = ? WHERE id = ?")
+                    .run(cwd, taskId);
+            }
+            if (current.agent_session_id === agentSessionId)
+                return current;
+            this.db
+                .prepare("DELETE FROM agent_sessions WHERE agent_key = ? AND task_id = ?")
+                .run(this.agentKey, taskId);
+            this.db
+                .prepare("INSERT INTO agent_sessions (agent_key, agent_session_id, task_id) VALUES (?, ?, ?)")
+                .run(this.agentKey, agentSessionId, taskId);
+            return this.getAgentSessionBinding(taskId);
+        })();
+    }
+    /** Bind an ACP execution to an existing WebAgent task without creating a row. */
+    bindAgentSession(taskId, agentSessionId) {
+        return this.db.transaction(() => {
+            if (!this.getTaskIncludingDeleted(taskId)) {
+                throw new Error(`Task not found: ${taskId}`);
+            }
+            const current = this.getAgentSessionBinding(taskId);
+            if (current) {
+                if (current.agent_session_id === agentSessionId)
+                    return current;
+                throw new Error(`Task already has an ACP binding: ${taskId}`);
+            }
+            this.db
+                .prepare("INSERT INTO agent_sessions (agent_key, agent_session_id, task_id) VALUES (?, ?, ?)")
+                .run(this.agentKey, agentSessionId, taskId);
+            return this.getAgentSessionBinding(taskId);
+        })();
+    }
+    ownsTask(taskId) {
+        return this.getAgentSessionBinding(taskId) !== undefined;
     }
     /**
-     * Returns a session row even if soft-deleted. Used by the public share
+     * Returns a task row even if soft-deleted. Used by the public share
      * viewer, which must keep working after the owner deletes the source
-     * session (events stay alive as long as any active share references them).
+     * task (events stay alive as long as any active share references them).
+     */
+    getTaskIncludingDeleted(id) {
+        return this.db.prepare("SELECT * FROM tasks WHERE id = ?").get(id);
+    }
+    /**
+     * Return the current lineage from Root (or the highest surviving ancestor)
+     * to a task. Includes soft-deleted ancestors so callers can detect a
+     * broken/hidden parent chain and revalidate it after acquiring a lock.
+     * Returns undefined for a missing row or a cycle.
+     */
+    getTaskLineage(id) {
+        const reversed = [];
+        const seen = new Set();
+        let current = this.getTaskIncludingDeleted(id);
+        while (current) {
+            if (seen.has(current.id))
+                return undefined;
+            seen.add(current.id);
+            reversed.push(current.id);
+            if (current.parent_id === null)
+                return reversed.reverse();
+            current = this.getTaskIncludingDeleted(current.parent_id);
+        }
+        return undefined;
+    }
+    /**
+     * The task's tree path (`@/parent/child`) for user-facing messages, or
+     * undefined when the row is missing or the lineage is broken. Users read this
+     * as the name of a task they can act on, unlike a raw id. Root is the path's
+     * origin and is never a segment, matching what the input grammar resolves.
      */
-    getSessionIncludingDeleted(id) {
-        return this.db.prepare("SELECT * FROM sessions WHERE id = ?").get(id);
+    getTaskPath(id) {
+        const lineage = this.getTaskLineage(id);
+        if (!lineage)
+            return undefined;
+        const segments = lineage[0] === ROOT_TASK_ID ? lineage.slice(1) : lineage;
+        return formatTaskPath(segments.map((taskId) => this.getTaskIncludingDeleted(taskId)?.title ?? taskId.slice(0, 8)));
+    }
+    /** Re-parent surviving children of a hard-deleted task under Root so the
+     *  FK on parent_id stays valid. Root is guaranteed to exist post-boot
+     *  (ensureRootTask runs before listen). No-op when there are no children. */
+    reparentChildrenToRoot(parentId) {
+        this.db
+            .prepare("UPDATE tasks SET parent_id = ? WHERE parent_id = ? AND id != ? AND id != ?")
+            .run(ROOT_TASK_ID, parentId, parentId, ROOT_TASK_ID);
+    }
+    /** Direct child ids of a task (excluding itself and Root), in any order. */
+    listChildren(parentId) {
+        return this.db
+            .prepare("SELECT id FROM tasks WHERE parent_id = ? AND id != ? AND id != ?")
+            .all(parentId, parentId, ROOT_TASK_ID).map((row) => row.id);
     }
     /**
-     * Delete a session. If any active (published) shares reference it, the
-     * session row + events are kept (soft-delete via deleted_at) so the
-     * shared snapshot remains viewable. Otherwise everything is hard-
-     * deleted. Preview shares (shared_at IS NULL) are always cleared:
-     * unpublished drafts share the session's lifecycle.
+     * Every descendant of a task, transitively (used to gate destructive
+     * operations such as the DELETE busy check against in-flight children).
+     */
+    getDescendantTaskIds(rootId) {
+        const out = [];
+        const queue = [rootId];
+        while (queue.length > 0) {
+            for (const child of this.listChildren(queue.pop())) {
+                queue.push(child);
+                out.push(child);
+            }
+        }
+        return out;
+    }
+    hasActiveShare(taskId) {
+        const row = this.db
+            .prepare("SELECT 1 AS present FROM shares WHERE task_id = ? AND shared_at IS NOT NULL LIMIT 1")
+            .get(taskId);
+        return row !== undefined;
+    }
+    /**
+     * Reset Root while preserving its stable anchor row. Every descendant is
+     * deleted using the ordinary task/share lifecycle, then Root's own event
+     * history and attachments are cleared. The caller rotates Root's ACP
+     * execution separately so this method remains a synchronous DB operation.
+     */
+    resetRootTask() {
+        const root = this.getTaskIncludingDeleted(ROOT_TASK_ID);
+        if (!root)
+            throw new Error("Root task not found");
+        if (this.hasActiveShare(ROOT_TASK_ID)) {
+            throw new Error("Root task has an active share");
+        }
+        const reset = this.db.transaction(() => {
+            const affected = [];
+            for (const childId of this.listChildren(ROOT_TASK_ID)) {
+                affected.push(...this.deleteTask(childId).affected);
+            }
+            this.db
+                .prepare("DELETE FROM shares WHERE task_id = ? AND shared_at IS NULL")
+                .run(ROOT_TASK_ID);
+            this.db.prepare("DELETE FROM events WHERE task_id = ?").run(ROOT_TASK_ID);
+            this.db
+                .prepare("DELETE FROM client_ops WHERE task_id = ?")
+                .run(ROOT_TASK_ID);
+            this.db
+                .prepare("DELETE FROM attachments WHERE task_id = ?")
+                .run(ROOT_TASK_ID);
+            this.db
+                .prepare("UPDATE tasks SET pending_compact_summary = NULL WHERE id = ?")
+                .run(ROOT_TASK_ID);
+            return { affected };
+        })();
+        return reset;
+    }
+    /**
+     * Delete a task and every descendant task recursively. The
+     * parent/child hierarchy is a hard ownership link, so the deletion is
+     * immediate and needs no confirmation (a confirmation step is deferred
+     * until a tree UI exists). Each affected task follows its own share
+     * rules: a task with active shares is tombstoned (kept so share
+     * viewers still resolve) and its binding removed; a share-tombstoned
+     * descendant of a hard-deleted parent is re-parented under Root.
      *
-     * Returns "hard" if the row + events were physically removed, "soft"
-     * if the row was tombstoned because shares still reference it. Callers
-     * use this to decide whether to clean up filesystem artefacts (images).
+     * Returns every affected task with its deletion mode and the ACP
+     * execution bound at deletion time, so callers can retire executions,
+     * clean up in-memory state, and broadcast `task_deleted` per id.
      */
-    deleteSession(id) {
+    deleteTask(id) {
+        if (id === ROOT_TASK_ID) {
+            throw new Error("Root task cannot be deleted");
+        }
+        const affected = [];
+        // Delete descendants first (children before parents) so the FK on
+        // parent_id can never block the parent's own row removal.
+        const children = this.listChildren(id);
+        for (const childId of children) {
+            affected.push(...this.deleteTask(childId).affected);
+        }
+        const binding = this.getAgentSessionBinding(id);
         // Drop preview shares regardless — they are owner-only drafts and
-        // share the session's lifecycle by design.
+        // share the task's lifecycle by design.
         this.db
-            .prepare("DELETE FROM shares WHERE session_id = ? AND shared_at IS NULL")
+            .prepare("DELETE FROM shares WHERE task_id = ? AND shared_at IS NULL")
             .run(id);
         const activeShareCount = this.db
-            .prepare("SELECT COUNT(*) AS n FROM shares WHERE session_id = ? AND shared_at IS NOT NULL")
+            .prepare("SELECT COUNT(*) AS n FROM shares WHERE task_id = ? AND shared_at IS NOT NULL")
             .get(id).n;
-        this.db.prepare("DELETE FROM client_ops WHERE session_id = ?").run(id);
+        this.db.prepare("DELETE FROM client_ops WHERE task_id = ?").run(id);
         if (activeShareCount > 0) {
-            // Soft-delete: keep events + sessions row so public share viewers
-            // can still resolve. revokeShare() / reapTombstoneIfOrphaned()
-            // finishes the job once the last share is gone.
+            // Soft-delete: keep events + tasks row so public share viewers
+            // can still resolve. The owner-side binding is retired like a hard
+            // delete; revokeShare() / reapTombstoneIfOrphaned() finishes the job
+            // once the last share is gone.
             this.db
-                .prepare("UPDATE sessions SET deleted_at = ? WHERE id = ?")
+                .prepare("UPDATE tasks SET deleted_at = ? WHERE id = ?")
                 .run(Date.now(), id);
-            return "soft";
+            if (binding) {
+                this.db
+                    .prepare("DELETE FROM agent_sessions WHERE agent_key = ? AND agent_session_id = ?")
+                    .run(this.agentKey, binding.agent_session_id);
+            }
+            affected.unshift({
+                id,
+                mode: "soft",
+                agentSessionId: binding?.agent_session_id ?? null,
+            });
+            return { mode: "soft", affected };
         }
-        this.db.prepare("DELETE FROM events WHERE session_id = ?").run(id);
-        this.db.prepare("DELETE FROM sessions WHERE id = ?").run(id);
-        return "hard";
+        // Hard delete: re-parent any survivor (share-tombstoned descendants)
+        // under Root, then drop events and the row (agent_sessions cascades).
+        this.reparentChildrenToRoot(id);
+        this.failOutstandingDeliveriesForDeletedTask(id);
+        this.db.prepare("DELETE FROM events WHERE task_id = ?").run(id);
+        this.db.prepare("DELETE FROM tasks WHERE id = ?").run(id);
+        affected.unshift({
+            id,
+            mode: "hard",
+            agentSessionId: binding?.agent_session_id ?? null,
+        });
+        return { mode: "hard", affected };
     }
     /**
-     * Hard-delete events + sessions row for a session that has been soft-
-     * deleted and whose last share was just revoked. No-op if the session
+     * Hard-delete events + tasks row for a task that has been soft-
+     * deleted and whose last share was just revoked. No-op if the task
      * is still live (deleted_at IS NULL) or still has active shares.
      * Returns true if a tombstone was reaped.
      */
-    reapTombstoneIfOrphaned(sessionId) {
-        const sess = this.db
-            .prepare("SELECT id FROM sessions WHERE id = ? AND deleted_at IS NOT NULL")
-            .get(sessionId);
-        if (!sess)
+    reapTombstoneIfOrphaned(taskId) {
+        const row = this.db
+            .prepare("SELECT id FROM tasks WHERE id = ? AND deleted_at IS NOT NULL")
+            .get(taskId);
+        if (!row)
             return false;
         const remaining = this.db
-            .prepare("SELECT COUNT(*) AS n FROM shares WHERE session_id = ?")
-            .get(sessionId).n;
+            .prepare("SELECT COUNT(*) AS n FROM shares WHERE task_id = ?")
+            .get(taskId).n;
         if (remaining > 0)
             return false;
-        this.db.prepare("DELETE FROM events WHERE session_id = ?").run(sessionId);
-        this.db.prepare("DELETE FROM sessions WHERE id = ?").run(sessionId);
+        // Its live children were deleted when it was tombstoned; any survivor
+        // (a share-tombstoned descendant of this tombstone) still references it
+        // and must be re-parented under Root before the row goes away.
+        this.reparentChildrenToRoot(taskId);
+        this.failOutstandingDeliveriesForDeletedTask(taskId);
+        this.db.prepare("DELETE FROM events WHERE task_id = ?").run(taskId);
+        this.db.prepare("DELETE FROM tasks WHERE id = ?").run(taskId);
         return true;
     }
-    /** Delete sessions that have zero events and are older than minAgeS seconds. Returns IDs deleted. */
-    deleteEmptySessions(minAgeS) {
+    /** Delete tasks that have zero events and are older than minAgeS seconds. Returns IDs deleted. */
+    deleteEmptyTasks(minAgeS) {
         const empties = this.db
             .prepare(`
-      SELECT s.id FROM sessions s
-      LEFT JOIN events e ON e.session_id = s.id
+      SELECT s.id, a.agent_session_id FROM tasks s
+      JOIN agent_sessions a ON a.task_id = s.id
+      LEFT JOIN events e ON e.task_id = s.id
       WHERE e.id IS NULL
+        AND s.id != ?
+        AND a.agent_key = ?
+        AND s.deleted_at IS NULL
         AND strftime('%s', 'now') - strftime('%s', s.created_at) >= ?
     `)
-            .all(minAgeS);
+            .all(ROOT_TASK_ID, this.agentKey, minAgeS);
         if (empties.length === 0)
             return [];
-        const del = this.db.prepare("DELETE FROM sessions WHERE id = ?");
-        for (const r of empties)
+        const del = this.db.prepare("DELETE FROM tasks WHERE id = ?");
+        const removed = [];
+        for (const r of empties) {
+            // A junk task may still be someone's parent; keep the children by
+            // re-parenting them under Root instead of deleting them.
+            this.reparentChildrenToRoot(r.id);
+            this.failOutstandingDeliveriesForDeletedTask(r.id);
             del.run(r.id);
-        return empties.map((r) => r.id);
+            removed.push({ id: r.id, agentSessionId: r.agent_session_id });
+        }
+        return removed;
     }
-    updateSessionTitle(id, title) {
+    updateTaskTitle(id, title) {
+        this.db.prepare("UPDATE tasks SET title = ? WHERE id = ?").run(title, id);
+    }
+    updateTaskWorkflowStatus(id, status) {
         this.db
-            .prepare("UPDATE sessions SET title = ? WHERE id = ?")
-            .run(title, id);
+            .prepare("UPDATE tasks SET workflow_status = ? WHERE id = ?")
+            .run(status, id);
     }
-    updateSessionLastActive(id) {
+    updateTaskLastActive(id) {
         this.db
-            .prepare("UPDATE sessions SET last_active_at = strftime('%Y-%m-%d %H:%M:%f', 'now') WHERE id = ?")
+            .prepare("UPDATE tasks SET last_active_at = strftime('%Y-%m-%d %H:%M:%f', 'now') WHERE id = ?")
             .run(id);
     }
-    /** Update a config option value (model, mode, reasoning_effort) for a session. */
-    updateSessionConfig(id, configId, value) {
+    /** Return the hidden summary waiting to be prepended to the next prompt. */
+    getPendingCompactSummary(id) {
+        const row = this.db
+            .prepare("SELECT pending_compact_summary FROM tasks WHERE id = ?")
+            .get(id);
+        return row?.pending_compact_summary ?? null;
+    }
+    /**
+     * Persist the visible assistant summary and its hidden pending copy together.
+     * The latter is consumed only when the next real prompt is accepted.
+     */
+    saveCompactSummary(taskId, summary) {
+        return this.db.transaction(() => {
+            const seq = this.db
+                .prepare("SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM events WHERE task_id = ?")
+                .get(taskId).next;
+            this.db
+                .prepare("INSERT INTO events (task_id, seq, type, data, from_ref) VALUES (?, ?, ?, ?, ?)")
+                .run(taskId, seq, "assistant_message", JSON.stringify({ text: summary }), "agent");
+            this.db
+                .prepare("UPDATE tasks SET pending_compact_summary = ? WHERE id = ?")
+                .run(summary, taskId);
+            return this.db
+                .prepare("SELECT * FROM events WHERE task_id = ? AND seq = ?")
+                .get(taskId, seq);
+        })();
+    }
+    /** Clear a pending summary, optionally only when it is still the expected value. */
+    clearPendingCompactSummary(id, expected) {
+        const result = expected === undefined
+            ? this.db
+                .prepare("UPDATE tasks SET pending_compact_summary = NULL WHERE id = ?")
+                .run(id)
+            : this.db
+                .prepare("UPDATE tasks SET pending_compact_summary = NULL WHERE id = ? AND pending_compact_summary = ?")
+                .run(id, expected);
+        return result.changes > 0;
+    }
+    /** Update a config option value (model, mode, reasoning_effort) for a task. */
+    updateTaskConfig(id, configId, value) {
         const column = {
             model: "model",
             mode: "mode",
             reasoning_effort: "reasoning_effort",
+            thought_level: "reasoning_effort",
         }[configId];
         if (!column)
             return;
         this.db
-            .prepare(`UPDATE sessions SET ${column} = ? WHERE id = ?`)
+            .prepare(`UPDATE tasks SET ${column} = ? WHERE id = ?`)
             .run(value, id);
     }
-    saveEvent(sessionId, type, data = {}, opts) {
+    saveEvent(taskId, type, data = {}, opts) {
         const seq = this.db
-            .prepare("SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM events WHERE session_id = ?")
-            .get(sessionId).next;
+            .prepare("SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM events WHERE task_id = ?")
+            .get(taskId).next;
         // Origin marker is required. Every writer must pass an explicit value;
         // missing/empty fails loudly so a forgotten retrofit can't silently
         // mis-bucket a row in production. Valid values:
         //   'user' | 'system' | 'agent' | 'msg:<id>'.
         const fromRef = opts?.from_ref;
         if (!fromRef) {
-            throw new Error(`saveEvent: from_ref is required (type=${type} session=${sessionId.slice(0, 8)}) — pass { from_ref: 'user' | 'system' | 'agent' | 'msg:<id>' }`);
+            throw new Error(`saveEvent: from_ref is required (type=${type} task=${taskId.slice(0, 8)}) — pass { from_ref: 'user' | 'system' | 'agent' | 'msg:<id>' }`);
         }
         this.db
-            .prepare("INSERT INTO events (session_id, seq, type, data, from_ref) VALUES (?, ?, ?, ?, ?)")
-            .run(sessionId, seq, type, JSON.stringify(data), fromRef);
+            .prepare("INSERT INTO events (task_id, seq, type, data, from_ref) VALUES (?, ?, ?, ?, ?)")
+            .run(taskId, seq, type, JSON.stringify(data), fromRef);
         return this.db
-            .prepare("SELECT * FROM events WHERE session_id = ? AND seq = ?")
-            .get(sessionId, seq);
+            .prepare("SELECT * FROM events WHERE task_id = ? AND seq = ?")
+            .get(taskId, seq);
     }
-    getEvents(sessionId, opts) {
+    getEvent(taskId, seq) {
+        return this.db
+            .prepare("SELECT * FROM events WHERE task_id = ? AND seq = ?")
+            .get(taskId, seq);
+    }
+    getEvents(taskId, opts) {
         const hasLimit = opts?.limit != null && opts.limit > 0;
-        const conditions = ["session_id = ?"];
-        const params = [sessionId];
+        const conditions = ["task_id = ?"];
+        const params = [taskId];
         if (opts?.afterSeq != null) {
             conditions.push("seq > ?");
             params.push(opts.afterSeq);
@@ -408,6 +910,11 @@ export class Store {
         if (opts?.excludeThinking) {
             conditions.push("type != 'thinking'");
         }
+        if (opts?.text !== undefined) {
+            conditions.push("data LIKE ? ESCAPE '\\'");
+            const escaped = opts.text.replace(/[\\%_]/g, (char) => `\\${char}`);
+            params.push(`%${escaped}%`);
+        }
         const where = conditions.join(" AND ");
         if (hasLimit) {
             // Fetch the last N matching rows: subquery orders DESC with LIMIT,
@@ -420,34 +927,37 @@ export class Store {
             .prepare(`SELECT * FROM events WHERE ${where} ORDER BY seq`)
             .all(...params);
     }
-    getEventCount(sessionId, opts) {
-        let query = "SELECT COUNT(*) as count FROM events WHERE session_id = ?";
-        const params = [sessionId];
+    getEventCount(taskId, opts) {
+        let query = "SELECT COUNT(*) as count FROM events WHERE task_id = ?";
+        const params = [taskId];
         if (opts?.excludeThinking) {
             query += " AND type != 'thinking'";
         }
         return this.db.prepare(query).get(...params).count;
     }
-    /** Highest seq of any stored event for this session (0 when empty). */
-    getLastEventSeq(sessionId) {
+    /** Highest seq of any stored event for this task (0 when empty). */
+    getLastEventSeq(taskId) {
         const row = this.db
-            .prepare("SELECT COALESCE(MAX(seq), 0) AS seq FROM events WHERE session_id = ?")
-            .get(sessionId);
+            .prepare("SELECT COALESCE(MAX(seq), 0) AS seq FROM events WHERE task_id = ?")
+            .get(taskId);
         return row.seq;
     }
-    /** Check if the most recent agent turn was interrupted (user_message without a following prompt_done). */
-    hasInterruptedTurn(sessionId) {
+    /** Check if the most recent agent turn lacks a completion or error terminal event. */
+    hasInterruptedTurn(taskId) {
         const row = this.db
             .prepare(`
       SELECT 1 FROM events
-      WHERE session_id = ? AND type = 'user_message'
+      WHERE task_id = ? AND type = 'user_message'
         AND seq > COALESCE(
-          (SELECT MAX(seq) FROM events WHERE session_id = ? AND type = 'prompt_done'),
+          (
+            SELECT MAX(seq) FROM events
+            WHERE task_id = ? AND type IN ('prompt_done', 'error')
+          ),
           0
         )
       LIMIT 1
     `)
-            .get(sessionId, sessionId);
+            .get(taskId, taskId);
         return Boolean(row);
     }
     // --- Push subscriptions ---
@@ -496,30 +1006,34 @@ export class Store {
     deleteRecentPath(cwd) {
         this.db.prepare("DELETE FROM recent_paths WHERE cwd = ?").run(cwd);
     }
-    // ===== messages (pending unbound notifications) =====
+    // ===== inbox messages (pending unbound notifications) =====
     createMessage(input) {
         this.db
-            .prepare(`INSERT INTO messages
+            .prepare(`INSERT INTO inbox_messages
          (id, from_ref, from_label, to_ref, deliver, dedup_key, title, body, cwd, created_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
             .run(input.id, input.from_ref, input.from_label, input.to_ref, input.deliver, input.dedup_key, input.title, input.body, input.cwd, input.created_at);
     }
     getMessage(id) {
-        return this.db.prepare("SELECT * FROM messages WHERE id = ?").get(id);
+        return this.db
+            .prepare("SELECT * FROM inbox_messages WHERE id = ?")
+            .get(id);
     }
     listUnprocessed() {
         return this.db
-            .prepare("SELECT * FROM messages ORDER BY created_at DESC")
+            .prepare("SELECT * FROM inbox_messages ORDER BY created_at DESC")
             .all();
     }
     countUnprocessed() {
         const row = this.db
-            .prepare("SELECT COUNT(*) AS count FROM messages")
+            .prepare("SELECT COUNT(*) AS count FROM inbox_messages")
             .get();
         return row.count;
     }
     deleteMessage(id) {
-        const info = this.db.prepare("DELETE FROM messages WHERE id = ?").run(id);
+        const info = this.db
+            .prepare("DELETE FROM inbox_messages WHERE id = ?")
+            .run(id);
         return info.changes;
     }
     /**
@@ -528,7 +1042,7 @@ export class Store {
      */
     deleteOlderThan(thresholdMs) {
         const info = this.db
-            .prepare("DELETE FROM messages WHERE created_at < ?")
+            .prepare("DELETE FROM inbox_messages WHERE created_at < ?")
             .run(thresholdMs);
         return info.changes;
     }
@@ -537,25 +1051,25 @@ export class Store {
         if (!dedup_key)
             return undefined;
         return this.db
-            .prepare("SELECT * FROM messages WHERE to_ref = ? AND dedup_key = ? LIMIT 1")
+            .prepare("SELECT * FROM inbox_messages WHERE to_ref = ? AND dedup_key = ? LIMIT 1")
             .get(to_ref, dedup_key);
     }
     /**
-     * Atomically move a pending message into an existing session. Session
+     * Atomically move a pending message into an existing task. Task
      * lifecycle belongs to SessionManager because ACP creation is asynchronous
      * and cannot participate in this SQLite transaction.
      */
-    consumeMessageTx(messageId, sessionId) {
-        const existing = this.findConsumedMessageSession(messageId);
+    consumeMessageTx(messageId, taskId) {
+        const existing = this.findConsumedMessageTask(messageId);
         if (existing) {
-            return { sessionId: existing, alreadyConsumed: true };
+            return { taskId: existing, alreadyConsumed: true };
         }
         const row = this.getMessage(messageId);
         if (!row) {
             throw new MessageNotFoundError(messageId);
         }
         const tx = this.db.transaction(() => {
-            this.saveEvent(sessionId, "message", {
+            this.saveEvent(taskId, "message", {
                 message_id: row.id,
                 from_ref: row.from_ref,
                 from_label: row.from_label,
@@ -564,33 +1078,225 @@ export class Store {
                 cwd: row.cwd,
             }, { from_ref: row.from_ref });
             const del = this.db
-                .prepare("DELETE FROM messages WHERE id = ?")
+                .prepare("DELETE FROM inbox_messages WHERE id = ?")
                 .run(messageId);
             if (del.changes === 0) {
                 throw new MessageNotFoundError(messageId);
             }
         });
         tx();
-        return { sessionId, alreadyConsumed: false };
+        return { taskId, alreadyConsumed: false };
     }
-    findConsumedMessageSession(messageId) {
+    findConsumedMessageTask(messageId) {
         const row = this.db
-            .prepare(`SELECT session_id FROM events
+            .prepare(`SELECT task_id FROM events
          WHERE type = 'message'
            AND json_extract(data, '$.message_id') = ?
          LIMIT 1`)
             .get(messageId);
-        return row?.session_id;
+        return row?.task_id;
+    }
+    // ===== collaboration messages =====
+    requireLiveTask(taskId) {
+        const task = this.getTaskIncludingDeleted(taskId);
+        if (task?.deleted_at !== null) {
+            throw new Error(`Live task not found: ${taskId}`);
+        }
+        return task;
+    }
+    lowestCommonAncestor(sourceTaskId, targetTaskId) {
+        const sourceLineage = this.getTaskLineage(sourceTaskId);
+        const targetLineage = this.getTaskLineage(targetTaskId);
+        if (!sourceLineage || !targetLineage) {
+            throw new Error("Cannot determine collaboration task lineage");
+        }
+        const sourceAncestors = new Set(sourceLineage);
+        for (let index = targetLineage.length - 1; index >= 0; index--) {
+            const taskId = targetLineage[index];
+            if (sourceAncestors.has(taskId))
+                return taskId;
+        }
+        throw new Error("Collaboration tasks have no common ancestor");
+    }
+    /**
+     * Persist one cross-task fact, its task-timeline projections, and the sole
+     * target Delivery in one SQLite transaction. Delivery mechanics live above
+     * this Store API; this method never resolves paths or applies reachability
+     * policy.
+     */
+    createCollaborationMessage(input) {
+        return this.db.transaction(() => this.createCollaborationMessageInTransaction(input))();
+    }
+    createCollaborationMessageInTransaction(input) {
+        const createdAt = input.createdAt ?? Date.now();
+        if (input.sourceTaskId === input.directTargetTaskId) {
+            throw new Error("Collaboration source and target must differ");
+        }
+        this.requireLiveTask(input.sourceTaskId);
+        this.requireLiveTask(input.directTargetTaskId);
+        const lcaTaskId = this.lowestCommonAncestor(input.sourceTaskId, input.directTargetTaskId);
+        this.db
+            .prepare(`INSERT INTO messages
+         (id, source_task_id, direct_target_task_id, source_actor, body, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`)
+            .run(input.id, input.sourceTaskId, input.directTargetTaskId, input.sourceActor, input.body, createdAt);
+        const insertProjection = this.db.prepare(`INSERT INTO message_projections (message_id, task_id, role, created_at)
+       VALUES (?, ?, ?, ?)`);
+        insertProjection.run(input.id, input.sourceTaskId, "source", createdAt);
+        insertProjection.run(input.id, input.directTargetTaskId, "target", createdAt);
+        if (lcaTaskId !== input.sourceTaskId &&
+            lcaTaskId !== input.directTargetTaskId) {
+            insertProjection.run(input.id, lcaTaskId, "supervisor", createdAt);
+        }
+        const sourceLabel = this.getTask(input.sourceTaskId)?.title ?? input.sourceTaskId.slice(0, 8);
+        const targetLabel = this.getTask(input.directTargetTaskId)?.title ??
+            input.directTargetTaskId.slice(0, 8);
+        const collaborationTitle = `${formatTaskReference(sourceLabel)} sent ${formatTaskReference(targetLabel)}`;
+        for (const projection of this.listCollaborationProjections(input.id)) {
+            this.saveEvent(projection.task_id, "system_message", {
+                kind: "collaboration",
+                messageId: input.id,
+                sourceTaskId: input.sourceTaskId,
+                sourceLabel,
+                targetTaskId: input.directTargetTaskId,
+                targetLabel,
+                role: projection.role,
+                title: collaborationTitle,
+                body: input.body,
+            }, { from_ref: `msg:${input.id}` });
+        }
+        this.db
+            .prepare(`INSERT INTO deliveries
+         (id, message_id, recipient_task_id, idempotency_key, status, queued_at)
+         VALUES (?, ?, ?, ?, 'queued', ?)`)
+            .run(input.deliveryId, input.id, input.directTargetTaskId, `${input.id}:${input.directTargetTaskId}`, createdAt);
+        return {
+            message: this.getCollaborationMessage(input.id),
+            delivery: this.getCollaborationDelivery(input.deliveryId),
+        };
+    }
+    /** Atomically record an Agent workflow update and its parent handoff. */
+    recordAgentWorkflowUpdate(taskId, status, body) {
+        return this.db.transaction(() => {
+            const task = this.requireLiveTask(taskId);
+            this.db
+                .prepare("UPDATE tasks SET workflow_status = ? WHERE id = ?")
+                .run(status, taskId);
+            this.saveEvent(taskId, "task_update", { status, body }, { from_ref: "agent" });
+            if (!task.parent_id) {
+                return { parentTaskId: null, collaborationMessageId: null };
+            }
+            const collaborationMessageId = randomUUID();
+            this.createCollaborationMessageInTransaction({
+                id: collaborationMessageId,
+                deliveryId: randomUUID(),
+                sourceTaskId: taskId,
+                directTargetTaskId: task.parent_id,
+                sourceActor: "agent",
+                body: `Task status: ${status}\n${body}`,
+            });
+            return {
+                parentTaskId: task.parent_id,
+                collaborationMessageId,
+            };
+        })();
+    }
+    getCollaborationMessage(id) {
+        return this.db.prepare("SELECT * FROM messages WHERE id = ?").get(id);
+    }
+    listCollaborationProjections(messageId) {
+        return this.db
+            .prepare(`SELECT task_id, role FROM message_projections
+         WHERE message_id = ?
+         ORDER BY CASE role
+           WHEN 'source' THEN 0
+           WHEN 'target' THEN 1
+           ELSE 2
+         END, task_id`)
+            .all(messageId);
+    }
+    getCollaborationDelivery(id) {
+        return this.db.prepare("SELECT * FROM deliveries WHERE id = ?").get(id);
+    }
+    /** Read-only queued count; lets a caller skip busy-turn churn entirely. */
+    countQueuedDeliveries(recipientTaskId) {
+        const row = this.db
+            .prepare("SELECT COUNT(*) AS count FROM deliveries WHERE recipient_task_id = ? AND status = 'queued'")
+            .get(recipientTaskId);
+        return row.count;
+    }
+    /** Atomically claim every currently queued Delivery for one target task. */
+    claimQueuedDeliveries(recipientTaskId) {
+        const claimedAt = Date.now();
+        return this.db.transaction(() => {
+            const ids = this.db
+                .prepare(`SELECT id FROM deliveries
+           WHERE recipient_task_id = ? AND status = 'queued'
+           ORDER BY queued_at, id`)
+                .all(recipientTaskId);
+            const claim = this.db.prepare(`UPDATE deliveries
+         SET status = 'draining', claimed_at = ?
+         WHERE id = ? AND status = 'queued'`);
+            const claimed = [];
+            for (const { id } of ids) {
+                if (claim.run(claimedAt, id).changes !== 1)
+                    continue;
+                const delivery = this.getCollaborationDelivery(id);
+                if (delivery)
+                    claimed.push(delivery);
+            }
+            return claimed;
+        })();
+    }
+    markCollaborationDeliveriesDelivered(ids, deliveredAt = Date.now()) {
+        const mark = this.db.prepare(`UPDATE deliveries
+       SET status = 'delivered', delivered_at = ?, failure_reason = NULL, failed_at = NULL
+       WHERE id = ? AND status = 'draining'`);
+        const tx = this.db.transaction(() => {
+            for (const id of ids)
+                mark.run(deliveredAt, id);
+        });
+        tx();
+    }
+    failCollaborationDeliveries(ids, failureReason, failedAt = Date.now()) {
+        const fail = this.db.prepare(`UPDATE deliveries
+       SET status = 'failed', failed_at = ?, failure_reason = ?
+       WHERE id = ? AND status = 'draining'`);
+        const tx = this.db.transaction(() => {
+            for (const id of ids)
+                fail.run(failedAt, failureReason, id);
+        });
+        tx();
+    }
+    failOutstandingDeliveriesForTaskClear(taskId) {
+        const failedAt = Date.now();
+        this.db
+            .prepare(`UPDATE deliveries
+         SET status = 'failed', failed_at = ?, failure_reason =
+           CASE status
+             WHEN 'queued' THEN 'cleared_before_delivery'
+             ELSE 'cleared_during_delivery'
+           END
+         WHERE recipient_task_id = ? AND status IN ('queued', 'draining')`)
+            .run(failedAt, taskId);
+    }
+    /** Preserve the fact while recording that a deleted target cannot receive it. */
+    failOutstandingDeliveriesForDeletedTask(taskId) {
+        this.db
+            .prepare(`UPDATE deliveries
+         SET status = 'failed', failed_at = ?, failure_reason = 'target_deleted'
+         WHERE recipient_task_id = ? AND status IN ('queued', 'draining')`)
+            .run(Date.now(), taskId);
     }
     // --- client-server-split M2: client_ops idempotency ---
     /**
-     * Look up a previously-cached response for (sessionId, clientOpId).
+     * Look up a previously-cached response for (taskId, clientOpId).
      * Returns the parsed result or null if no cached entry exists.
      */
-    getClientOp(sessionId, clientOpId) {
+    getClientOp(taskId, clientOpId) {
         const row = this.db
-            .prepare("SELECT result_json FROM client_ops WHERE session_id = ? AND client_op_id = ?")
-            .get(sessionId, clientOpId);
+            .prepare("SELECT result_json FROM client_ops WHERE task_id = ? AND client_op_id = ?")
+            .get(taskId, clientOpId);
         if (!row)
             return null;
         try {
@@ -601,13 +1307,13 @@ export class Store {
         }
     }
     /**
-     * Cache a successful response for (sessionId, clientOpId). Uses
+     * Cache a successful response for (taskId, clientOpId). Uses
      * INSERT OR IGNORE so a concurrent winner is preserved.
      */
-    saveClientOp(sessionId, clientOpId, result) {
+    saveClientOp(taskId, clientOpId, result) {
         this.db
-            .prepare("INSERT OR IGNORE INTO client_ops (session_id, client_op_id, result_json) VALUES (?, ?, ?)")
-            .run(sessionId, clientOpId, JSON.stringify(result));
+            .prepare("INSERT OR IGNORE INTO client_ops (task_id, client_op_id, result_json) VALUES (?, ?, ?)")
+            .run(taskId, clientOpId, JSON.stringify(result));
     }
     /** Prune client_ops rows older than `maxAgeMs` (milliseconds). Returns rows deleted. */
     pruneClientOps(maxAgeMs) {
@@ -620,55 +1326,55 @@ export class Store {
     // ===== attachments (uploads-plan v2.6 §1.2) =====
     /**
      * Insert a new attachment row. upload_seq is computed as
-     * `COALESCE(MAX(events.seq), 0)` for the session at insert time. Callers
+     * `COALESCE(MAX(events.seq), 0)` for the task at insert time. Callers
      * must have already written the file under
-     * <data_dir>/sessions/<sid>/attachments/<id>.<ext> and resolved its
-     * realpath. The row is bound by FK CASCADE to its session.
+     * <data_dir>/tasks/<sid>/attachments/<id>.<ext> and resolved its
+     * realpath. The row is bound by FK CASCADE to its task.
      */
     insertAttachment(input) {
         const seqRow = this.db
-            .prepare("SELECT COALESCE(MAX(seq), 0) AS s FROM events WHERE session_id = ?")
-            .get(input.sessionId);
+            .prepare("SELECT COALESCE(MAX(seq), 0) AS s FROM events WHERE task_id = ?")
+            .get(input.taskId);
         const uploadSeq = seqRow.s;
         this.db
             .prepare(`INSERT INTO attachments
-           (id, session_id, kind, name, mime, size, realpath, upload_seq, width, height)
+           (id, task_id, kind, name, mime, size, realpath, upload_seq, width, height)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(input.id, input.sessionId, input.kind, input.name, input.mime, input.size, input.realpath, uploadSeq, input.width ?? null, input.height ?? null);
+            .run(input.id, input.taskId, input.kind, input.name, input.mime, input.size, input.realpath, uploadSeq, input.width ?? null, input.height ?? null);
         return this.db
             .prepare("SELECT * FROM attachments WHERE id = ?")
             .get(input.id);
     }
-    /** Look up an attachment row by (session_id, id). */
-    getAttachment(sessionId, id) {
+    /** Look up an attachment row by (task_id, id). */
+    getAttachment(taskId, id) {
         return this.db
-            .prepare("SELECT * FROM attachments WHERE session_id = ? AND id = ?")
-            .get(sessionId, id);
+            .prepare("SELECT * FROM attachments WHERE task_id = ? AND id = ?")
+            .get(taskId, id);
     }
     /**
      * For the permission interceptor: list all attachment realpaths for a
-     * session so we can compare against `toolCall.locations[].path` after
+     * task so we can compare against `toolCall.locations[].path` after
      * realpath-ing each side. The set is small (≤ a few hundred per
-     * session) so we hand back an in-memory array.
+     * task) so we hand back an in-memory array.
      */
-    listAttachmentRealpaths(sessionId) {
+    listAttachmentRealpaths(taskId) {
         const rows = this.db
-            .prepare("SELECT realpath FROM attachments WHERE session_id = ?")
-            .all(sessionId);
+            .prepare("SELECT realpath FROM attachments WHERE task_id = ?")
+            .all(taskId);
         return rows.map((r) => r.realpath);
     }
     /**
      * For the egress label-rewrite (CLAUDE.md "Attachment label egress
      * rewrite"): list each attachment's id, user-supplied name, and
-     * realpath for a session. Caller (session-manager label cache)
+     * realpath for a task. Caller (task-manager label cache)
      * derives the label string `<name> [#<id4>]`. Pure DB read; no
      * realpath syscalls (the stored realpath is already resolved at
      * upload time).
      */
-    listAttachmentLabels(sessionId) {
+    listAttachmentLabels(taskId) {
         const rows = this.db
-            .prepare("SELECT id, name, realpath FROM attachments WHERE session_id = ?")
-            .all(sessionId);
+            .prepare("SELECT id, name, realpath FROM attachments WHERE task_id = ?")
+            .all(taskId);
         return rows;
     }
     /**
@@ -676,10 +1382,10 @@ export class Store {
      * filename portion of its URL (`<id>.<ext>`). The id is the uuid prefix
      * of the file segment.
      */
-    getAttachmentByFile(sessionId, file) {
+    getAttachmentByFile(taskId, file) {
         const dot = file.indexOf(".");
         const id = dot === -1 ? file : file.slice(0, dot);
-        return this.getAttachment(sessionId, id);
+        return this.getAttachment(taskId, id);
     }
     close() {
         this.db.close();
@@ -691,22 +1397,22 @@ export class Store {
      * §4.3 R1-c2). Returns the inserted row.
      *
      * May throw SQLITE_CONSTRAINT_UNIQUE on shares_one_active_preview;
-     * callers handle via findActivePreviewBySession fallback (§4.3 R2-c2).
+     * callers handle via findActivePreviewByTask fallback (§4.3 R2-c2).
      */
     insertSharePreview(input) {
         this.db
-            .prepare(`INSERT INTO shares (token, session_id, share_snapshot_seq, ttl_hours, display_name, owner_label)
+            .prepare(`INSERT INTO shares (token, task_id, share_snapshot_seq, ttl_hours, display_name, owner_label)
        VALUES (?, ?, ?, ?, ?, ?)`)
-            .run(input.token, input.sessionId, input.snapshotSeq, input.ttlHours ?? null, input.displayName ?? null, input.ownerLabel ?? null);
+            .run(input.token, input.taskId, input.snapshotSeq, input.ttlHours ?? null, input.displayName ?? null, input.ownerLabel ?? null);
         return this.getShareByToken(input.token);
     }
-    /** SELECT the single un-activated preview for this session (partial unique). */
-    findActivePreviewBySession(sessionId) {
+    /** SELECT the single un-activated preview for this task (partial unique). */
+    findActivePreviewByTask(taskId) {
         return this.db
             .prepare(`SELECT * FROM shares
-       WHERE session_id = ? AND shared_at IS NULL
+       WHERE task_id = ? AND shared_at IS NULL
        ORDER BY created_at DESC LIMIT 1`)
-            .get(sessionId);
+            .get(taskId);
     }
     getShareByToken(token) {
         return this.db
@@ -761,8 +1467,8 @@ export class Store {
         return this.db
             .prepare(`SELECT
          s.token AS token,
-         s.session_id AS session_id,
-         sess.title AS session_title,
+         s.task_id AS task_id,
+         t.title AS task_title,
          s.shared_at AS shared_at,
          s.created_at AS created_at,
          s.display_name AS display_name,
@@ -771,9 +1477,11 @@ export class Store {
          s.ttl_hours AS ttl_hours,
          s.last_accessed_at AS last_accessed_at
        FROM shares s
-       LEFT JOIN sessions sess ON sess.id = s.session_id
+       JOIN agent_sessions a ON a.task_id = s.task_id
+       LEFT JOIN tasks t ON t.id = s.task_id
+       WHERE a.agent_key = ?
        ORDER BY s.created_at DESC`)
-            .all();
+            .all(this.agentKey);
     }
     /**
      * One-time write of last_accessed_at (share-plan §4.1 R2 ENG-6a +