@vellumai/assistant 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/plugins/defaults/memory/jobs/embed-pkb-file.test.ts

@@ -1,27 +1,15 @@
 import { beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
 
-mock.module("../../../../util/logger.js", () => ({
-  getLogger: () =>
-    new Proxy({} as Record<string, unknown>, {
-      get: () => () => {},
-    }),
-}));
-
 // Track calls to indexPkbFile so we can assert the handler forwards payload
 // fields correctly.
 const indexPkbFileCalls: Array<{
   pkbRoot: string;
   absPath: string;
-  memoryScopeId: string;
 }> = [];
 
 mock.module("../pkb/pkb-index.js", () => ({
-  indexPkbFile: async (
-    pkbRoot: string,
-    absPath: string,
-    memoryScopeId: string,
-  ) => {
-    indexPkbFileCalls.push({ pkbRoot, absPath, memoryScopeId });
+  indexPkbFile: async (pkbRoot: string, absPath: string) => {
+    indexPkbFileCalls.push({ pkbRoot, absPath });
   },
 }));
 
@@ -31,6 +19,14 @@ mock.module("../../../../config/loader.js", () => ({
   invalidateConfigCache: () => {},
 }));
 
+// Controls the enqueue gate: PKB index jobs are v1-only, so the enqueue
+// helper consults memory.v2.enabled.
+let v2Enabled = false;
+
+mock.module("../config.js", () => ({
+  getMemoryConfig: () => ({ v2: { enabled: v2Enabled } }),
+}));
+
 import { DEFAULT_CONFIG } from "../../../../config/defaults.js";
 import type { AssistantConfig } from "../../../../config/types.js";
 import { getMemoryDb } from "../../../../persistence/db-connection.js";
@@ -77,7 +73,6 @@ describe("embedPkbFileJob", () => {
       makeJob({
         pkbRoot: "/pkb/root",
         absPath: "/pkb/root/note.md",
-        memoryScopeId: "scope-123",
       }),
       TEST_CONFIG,
     );
@@ -86,32 +81,39 @@ describe("embedPkbFileJob", () => {
     expect(indexPkbFileCalls[0]).toEqual({
       pkbRoot: "/pkb/root",
       absPath: "/pkb/root/note.md",
-      memoryScopeId: "scope-123",
     });
   });
 
   test("skips when pkbRoot is missing", async () => {
     await embedPkbFileJob(
-      makeJob({ absPath: "/pkb/root/note.md", memoryScopeId: "scope-123" }),
+      makeJob({ absPath: "/pkb/root/note.md" }),
       TEST_CONFIG,
     );
     expect(indexPkbFileCalls).toHaveLength(0);
   });
 
   test("skips when absPath is missing", async () => {
-    await embedPkbFileJob(
-      makeJob({ pkbRoot: "/pkb/root", memoryScopeId: "scope-123" }),
-      TEST_CONFIG,
-    );
+    await embedPkbFileJob(makeJob({ pkbRoot: "/pkb/root" }), TEST_CONFIG);
     expect(indexPkbFileCalls).toHaveLength(0);
   });
 
-  test("skips when memoryScopeId is missing", async () => {
+  test("processes a legacy payload that still carries a memoryScopeId key", async () => {
+    // Rows enqueued before scope removal persist in the job queue with the
+    // extra key; the handler reads only pkbRoot/absPath and must not skip.
     await embedPkbFileJob(
-      makeJob({ pkbRoot: "/pkb/root", absPath: "/pkb/root/note.md" }),
+      makeJob({
+        pkbRoot: "/pkb/root",
+        absPath: "/pkb/root/note.md",
+        memoryScopeId: "legacy-scope",
+      }),
       TEST_CONFIG,
     );
-    expect(indexPkbFileCalls).toHaveLength(0);
+
+    expect(indexPkbFileCalls).toHaveLength(1);
+    expect(indexPkbFileCalls[0]).toEqual({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+    });
   });
 });
 
@@ -122,15 +124,29 @@ describe("enqueuePkbIndexJob", () => {
 
   beforeEach(() => {
     indexPkbFileCalls.length = 0;
+    v2Enabled = false;
     const db = getMemoryDb()!;
     db.delete(memoryJobs).run();
   });
 
+  test("does not enqueue when memory v2 is enabled", () => {
+    v2Enabled = true;
+
+    const id = enqueuePkbIndexJob({
+      pkbRoot: "/pkb/root",
+      absPath: "/pkb/root/note.md",
+    });
+
+    expect(id).toBe("");
+    expect(claimMemoryJobs({ slowLlm: 10, fast: 10, embed: 10 })).toHaveLength(
+      0,
+    );
+  });
+
   test("enqueues a pending embed_pkb_file job with payload", () => {
     const id = enqueuePkbIndexJob({
       pkbRoot: "/pkb/root",
       absPath: "/pkb/root/note.md",
-      memoryScopeId: "scope-abc",
     });
     expect(id).toBeTruthy();
 
@@ -142,7 +158,6 @@ describe("enqueuePkbIndexJob", () => {
     expect(job.payload).toEqual({
       pkbRoot: "/pkb/root",
       absPath: "/pkb/root/note.md",
-      memoryScopeId: "scope-abc",
     });
   });
 
@@ -150,7 +165,6 @@ describe("enqueuePkbIndexJob", () => {
     enqueuePkbIndexJob({
       pkbRoot: "/pkb/root",
       absPath: "/pkb/root/note.md",
-      memoryScopeId: "scope-rt",
     });
 
     const claimed = claimMemoryJobs({ slowLlm: 10, fast: 10, embed: 10 });
@@ -163,7 +177,6 @@ describe("enqueuePkbIndexJob", () => {
     expect(indexPkbFileCalls[0]).toEqual({
       pkbRoot: "/pkb/root",
       absPath: "/pkb/root/note.md",
-      memoryScopeId: "scope-rt",
     });
   });
 });

package/src/plugins/defaults/memory/jobs/embed-pkb-file.ts

@@ -5,6 +5,7 @@ import {
   isMemoryEnabled,
   type MemoryJob,
 } from "../../../../persistence/jobs-store.js";
+import { getMemoryConfig } from "../config.js";
 import { indexPkbFile } from "../pkb/pkb-index.js";
 
 /**
@@ -13,7 +14,6 @@ import { indexPkbFile } from "../pkb/pkb-index.js";
 export interface EmbedPkbFileJobInput {
   pkbRoot: string;
   absPath: string;
-  memoryScopeId: string;
 }
 
 /**
@@ -28,11 +28,10 @@ export async function embedPkbFileJob(
 ): Promise<void> {
   const pkbRoot = asString(job.payload.pkbRoot);
   const absPath = asString(job.payload.absPath);
-  const memoryScopeId = asString(job.payload.memoryScopeId);
-  if (!pkbRoot || !absPath || !memoryScopeId) return;
+  if (!pkbRoot || !absPath) return;
 
   try {
-    await indexPkbFile(pkbRoot, absPath, memoryScopeId);
+    await indexPkbFile(pkbRoot, absPath);
   } catch (error) {
     if (
       error !== null &&
@@ -48,12 +47,18 @@ export async function embedPkbFileJob(
 
 /**
  * Enqueue an `embed_pkb_file` job (async, fire-and-forget).
+ *
+ * PKB is the v1 storage layer; under v2 nothing reads the PKB index and the
+ * v1 Qdrant collection is not initialized, so processing the job would throw.
+ * Skipping the enqueue here covers every producer (file-write hook, remember,
+ * startup reconcile); a later switch back to v1 rebuilds the index via the
+ * startup reconcile.
  */
 export function enqueuePkbIndexJob(input: EmbedPkbFileJobInput): string {
   if (!isMemoryEnabled()) return "";
+  if (getMemoryConfig().v2.enabled) return "";
   return enqueueMemoryJob("embed_pkb_file", {
     pkbRoot: input.pkbRoot,
     absPath: input.absPath,
-    memoryScopeId: input.memoryScopeId,
   });
 }

package/src/plugins/defaults/memory/jobs-worker.ts

@@ -13,10 +13,14 @@ import {
   setMemoryCheckpoint,
 } from "../../../persistence/checkpoints.js";
 import {
+  type CleanupJobKind,
   getLastScheduledCleanupEnqueueMs,
   markScheduledCleanupEnqueued,
 } from "../../../persistence/cleanup-schedule-state.js";
-import { maybeRunDbMaintenance } from "../../../persistence/db-maintenance.js";
+import {
+  maybeRunDbMaintenance,
+  maybeRunPassiveWalCheckpoint,
+} from "../../../persistence/db-maintenance.js";
 import {
   EmbeddingBillingBlockError,
   extractHttpStatus,
@@ -49,22 +53,15 @@ import {
   SLOW_LLM_JOB_TYPES,
 } from "../../../persistence/jobs-store.js";
 import { spawnMemoryWorkerProcess } from "../../../persistence/worker-control.js";
-import { getLogger } from "../../../util/logger.js";
-import { getWorkspaceDir } from "../../../util/platform.js";
+import type { JobHandler } from "../../types.js";
+import { getLogger } from "./logging.js";
 import { sweepOrphanMemoryRetrospectiveConversations } from "./memory-retrospective-startup-cleanup.js";
+import { getWorkspaceDir } from "./paths.js";
 import { hasPkbBufferContent } from "./pkb-schedule.js";
 import { countBufferLines } from "./v2/consolidation-job.js";
 
 const log = getLogger("memory-jobs-worker");
 
-/**
- * A per-job-type handler. The owning feature (e.g. memory) registers handlers
- * via {@link registerJobHandler}; the worker dispatches each claimed job to its
- * registered handler. Decoupling registration from the worker keeps the queue
- * mechanics generic and free of feature-specific handler imports.
- */
-export type JobHandler = (job: MemoryJob, config: AssistantConfig) => unknown;
-
 const jobHandlers = new Map<string, JobHandler>();
 
 /**
@@ -131,6 +128,9 @@ const LEGACY_JOB_TYPES = new Set([
   "memory_v3_index_maintenance",
   "memory_v3_edge_learning",
   "memory_proc_distill",
+  // Retired analyze-conversation job type — pre-upgrade pending rows drop
+  // gracefully.
+  "conversation_analyze",
 ]);
 
 export const POLL_INTERVAL_MIN_MS = 1_500;
@@ -240,19 +240,36 @@ export function startInProcessMemoryJobsWorker(
     log.info({ recovered }, "Recovered stale running memory jobs");
   }
 
-  // After running-job recovery (so legitimate in-flight retries aren't
-  // swept), clean up orphan memory-retrospective background conversations
-  // left behind by daemon crashes mid-job. Best-effort — never block worker
-  // startup on cleanup failures.
+  // Restore each cleanup job's cadence from its persisted checkpoint so a
+  // restart resumes counting from the last enqueue instead of re-firing every
+  // job on boot. Runs after resetRunningJobsToPending (which has already
+  // touched the DB), so migrations are settled. Best-effort: on failure the
+  // throttle stays at 0 and jobs fire on the first tick (the pre-persistence
+  // behavior), which is a safe degradation.
   try {
-    sweepOrphanMemoryRetrospectiveConversations();
+    seedCleanupScheduleFromCheckpoints();
   } catch (err) {
     log.warn(
       { err },
-      "Memory-retrospective startup cleanup failed; continuing worker startup",
+      "Failed to seed cleanup schedule from checkpoints; jobs will fire on the first tick",
     );
   }
 
+  // After running-job recovery (so legitimate in-flight retries aren't
+  // swept), clean up orphan memory-retrospective background conversations
+  // left behind by daemon crashes mid-job. Best-effort and detached — worker
+  // startup never blocks on the sweep, and failures only log. Concurrent
+  // ticking is safe: the sweep reads the active-job set and the orphan
+  // candidates in one synchronous block after its awaited baseline loads, so
+  // a retrospective forked by a mid-sweep tick is protected by its
+  // pending/running job.
+  void sweepOrphanMemoryRetrospectiveConversations().catch((err: unknown) => {
+    log.warn(
+      { err },
+      "Memory-retrospective startup cleanup failed; continuing worker startup",
+    );
+  });
+
   let stopped = false;
   let tickRunning = false;
   let timer: ReturnType<typeof setTimeout>;
@@ -395,6 +412,7 @@ export async function runMemoryJobsOnce(
     maybeEnqueueGraphMaintenanceJobs(config);
     if (memoryEnabled) {
       await maybeRunDbMaintenance();
+      await maybeRunPassiveWalCheckpoint();
     }
     return 0;
   }
@@ -462,6 +480,7 @@ export async function runMemoryJobsOnce(
   }
   maybeEnqueueGraphMaintenanceJobs(config);
   await maybeRunDbMaintenance();
+  await maybeRunPassiveWalCheckpoint();
   return slowProcessed + fastProcessed + embedProcessed;
 }
 
@@ -657,11 +676,74 @@ async function processJob(
   throw new Error(`Unknown memory job type: ${rawType}`);
 }
 
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+const CLEANUP_JOB_KINDS: readonly CleanupJobKind[] = [
+  "conversations",
+  "llm_request_logs",
+  "tool_invocations",
+];
+
+const CLEANUP_ENQUEUE_CHECKPOINT_KEYS: Record<CleanupJobKind, string> = {
+  conversations: "cleanup:last_enqueue:conversations",
+  llm_request_logs: "cleanup:last_enqueue:llm_request_logs",
+  tool_invocations: "cleanup:last_enqueue:tool_invocations",
+};
+
+/**
+ * Seed the in-memory cleanup throttle from persisted checkpoints so each job's
+ * cadence survives a daemon restart. Without this the throttle would start at 0
+ * on every boot, re-firing every cleanup job immediately regardless of when it
+ * last ran — which for a long retention window (e.g. 30-day conversation
+ * pruning) turns a frequent restart cycle into a prune on every boot.
+ *
+ * A job with no checkpoint (never enqueued on this instance) keeps its default
+ * 0, so it fires once on the first tick and then persists its timestamp. On a
+ * fresh instance that first prune is a harmless no-op (nothing is old enough to
+ * delete yet); on an upgrade it clears whatever has already aged out.
+ *
+ * Must run after DB migrations settle — the worker startup path already
+ * satisfies this (it touches the DB before calling here).
+ */
+export function seedCleanupScheduleFromCheckpoints(): void {
+  for (const kind of CLEANUP_JOB_KINDS) {
+    const raw = getMemoryCheckpoint(CLEANUP_ENQUEUE_CHECKPOINT_KEYS[kind]);
+    if (raw === null) {
+      continue;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      markScheduledCleanupEnqueued(kind, parsed);
+    }
+  }
+}
+
 /**
- * Enqueue periodic cleanup jobs using config-driven retention windows.
- * Enqueue is deduped in jobs-store, so repeated calls remain safe.
+ * Record that a cleanup job for `kind` was just enqueued: advance the in-memory
+ * throttle and persist the timestamp so the cadence survives a restart. A
+ * config-driven throttle reset (ConfigWatcher) only clears the in-memory value;
+ * the next enqueue re-persists here, so the checkpoint self-heals on the tick
+ * after a retention change.
  */
-function maybeEnqueueScheduledCleanupJobs(
+function recordCleanupEnqueued(kind: CleanupJobKind, nowMs: number): void {
+  markScheduledCleanupEnqueued(kind, nowMs);
+  setMemoryCheckpoint(CLEANUP_ENQUEUE_CHECKPOINT_KEYS[kind], String(nowMs));
+}
+
+/**
+ * Enqueue periodic cleanup jobs, each on a cadence equal to its own retention
+ * window. A job that keeps data for N is re-enqueued at most once per N:
+ * pruning that retains LLM logs for 1h runs hourly, pruning that retains
+ * conversations for 30d runs every 30d. Each job's throttle is tracked
+ * independently in cleanup-schedule-state (and persisted via checkpoints so the
+ * cadence survives restarts), and enqueue is deduped in jobs-store, so repeated
+ * calls remain safe.
+ *
+ * Exported for tests; the worker calls it on every idle/drain tick.
+ *
+ * Returns true if at least one job was enqueued this call.
+ */
+export function maybeEnqueueScheduledCleanupJobs(
   config: AssistantConfig,
   nowMs = Date.now(),
 ): boolean {
@@ -669,38 +751,65 @@ function maybeEnqueueScheduledCleanupJobs(
   if (!cleanup.enabled) {
     return false;
   }
-  if (nowMs - getLastScheduledCleanupEnqueueMs() < cleanup.enqueueIntervalMs) {
-    return false;
+
+  // A job is due when at least its full retention window has elapsed since the
+  // last enqueue for that job. The throttle is seeded from a persisted
+  // checkpoint at startup and reset to 0 when ConfigWatcher observes a
+  // retention change, so a due job also fires promptly after a config change
+  // while an unchanged one resumes its cadence across restarts.
+  const isDue = (kind: CleanupJobKind, intervalMs: number): boolean =>
+    nowMs - getLastScheduledCleanupEnqueueMs(kind) >= intervalMs;
+
+  let enqueuedAny = false;
+
+  if (
+    cleanup.conversationRetentionDays > 0 &&
+    isDue("conversations", cleanup.conversationRetentionDays * MS_PER_DAY)
+  ) {
+    const jobId = enqueuePruneOldConversationsJob(
+      cleanup.conversationRetentionDays,
+    );
+    recordCleanupEnqueued("conversations", nowMs);
+    enqueuedAny = true;
+    log.debug(
+      { jobId, retentionDays: cleanup.conversationRetentionDays },
+      "Enqueued scheduled prune_old_conversations",
+    );
+  }
+
+  if (
+    cleanup.llmRequestLogRetentionMs !== null &&
+    isDue("llm_request_logs", cleanup.llmRequestLogRetentionMs)
+  ) {
+    const jobId = enqueuePruneOldLlmRequestLogsJob(
+      cleanup.llmRequestLogRetentionMs,
+    );
+    recordCleanupEnqueued("llm_request_logs", nowMs);
+    enqueuedAny = true;
+    log.debug(
+      { jobId, retentionMs: cleanup.llmRequestLogRetentionMs },
+      "Enqueued scheduled prune_old_llm_request_logs",
+    );
   }
 
-  const pruneConversationsJobId =
-    cleanup.conversationRetentionDays > 0
-      ? enqueuePruneOldConversationsJob(cleanup.conversationRetentionDays)
-      : null;
-  const pruneLlmRequestLogsJobId =
-    cleanup.llmRequestLogRetentionMs !== null
-      ? enqueuePruneOldLlmRequestLogsJob(cleanup.llmRequestLogRetentionMs)
-      : null;
   // Audit-log (tool_invocations) retention is configured separately under
-  // `auditLog.retentionDays`, but rides this same cleanup cadence for now.
-  const pruneToolInvocationsJobId =
-    config.auditLog.retentionDays > 0
-      ? enqueuePruneOldToolInvocationsJob(config.auditLog.retentionDays)
-      : null;
-  markScheduledCleanupEnqueued(nowMs);
-  log.debug(
-    {
-      pruneConversationsJobId,
-      pruneLlmRequestLogsJobId,
-      pruneToolInvocationsJobId,
-      enqueueIntervalMs: cleanup.enqueueIntervalMs,
-      conversationRetentionDays: cleanup.conversationRetentionDays,
-      llmRequestLogRetentionMs: cleanup.llmRequestLogRetentionMs,
-      auditLogRetentionDays: config.auditLog.retentionDays,
-    },
-    "Enqueued scheduled memory cleanup jobs",
-  );
-  return true;
+  // `auditLog.retentionDays`; its prune cadence follows that window.
+  if (
+    config.auditLog.retentionDays > 0 &&
+    isDue("tool_invocations", config.auditLog.retentionDays * MS_PER_DAY)
+  ) {
+    const jobId = enqueuePruneOldToolInvocationsJob(
+      config.auditLog.retentionDays,
+    );
+    recordCleanupEnqueued("tool_invocations", nowMs);
+    enqueuedAny = true;
+    log.debug(
+      { jobId, retentionDays: config.auditLog.retentionDays },
+      "Enqueued scheduled prune_old_tool_invocations",
+    );
+  }
+
+  return enqueuedAny;
 }
 
 // ── Graph maintenance scheduling ──────────────────────────────────
@@ -765,7 +874,9 @@ function isWithinPkbActiveHours(
   start: number | null,
   end: number | null,
 ): boolean {
-  if (start == null || end == null) return true;
+  if (start == null || end == null) {
+    return true;
+  }
   if (start <= end) {
     return hour >= start && hour < end;
   }

package/src/plugins/defaults/memory/logging.ts

@@ -0,0 +1,17 @@
+/**
+ * The memory plugin's single logging channel. Every module in this plugin
+ * obtains its logger here rather than importing host `util/logger` directly,
+ * so the host import below is the plugin's sole logging escape (tracked by
+ * `plugin-import-boundary-guard.test.ts`).
+ *
+ * A plain forward is deliberate: memory creates module-scoped loggers in
+ * files that also run inside the jobs worker and CLI processes, where no
+ * plugin bootstrap (and therefore no `InitContext.logger`) exists. Deriving
+ * from the host-provided plugin logger requires a per-process binding story
+ * first; centralizing the import here keeps that cutover a one-file change.
+ */
+import { getLogger as getHostLogger } from "../../../util/logger.js";
+
+export function getLogger(name: string) {
+  return getHostLogger(name);
+}

package/src/plugins/defaults/memory/memory-retrospective-accounting.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// Memory retrospective — kind-aware message accounting.
+// ---------------------------------------------------------------------------
+//
+// After a successful run, `finalizeSuccessfulRetrospective` persists
+// `lastProcessedMessageId` and THEN (flag-gated) appends the
+// `skill-authored-card` assistant message to the source conversation — so the
+// card always lands past the cursor the run just wrote. To the generic
+// `countMessagesAfter` / `getMessagesAfter` helpers that card is
+// indistinguishable from real conversation content: an otherwise-idle
+// conversation would wake another retrospective over the assistant's own card
+// and re-review its `_surfaceFallback` text.
+//
+// These wrappers exclude skill-card rows from retrospective accounting on
+// BOTH paths — the trigger check's message count (including its
+// zero-new-messages early-out) and the job's new-message slice — without
+// touching the generic persistence helpers' semantics for other callers.
+//
+// The cursor is never blindly advanced over a card: the job still takes its
+// cutoff from the last NON-card row of the filtered slice, so a real message
+// that lands between the cutoff snapshot and the card insert can never be
+// skipped. A trailing card simply stays past the cursor, invisible to
+// accounting; once newer real messages arrive it is copied into the next
+// run's fork as inert prefix context.
+
+import { and, eq, like } from "drizzle-orm";
+
+import {
+  countMessagesAfter,
+  getMessagesAfter,
+  type MessageRow,
+} from "../../../persistence/conversation-crud.js";
+import { getDb } from "../../../persistence/db-connection.js";
+import { messages } from "../../../persistence/schema/index.js";
+import { SKILL_CARD_MESSAGE_KIND } from "./memory-retrospective-constants.js";
+
+/** True when a message row's metadata carries the skill-card kind. */
+export function isSkillCardMessage(row: { metadata: string | null }): boolean {
+  if (!row.metadata) return false;
+  try {
+    const meta: unknown = JSON.parse(row.metadata);
+    return (
+      !!meta &&
+      typeof meta === "object" &&
+      (meta as Record<string, unknown>).kind === SKILL_CARD_MESSAGE_KIND
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `getMessagesAfter` minus skill-card rows. The retrospective job's
+ * new-message slice: a card-only tail yields an empty slice (the job's
+ * `no_new_messages` early return), and a mixed tail's cutoff lands on the
+ * last real message rather than the card.
+ */
+export function getRetrospectiveMessagesAfter(
+  conversationId: string,
+  afterMessageId: string | null,
+): MessageRow[] {
+  return getMessagesAfter(conversationId, afterMessageId).filter(
+    (row) => !isSkillCardMessage(row),
+  );
+}
+
+/**
+ * `countMessagesAfter` minus skill-card rows. Stays count-shaped — the
+ * trigger check runs after every agent turn and the generic count helper
+ * exists precisely so that path never loads message bodies — so the total
+ * comes from `countMessagesAfter` and the handful of card rows past the
+ * cursor are counted separately and subtracted.
+ */
+export function countRetrospectiveMessagesAfter(
+  conversationId: string,
+  afterMessageId: string | null,
+): number {
+  const total = countMessagesAfter(conversationId, afterMessageId);
+  if (total === 0) return 0;
+  const cardCount = countSkillCardMessagesAfter(conversationId, afterMessageId);
+  return Math.max(0, total - cardCount);
+}
+
+/**
+ * Count skill-card rows strictly after the `(createdAt, id)` cursor. A LIKE
+ * prefilter keeps the scan from loading every row's metadata (cards are rare
+ * — at most one per successful retrospective run); each candidate is then
+ * JSON-verified by {@link isSkillCardMessage} so an incidental substring
+ * match in unrelated metadata can never exclude a real message from
+ * accounting. The cursor comparison mirrors `countMessagesAfter`'s
+ * tie-breaker semantics, including the null/`""` "count everything" cases
+ * and the vanished-reference "no new work" case.
+ */
+function countSkillCardMessagesAfter(
+  conversationId: string,
+  afterMessageId: string | null,
+): number {
+  // The `""` sentinel (failure-only state rows) counts everything, matching
+  // `countMessagesAfter`.
+  const cursorId =
+    afterMessageId === null || afterMessageId === "" ? null : afterMessageId;
+  const db = getDb();
+  const candidates = db
+    .select({
+      id: messages.id,
+      createdAt: messages.createdAt,
+      metadata: messages.metadata,
+    })
+    .from(messages)
+    .where(
+      and(
+        eq(messages.conversationId, conversationId),
+        like(messages.metadata, `%"kind":"${SKILL_CARD_MESSAGE_KIND}"%`),
+      ),
+    )
+    .all();
+  if (candidates.length === 0) return 0;
+
+  let ref: { createdAt: number } | undefined;
+  if (cursorId !== null) {
+    ref = db
+      .select({ createdAt: messages.createdAt })
+      .from(messages)
+      .where(eq(messages.id, cursorId))
+      .get();
+    // Vanished reference: `countMessagesAfter` reported 0, so there is
+    // nothing to subtract from.
+    if (!ref) return 0;
+  }
+
+  let count = 0;
+  for (const row of candidates) {
+    if (!isSkillCardMessage(row)) continue;
+    if (cursorId !== null && ref) {
+      const after =
+        row.createdAt > ref.createdAt ||
+        (row.createdAt === ref.createdAt && row.id > cursorId);
+      if (!after) continue;
+    }
+    count++;
+  }
+  return count;
+}