@vellumai/assistant 0.11.4 → 0.11.5-dev.202608220019.a778cf0

package/src/permissions/confirmation-guardian-request.test.ts

@@ -1,7 +1,9 @@
 /**
- * Tests for the confirmation → guardian-request promotion, including the
- * in-flight race: a confirmation resolved while the fire-and-forget gateway
- * create is still pending must not strand a pending tool_approval row.
+ * Tests for the confirmation to guardian-request promotion, including the
+ * in-flight race (a confirmation resolved while the fire-and-forget gateway
+ * create is still pending must not strand a pending tool_approval row) and
+ * the deadline, which is derived from the approval-window resolver rather
+ * than restated as a constant.
  */
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
@@ -52,6 +54,15 @@ mock.module("../runtime/confirmation-request-guardian-bridge.js", () => ({
   },
 }));
 
+// Deliberately not 300_000, the resolver's default. A fixture on the default
+// passes whether the deadline is read from the resolver or restated as a
+// constant beside it; this value only matches if it is read.
+const APPROVAL_WINDOW_MS = 900_000;
+
+mock.module("../tools/tool-approval-handler.js", () => ({
+  resolveInlineGrantWaitMs: () => APPROVAL_WINDOW_MS,
+}));
+
 import { asConversation } from "../__tests__/helpers/mock-conversation.js";
 import type { AssistantEvent } from "../api/index.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
@@ -86,6 +97,20 @@ describe("createGuardianRequestForConfirmation", () => {
     expect(bridgeCalls).toHaveLength(1);
   });
 
+  test("takes the row deadline from the approval-window resolver", async () => {
+    const before = Date.now();
+    await createGuardianRequestForConfirmation(MSG, "conv-1");
+    const after = Date.now();
+
+    expect(createCalls).toHaveLength(1);
+    const expiresAt = createCalls[0].expiresAt as number;
+
+    // Bracketed against the clock either side of the call rather than compared
+    // to a single Date.now(), so the assertion cannot flake on a slow tick.
+    expect(expiresAt).toBeGreaterThanOrEqual(before + APPROVAL_WINDOW_MS);
+    expect(expiresAt).toBeLessThanOrEqual(after + APPROVAL_WINDOW_MS);
+  });
+
   test("expires the row and skips the bridge when the confirmation resolved mid-create", async () => {
     confirmationPending = false;
 

package/src/permissions/confirmation-guardian-request.ts

@@ -55,6 +55,7 @@ export async function createGuardianRequestForConfirmation(
       { summarizeToolInput },
       { DAEMON_INTERNAL_ASSISTANT_ID },
       { bridgeConfirmationRequestToGuardian },
+      { resolveInlineGrantWaitMs },
     ] = await Promise.all([
       import("../daemon/conversation-registry.js"),
       import("../channels/gateway-guardian-requests.js"),
@@ -62,6 +63,7 @@ export async function createGuardianRequestForConfirmation(
       import("../tools/tool-input-summary.js"),
       import("../runtime/assistant-scope.js"),
       import("../runtime/confirmation-request-guardian-bridge.js"),
+      import("../tools/tool-approval-handler.js"),
     ]);
 
     const conversation = findConversation(conversationId);
@@ -100,7 +102,9 @@ export async function createGuardianRequestForConfirmation(
       activityText: activityRaw ? redactSecrets(activityRaw) : undefined,
       executionTarget: msg.executionTarget,
       status: "pending",
-      expiresAt: Date.now() + 5 * 60 * 1000,
+      // The row stays decidable exactly as long as the prompt stays parked:
+      // one budget, so raising `timeouts.permissionTimeoutSec` moves both.
+      expiresAt: Date.now() + resolveInlineGrantWaitMs(),
     });
 
     // The prompt is actionable before this fire-and-forget create lands, so

package/src/persistence/conversation-crud.ts

@@ -50,6 +50,10 @@ import {
   isRetryableSqliteError,
   withSqliteRetry,
 } from "../util/sqlite-retry.js";
+import {
+  purgeAllWatchTimelines,
+  purgeWatchTimelineForConversation,
+} from "../watch/watch-timeline.js";
 import {
   deleteOrphanAttachments,
   linkAttachmentToMessage,
@@ -87,6 +91,7 @@ import {
   type ConversationCreateType,
   type ConversationOrigin,
   isHiddenMessageMetadata,
+  isSystemCardMetadata,
   PINNED_GROUP_ID,
   UNGROUPED_GROUP_ID,
 } from "./conversation-types.js";
@@ -190,6 +195,36 @@ function dedicatedTableExists(db: DrizzleDb, table: string): boolean {
  * keys on `conversation_id` regardless of event name, so this covers every
  * conversation-scoped pending event.
  */
+/**
+ * Remove a conversation's watch-session timeline: the narration, the screens,
+ * and the frames of them the entries carry.
+ *
+ * The rows are keyed by conversation id with no cascade behind them, so a
+ * delete that skipped them would keep pictures of the user's screen for a
+ * conversation they asked to remove. It runs after the row deletes, which is
+ * the order the watch store expects: once `conversations` no longer has the
+ * row, a later append is refused rather than left for a purge that has already
+ * been.
+ *
+ * Best-effort, like the rest of the post-transaction cleanup. The conversation
+ * row is already gone by this point, so throwing here would turn a completed
+ * delete into an error the caller cannot usefully retry. A swallowed failure
+ * is not the end of the story: `sweepOrphanedWatchTimelineEntries` runs from
+ * daemon startup and from database maintenance and deletes entries whose
+ * conversation no longer exists, so whatever this pass leaves behind is
+ * reclaimed on a later one.
+ */
+function purgeWatchTimelineForDeletedConversation(id: string): void {
+  try {
+    purgeWatchTimelineForConversation(id);
+  } catch (err) {
+    log.warn(
+      { err, conversationId: id },
+      "Failed to purge the watch timeline for a deleted conversation",
+    );
+  }
+}
+
 function deletePendingTelemetryEventsForConversation(id: string): void {
   const telemetry = getTelemetryDb({ createIfMissing: false });
   if (!telemetry || !dedicatedTableExists(telemetry, "telemetry_events")) {
@@ -259,6 +294,14 @@ const backgroundToolCompletionMetadataSchema = z.object({
 
 export const messageMetadataSchema = z
   .object({
+    /**
+     * Epoch ms the content actually happened, when that differs from when
+     * the row was written. Set wherever persistence lags the event: a queued
+     * turn draining, or channel history imported long after the fact.
+     * History serialization prefers it over `createdAt` for the display
+     * timestamp.
+     */
+    sentAt: z.number().optional(),
     userMessageChannel: channelIdSchema.optional(),
     assistantMessageChannel: channelIdSchema.optional(),
     userMessageInterface: interfaceIdSchema.optional(),
@@ -413,13 +456,15 @@ export {
 } from "./conversation-types.js";
 
 /**
- * `messageKind` value marking a daemon-authored system card — a pre-composed
- * status reply (the /compact, /clean, and summarize-up-to result cards) that
- * bypasses the agent loop. Cards render as standalone system notices, never
- * as the assistant persona speaking, and never merge into adjacent assistant
- * display turns.
+ * The system-card `messageKind` marker and its predicate live in the
+ * `conversation-types` leaf so a caller that only stamps or classifies the
+ * marker does not pull in this module's DB graph, and are re-exported here
+ * alongside the schema that carries them.
  */
-export const SYSTEM_CARD_MESSAGE_KIND = "system_card";
+export {
+  isSystemCardMetadata,
+  SYSTEM_CARD_MESSAGE_KIND,
+} from "./conversation-types.js";
 
 /**
  * `messageKind` value marking the synthetic assistant row the agent loop
@@ -431,18 +476,6 @@ export const SYSTEM_CARD_MESSAGE_KIND = "system_card";
  */
 export const PROVIDER_ERROR_MESSAGE_KIND = "provider_error";
 
-/**
- * Shared predicate for the system-card marker on assistant-message metadata
- * (see the `messageKind` field on {@link messageMetadataSchema}). One
- * definition so display merging, transcript rendering, and turn grouping
- * cannot drift.
- */
-export function isSystemCardMetadata(
-  metadata: Record<string, unknown> | null | undefined,
-): boolean {
-  return metadata?.messageKind === SYSTEM_CARD_MESSAGE_KIND;
-}
-
 /**
  * Shared predicate for the provider-error marker on assistant-message
  * metadata (see the `messageKind` field on {@link messageMetadataSchema}).
@@ -2110,6 +2143,8 @@ export function deleteConversation(id: string): DeletedMemoryIds {
     removeConversationDir(id, createdAtForDiskCleanup);
   }
 
+  purgeWatchTimelineForDeletedConversation(id);
+
   // Notify `conversation-deleted` hooks (e.g. the memory plugin failing its
   // still-pending jobs for this conversation). Fire-and-forget from this
   // synchronous primitive — the pipeline contains per-hook failures, and
@@ -2260,6 +2295,8 @@ export async function deleteConversationGently(
     removeConversationDir(id, createdAtForDiskCleanup);
   }
 
+  purgeWatchTimelineForDeletedConversation(id);
+
   // Notify `conversation-deleted` hooks — fire-and-forget, same contract as
   // the synchronous delete primitive.
   void runHook(HOOKS.CONVERSATION_DELETED, {
@@ -2467,7 +2504,7 @@ export function getMessages(conversationId: string): MessageRow[] {
  * offsets until the target is reached (capped at a reasonable maximum to bound
  * scan cost).
  */
-export function selectSlackMetaCandidateMetadata(
+export function selectProviderMetaCandidateMetadata(
   conversationId: string,
   limit: number,
   offset = 0,
@@ -2482,10 +2519,14 @@ export function selectSlackMetaCandidateMetadata(
         lineageFilter(conversationId),
         opts?.includeFlatLegacy
           ? or(
+              like(messages.metadata, '%"providerMeta"%'),
               like(messages.metadata, '%"slackMeta"%'),
               like(messages.metadata, '%"source":"slack"%'),
             )
-          : like(messages.metadata, '%"slackMeta"%'),
+          : or(
+              like(messages.metadata, '%"providerMeta"%'),
+              like(messages.metadata, '%"slackMeta"%'),
+            ),
       ),
     )
     .orderBy(asc(messages.createdAt))
@@ -3585,6 +3626,14 @@ export async function clearAll(): Promise<{
   // cascade; wipe them explicitly so labels/objectives don't survive (or
   // rehydrate after) a clear-all.
   await runOrThrow("DELETE FROM subagents");
+  // Watch-session timelines are conversation-keyed rows the cascade does not
+  // reach. They come after `conversations` so this statement is the last thing
+  // that needs to reach one: an append arriving from here on finds no
+  // conversation to key itself to and is refused, and an append that already
+  // ran is a row this deletes. The bulk deletes above run in a sqlite3
+  // subprocess, so the event loop is free while they work; this one is a
+  // synchronous in-process statement, which nothing can interleave with.
+  purgeAllWatchTimelines();
 
   // The memory feature's relocated conversation-keyed tables lost their main-DB
   // cascade. Signal the wipe through the hook rather than reaching into the

package/src/persistence/conversation-queries.ts

@@ -199,7 +199,8 @@ function surfacedVisibilitySql(alias = "conversations"): string {
  * explicitly surfaced. {@link standardListingVisibilitySql} already admits
  * such rows through its surfaced and custom-group arms, so a caller that
  * must distinguish "visible in the listing" from "user-facing foreground"
- * (unread counting) applies this on top.
+ * (unread counting, the section index, a `foregroundOnly` list read) applies
+ * this on top.
  *
  * The SQL twin of `isBackgroundConversation` in the web client's
  * `utils/conversation-predicates.ts`.
@@ -282,6 +283,16 @@ export interface ConversationListFilter {
    * the rows its attention surfaces need instead of scanning for them.
    */
   needsAttention?: true;
+  /**
+   * Restrict to user-facing foreground conversations: drop the automated
+   * background/scheduled rows the standard listing admits through its
+   * custom-group arm ({@link notBackgroundVisibilitySql}, the same predicate
+   * the unread count and the section index apply on top of visibility).
+   * Only `true` narrows; omit to keep every visible row. A client that
+   * needs the newest conversation a user can open can ask for it in one
+   * row instead of paging past runs it would skip.
+   */
+  foregroundOnly?: true;
 }
 
 export interface ConversationListQuery extends ConversationListFilter {
@@ -364,6 +375,7 @@ function conversationListWhere(filter: ConversationListFilter) {
     originChannel,
     groupId,
     needsAttention,
+    foregroundOnly,
   } = filter;
   return and(
     conversationTypeClause(conversationType),
@@ -371,6 +383,7 @@ function conversationListWhere(filter: ConversationListFilter) {
     originChannel ? originChannelClause(originChannel) : undefined,
     groupId ? groupIdClause(groupId) : undefined,
     ...(needsAttention ? unseenAttentionStateConditions() : []),
+    foregroundOnly ? sql.raw(notBackgroundVisibilitySql()) : undefined,
   );
 }
 

package/src/persistence/conversation-types.ts

@@ -135,6 +135,28 @@ export function isBackgroundEventMetadata(
   return typeof metadata?.backgroundEventSource === "string";
 }
 
+/**
+ * `messageKind` value marking a daemon-authored system card: a notice that
+ * bypasses the agent loop (the /compact, /clean, and summarize-up-to result
+ * cards, and plugin notices about what a turn did to the user's input). Cards
+ * render as standalone system notices, never as the assistant persona
+ * speaking, and never merge into adjacent assistant display turns.
+ *
+ * Lives in this leaf so a caller that only stamps or classifies the marker
+ * does not pull in `conversation-crud`'s DB graph.
+ */
+export const SYSTEM_CARD_MESSAGE_KIND = "system_card";
+
+/**
+ * Shared predicate for the system-card marker on assistant-message metadata,
+ * so display merging, transcript rendering, and turn grouping cannot drift.
+ */
+export function isSystemCardMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+): boolean {
+  return metadata?.messageKind === SYSTEM_CARD_MESSAGE_KIND;
+}
+
 /**
  * True when a role-`"user"` row is internal scaffolding rather than a person's
  * prompt: a daemon-injected run lifecycle notification (subagent

package/src/persistence/db-async-query.ts

@@ -216,6 +216,7 @@ async function runViaCli(
   // never an issue regardless of the statement complexity.
   const proc = Bun.spawn({
     cmd: [sqlite3Path, dbPath],
+    windowsHide: true,
     stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
@@ -396,7 +397,7 @@ export function spawnDetachedWalCheckpoint(): boolean {
         getDbPath(),
         `PRAGMA busy_timeout=${SQLITE_BUSY_TIMEOUT_MS}; PRAGMA wal_checkpoint(TRUNCATE);`,
       ],
-      { detached: true, stdio: "ignore" },
+      { detached: true, stdio: "ignore", windowsHide: true },
     );
     // A post-spawn failure can't be acted on — the daemon is exiting — but an
     // unlistened ChildProcess "error" event would throw as an uncaught

package/src/persistence/db-maintenance.ts

@@ -3,6 +3,7 @@ import { statSync } from "node:fs";
 import { getConfig } from "../config/loader.js";
 import { getLogger } from "../util/logger.js";
 import { getDbPath } from "../util/platform.js";
+import { sweepOrphanedWatchTimelineEntries } from "../watch/watch-timeline.js";
 import { pruneRuns } from "../workflows/journal-store.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
 import { getLastInteractiveUserMessageTimestamp } from "./conversation-crud.js";
@@ -81,6 +82,20 @@ async function runDbMaintenance(): Promise<void> {
     log.warn({ err }, "Workflow run pruning failed (non-fatal)");
   }
 
+  // Reclaim watch-timeline entries whose conversation is gone. Their purge runs
+  // after the conversation row is already deleted and cannot be retried by the
+  // caller, and nothing cascades into the table, so a failed purge or a crash
+  // between the two writes would otherwise keep screenshots of the user's
+  // screen indefinitely. Bounded per pass and best-effort inside the sweep,
+  // which reports zero rather than throwing, so it needs no guard here.
+  const sweptWatchEntries = sweepOrphanedWatchTimelineEntries();
+  if (sweptWatchEntries > 0) {
+    log.info(
+      { sweptWatchEntries },
+      "Swept watch timeline entries for deleted conversations",
+    );
+  }
+
   // Refresh the query planner's statistics (see PLANNER_OPTIMIZE_PRAGMA for
   // what the mask buys here). Routed through the async path to keep it off the
   // main thread when the sqlite3 CLI backend is available.

package/src/persistence/delivery-crud.ts

@@ -5,15 +5,15 @@
  * finding messages by source identifiers, and managing raw payload storage.
  */
 
-import { and, desc, eq, isNotNull, ne, or, sql } from "drizzle-orm";
+import { and, desc, eq, isNotNull, like, ne, or, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import type { ChannelId } from "../channels/types.js";
-import { readSlackMetadataFromMessageMetadata } from "../messaging/providers/slack/message-metadata.js";
+import { readProviderMetadata } from "../messaging/read-provider-metadata.js";
 import type { SlackInboundMessageMetadata } from "../runtime/http-types.js";
 import { parseJsonSafe } from "../util/json.js";
 import { isPlainObject } from "../util/object.js";
-import { selectSlackMetaCandidateMetadata } from "./conversation-crud.js";
+import { selectProviderMetaCandidateMetadata } from "./conversation-crud.js";
 import {
   getConversationByKey,
   getOrCreateConversation,
@@ -21,7 +21,12 @@ import {
 } from "./conversation-key-store.js";
 import type { NonScheduledConversationType } from "./conversation-types.js";
 import { getDb } from "./db-connection.js";
-import { channelInboundEvents, conversations } from "./schema.js";
+import {
+  channelInboundEvents,
+  conversationKeys,
+  conversations,
+  messages,
+} from "./schema.js";
 
 export interface InboundResult {
   accepted: boolean;
@@ -33,11 +38,26 @@ export interface InboundResult {
 export interface RecordInboundOptions {
   sourceMessageId?: string;
   sourceThreadId?: string;
+  /**
+   * Record the event against this conversation instead of resolving one from
+   * the address. For events that belong to a message rather than to a chat: a
+   * reaction lives in the conversation of the message it was attached to, and
+   * resolving from its own address would mint a second one.
+   */
+  conversationId?: string;
 }
 
 const SLACK_LEGACY_THREAD_EVIDENCE_BATCH_SIZE = 50;
 const SLACK_LEGACY_THREAD_EVIDENCE_MAX_SCAN = 500;
 
+/**
+ * Rows examined when locating a Slack message the assistant itself posted.
+ * Bounded on purpose: the scan runs on the inbound path while the gateway
+ * waits for its ack, and reactions land on recent messages, so a cap costs
+ * almost no recall and keeps the cost flat as the database grows.
+ */
+const SLACK_OUTBOUND_TS_MAX_SCAN = 400;
+
 /**
  * Channels where an inbound thread id scopes the conversation: a Slack thread
  * or a Telegram private-chat topic each maps to its own conversation. A
@@ -99,7 +119,7 @@ function legacySlackConversationHasThreadEvidence(
       SLACK_LEGACY_THREAD_EVIDENCE_BATCH_SIZE,
       remaining,
     );
-    const metadataRows = selectSlackMetaCandidateMetadata(
+    const metadataRows = selectProviderMetaCandidateMetadata(
       conversationId,
       batchLimit,
       offset,
@@ -110,12 +130,10 @@ function legacySlackConversationHasThreadEvidence(
       return false;
     }
     for (const metadata of metadataRows) {
-      const slackMeta = readSlackMetadataFromMessageMetadata(metadata, {
-        allowFlatLegacy: true,
-      });
+      const meta = readProviderMetadata(metadata, { allowFlatLegacy: true });
       if (
-        slackMeta?.channelId === externalChatId &&
-        slackMeta.threadTs === sourceThreadId
+        meta?.conversationExternalId === externalChatId &&
+        meta.threadId === sourceThreadId
       ) {
         return true;
       }
@@ -248,6 +266,93 @@ export function findInboundConversationId(
  * the conversation and tracks the reply. Both must key on the same three
  * fields for either to mean anything.
  */
+/**
+ * The inbound event already recorded for this address, if any. Read-only twin
+ * of the dedup check inside {@link recordInbound}, for callers that must know
+ * an event is a redelivery before doing work that recording would otherwise
+ * gate (routing a guardian decision, for one).
+ */
+export function findInboundEvent(
+  sourceChannel: string,
+  externalChatId: string,
+  externalMessageId: string,
+): { eventId: string; conversationId: string } | null {
+  const row = getDb()
+    .select({
+      id: channelInboundEvents.id,
+      conversationId: channelInboundEvents.conversationId,
+    })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.sourceChannel, sourceChannel),
+        eq(channelInboundEvents.externalChatId, externalChatId),
+        eq(channelInboundEvents.externalMessageId, externalMessageId),
+      ),
+    )
+    .get();
+  return row ? { eventId: row.id, conversationId: row.conversationId } : null;
+}
+
+/**
+ * The conversation holding the message with this provider id, found by reading
+ * the metadata the assistant's own posts carry.
+ *
+ * Reads through `readProviderMetadata`, so it matches any channel that
+ * describes its rows in the neutral shape as well as Slack's own envelope.
+ *
+ * `findMessageBySourceId` covers every message that arrived as an inbound
+ * event. It cannot see what the assistant posted, because an outbound reply
+ * opens no inbound event, so a reaction on the assistant's own message needs
+ * this. The search is confined to conversations already bound to the same
+ * Slack channel and to the most recent {@link SLACK_OUTBOUND_TS_MAX_SCAN}
+ * rows among them; beyond that it gives up and the caller drops the
+ * annotation, which is the same outcome as never finding it at all.
+ */
+export function findSlackConversationByMessageTs(
+  externalChatId: string,
+  channelTs: string,
+): string | null {
+  const db = getDb();
+  const keyPrefix = `${CONVERSATION_KEY_SCOPE}:slack:${externalChatId}`;
+  const rows = db
+    .select({
+      conversationId: messages.conversationId,
+      metadata: messages.metadata,
+    })
+    .from(messages)
+    .innerJoin(
+      conversationKeys,
+      eq(conversationKeys.conversationId, messages.conversationId),
+    )
+    .where(
+      and(
+        or(
+          eq(conversationKeys.conversationKey, keyPrefix),
+          like(conversationKeys.conversationKey, `${keyPrefix}:thread:%`),
+        ),
+        or(
+          like(messages.metadata, '%"providerMeta"%'),
+          like(messages.metadata, '%"slackMeta"%'),
+        ),
+      ),
+    )
+    .orderBy(desc(messages.createdAt))
+    .limit(SLACK_OUTBOUND_TS_MAX_SCAN)
+    .all();
+
+  for (const row of rows) {
+    const meta = readProviderMetadata(row.metadata, { allowFlatLegacy: true });
+    if (
+      meta?.conversationExternalId === externalChatId &&
+      meta.messageId === channelTs
+    ) {
+      return row.conversationId;
+    }
+  }
+  return null;
+}
+
 export function recordInbound(
   sourceChannel: string,
   externalChatId: string,
@@ -280,11 +385,13 @@ export function recordInbound(
     };
   }
 
-  const mapping = resolveInboundConversation(
-    sourceChannel,
-    externalChatId,
-    options?.sourceThreadId,
-  );
+  const mapping = options?.conversationId
+    ? { conversationId: options.conversationId }
+    : resolveInboundConversation(
+        sourceChannel,
+        externalChatId,
+        options?.sourceThreadId,
+      );
   const now = Date.now();
   const eventId = uuid();
 

package/src/persistence/embeddings/qdrant-manager.ts

@@ -154,6 +154,7 @@ export class QdrantManager {
 
     const proc = Bun.spawn({
       cmd: [spawnPath],
+      windowsHide: true,
       env: {
         ...process.env,
         QDRANT__SERVICE__HOST: this.host,

package/src/persistence/migrations/367-create-watch-timeline-entries.ts

@@ -0,0 +1,46 @@
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Creates `watch_timeline_entries`: the per-session record of what a watch
+ * session's user narrated and what was on their screen.
+ *
+ * The table is the timeline's only home. Entries live outside conversation
+ * message history, so nothing here participates in turn alternation or
+ * provider-facing sanitization, and only the retrospective's rendered summary
+ * reaches a model.
+ *
+ * `screenshot_attachment_id` holds the id of a row in `attachments`, so the
+ * pixels stay on disk behind the attachment store rather than in this table.
+ * Timeline rows and the screenshots they own are removed together by the
+ * watch store's purge.
+ *
+ * The two indexes cover the two access paths: reads are scoped to one session
+ * and ordered by offset, and purges are scoped to one conversation.
+ *
+ * Idempotent: `IF NOT EXISTS` on the table and both indexes.
+ */
+export function migrateCreateWatchTimelineEntries(db: DrizzleDb): void {
+  const raw = getSqliteFrom(db);
+
+  raw.exec(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS watch_timeline_entries (
+      id                       TEXT PRIMARY KEY,
+      session_id               TEXT NOT NULL,
+      conversation_id          TEXT NOT NULL,
+      at_ms                    INTEGER NOT NULL,
+      kind                     TEXT NOT NULL,
+      text                     TEXT NOT NULL,
+      ax_tree                  TEXT,
+      ax_diff                  TEXT,
+      screenshot_attachment_id TEXT,
+      created_at               INTEGER NOT NULL
+    )
+  `);
+
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_watch_timeline_entries_session ON watch_timeline_entries(session_id, at_ms)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_watch_timeline_entries_conversation ON watch_timeline_entries(conversation_id)`,
+  );
+}

package/src/persistence/migrations/368-watch-timeline-screenshot-blob.ts

@@ -0,0 +1,33 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+/**
+ * Move a watch timeline entry's screenshot into the row that owns it.
+ *
+ * `screenshot` holds the frame's JPEG bytes directly, so an entry is one row
+ * with one lifetime: a single `DELETE` takes the narration, the screen, and
+ * the pixels together, with nothing staged elsewhere to coordinate against.
+ * `screenshot_attachment_id`, the id of a separately staged file, goes with
+ * it.
+ *
+ * Idempotent: each `ALTER TABLE` is guarded by a column check, so a crash
+ * between the two leaves the next boot able to finish the job.
+ */
+export function migrateWatchTimelineScreenshotBlob(database: DrizzleDb): void {
+  if (!tableHasColumn(database, "watch_timeline_entries", "screenshot")) {
+    database.run(
+      /*sql*/ `ALTER TABLE watch_timeline_entries ADD COLUMN screenshot BLOB`,
+    );
+  }
+  if (
+    tableHasColumn(
+      database,
+      "watch_timeline_entries",
+      "screenshot_attachment_id",
+    )
+  ) {
+    database.run(
+      /*sql*/ `ALTER TABLE watch_timeline_entries DROP COLUMN screenshot_attachment_id`,
+    );
+  }
+}