trekoon 0.3.0 → 0.3.2

package/src/domain/tracker-domain.ts

@@ -32,10 +32,13 @@ import {
   type SubtaskRecord,
   type TaskTreeDetailed,
   type TaskRecord,
+  VALID_STATUSES,
+  VALID_TRANSITIONS,
+  type ValidStatus,
 } from "./types";
 
 const DEFAULT_STATUS = "todo";
-const DEPENDENCY_GATED_STATUSES = new Set<string>(["in_progress", "in-progress", "done"]);
+const DEPENDENCY_GATED_STATUSES = new Set<string>(["in_progress", "done"]);
 
 interface EpicRow {
   id: string;
@@ -48,10 +51,12 @@ interface EpicRow {
 
 interface TaskRow extends EpicRow {
   epic_id: string;
+  owner: string | null;
 }
 
 interface SubtaskRow extends EpicRow {
   task_id: string;
+  owner: string | null;
 }
 
 interface DependencyRow {
@@ -146,6 +151,45 @@ function normalizeSubtaskDescription(value: string | undefined): string {
   return value.trim();
 }
 
+function isValidStatus(status: string): status is ValidStatus {
+  return (VALID_STATUSES as readonly string[]).includes(status);
+}
+
+export function validateStatusTransition(fromStatus: string, toStatus: string, entityKind: string, entityId: string): void {
+  if (fromStatus === toStatus) {
+    return;
+  }
+
+  if (!isValidStatus(toStatus)) {
+    throw new DomainError({
+      code: "status_transition_invalid",
+      message: `invalid status '${toStatus}' for ${entityKind} ${entityId}; allowed statuses: ${VALID_STATUSES.join(", ")}`,
+      details: { entity: entityKind, id: entityId, fromStatus, toStatus, allowedStatuses: [...VALID_STATUSES] },
+    });
+  }
+
+  if (!isValidStatus(fromStatus)) {
+    // Legacy/custom status from pre-0.3.1 data; allow transition to any valid
+    // status so existing databases can migrate forward without manual fixups.
+    return;
+  }
+
+  const allowed = VALID_TRANSITIONS.get(fromStatus);
+  if (!allowed || !allowed.has(toStatus)) {
+    throw new DomainError({
+      code: "status_transition_invalid",
+      message: `cannot transition ${entityKind} ${entityId} from '${fromStatus}' to '${toStatus}'`,
+      details: {
+        entity: entityKind,
+        id: entityId,
+        fromStatus,
+        toStatus,
+        allowedTransitions: allowed ? [...allowed] : [],
+      },
+    });
+  }
+}
+
 function mapEpic(row: EpicRow): EpicRecord {
   return {
     id: row.id,
@@ -164,6 +208,7 @@ function mapTask(row: TaskRow): TaskRecord {
     title: row.title,
     description: row.description,
     status: row.status,
+    owner: row.owner ?? null,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -176,6 +221,7 @@ function mapSubtask(row: SubtaskRow): SubtaskRecord {
     title: row.title,
     description: row.description,
     status: row.status,
+    owner: row.owner ?? null,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -376,21 +422,21 @@ export class TrackerDomain {
       this.getEpicOrThrow(epicId);
       const rows = this.#db
         .query(
-          "SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks WHERE epic_id = ? ORDER BY created_at ASC, id ASC;",
+          "SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks WHERE epic_id = ? ORDER BY created_at ASC, id ASC;",
         )
         .all(epicId) as TaskRow[];
       return rows.map(mapTask);
     }
 
     const rows = this.#db
-      .query("SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks ORDER BY created_at ASC, id ASC;")
+      .query("SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks ORDER BY created_at ASC, id ASC;")
       .all() as TaskRow[];
     return rows.map(mapTask);
   }
 
   getTask(id: string): TaskRecord | null {
     const row = this.#db
-      .query("SELECT id, epic_id, title, description, status, created_at, updated_at FROM tasks WHERE id = ?;")
+      .query("SELECT id, epic_id, title, description, status, owner, created_at, updated_at FROM tasks WHERE id = ?;")
       .get(id) as TaskRow | null;
     return row ? mapTask(row) : null;
   }
@@ -410,19 +456,20 @@ export class TrackerDomain {
 
   updateTask(
     id: string,
-    input: { title?: string | undefined; description?: string | undefined; status?: string | undefined },
+    input: { title?: string | undefined; description?: string | undefined; status?: string | undefined; owner?: string | null | undefined },
   ): TaskRecord {
     const existing: TaskRecord = this.getTaskOrThrow(id);
     const nextTitle: string = input.title !== undefined ? assertNonEmpty("title", input.title) : existing.title;
     const nextDescription: string =
       input.description !== undefined ? assertNonEmpty("description", input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
+    const nextOwner: string | null = input.owner !== undefined ? input.owner : existing.owner;
     this.assertNoUnresolvedDependenciesForStatusTransition(id, "task", existing.status, nextStatus);
     const now: number = Date.now();
 
     this.#db
-      .query("UPDATE tasks SET title = ?, description = ?, status = ?, updated_at = ?, version = version + 1 WHERE id = ?;")
-      .run(nextTitle, nextDescription, nextStatus, now, id);
+      .query("UPDATE tasks SET title = ?, description = ?, status = ?, owner = ?, updated_at = ?, version = version + 1 WHERE id = ?;")
+      .run(nextTitle, nextDescription, nextStatus, nextOwner, now, id);
 
     return this.getTaskOrThrow(id);
   }
@@ -541,7 +588,7 @@ export class TrackerDomain {
       this.getTaskOrThrow(taskId);
       const rows = this.#db
         .query(
-          "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE task_id = ? ORDER BY created_at ASC, id ASC;",
+          "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE task_id = ? ORDER BY created_at ASC, id ASC;",
         )
         .all(taskId) as SubtaskRow[];
       return rows.map(mapSubtask);
@@ -549,15 +596,25 @@ export class TrackerDomain {
 
     const rows = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks ORDER BY created_at ASC, id ASC;",
+        "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks ORDER BY created_at ASC, id ASC;",
       )
       .all() as SubtaskRow[];
     return rows.map(mapSubtask);
   }
 
+  getOpenSubtasks(taskId: string): readonly SubtaskRecord[] {
+    this.getTaskOrThrow(taskId);
+    const rows = this.#db
+      .query(
+        "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE task_id = ? AND status != 'done' ORDER BY created_at ASC, id ASC;",
+      )
+      .all(taskId) as SubtaskRow[];
+    return rows.map(mapSubtask);
+  }
+
   getSubtask(id: string): SubtaskRecord | null {
     const row = this.#db
-      .query("SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE id = ?;")
+      .query("SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE id = ?;")
       .get(id) as SubtaskRow | null;
     return row ? mapSubtask(row) : null;
   }
@@ -577,19 +634,20 @@ export class TrackerDomain {
 
   updateSubtask(
     id: string,
-    input: { title?: string | undefined; description?: string | undefined; status?: string | undefined },
+    input: { title?: string | undefined; description?: string | undefined; status?: string | undefined; owner?: string | null | undefined },
   ): SubtaskRecord {
     const existing: SubtaskRecord = this.getSubtaskOrThrow(id);
     const nextTitle: string = input.title !== undefined ? assertNonEmpty("title", input.title) : existing.title;
     const nextDescription: string =
       input.description !== undefined ? normalizeSubtaskDescription(input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
+    const nextOwner: string | null = input.owner !== undefined ? input.owner : existing.owner;
     this.assertNoUnresolvedDependenciesForStatusTransition(id, "subtask", existing.status, nextStatus);
     const now: number = Date.now();
 
     this.#db
-      .query("UPDATE subtasks SET title = ?, description = ?, status = ?, updated_at = ?, version = version + 1 WHERE id = ?;")
-      .run(nextTitle, nextDescription, nextStatus, now, id);
+      .query("UPDATE subtasks SET title = ?, description = ?, status = ?, owner = ?, updated_at = ?, version = version + 1 WHERE id = ?;")
+      .run(nextTitle, nextDescription, nextStatus, nextOwner, now, id);
 
     return this.getSubtaskOrThrow(id);
   }
@@ -605,7 +663,7 @@ export class TrackerDomain {
     const taskIds = new Set(tasks.map((task) => task.id));
     const subtasks = this.#db
       .query(
-        "SELECT id, task_id, title, description, status, created_at, updated_at FROM subtasks WHERE task_id IN (SELECT id FROM tasks WHERE epic_id = ?) ORDER BY created_at ASC, id ASC;",
+        "SELECT id, task_id, title, description, status, owner, created_at, updated_at FROM subtasks WHERE task_id IN (SELECT id FROM tasks WHERE epic_id = ?) ORDER BY created_at ASC, id ASC;",
       )
       .all(epicId) as SubtaskRow[];
 
@@ -921,6 +979,65 @@ export class TrackerDomain {
     return rows.map(mapDependency);
   }
 
+  /**
+   * Resolves dependency statuses for multiple tasks using a single prepared
+   * statement executed once per task ID.  This avoids the previous N+1 pattern
+   * where each task required separate getTaskOrThrow/getSubtaskOrThrow calls
+   * per dependency.
+   */
+  batchResolveDependencyStatuses(
+    taskIds: readonly string[],
+  ): Map<string, { totalDependencies: number; blockers: Array<{ id: string; kind: "task" | "subtask"; status: string }> }> {
+    const result = new Map<string, { totalDependencies: number; blockers: Array<{ id: string; kind: "task" | "subtask"; status: string }> }>();
+
+    if (taskIds.length === 0) {
+      return result;
+    }
+
+    // Use a static parameterised query per task ID rather than interpolating
+    // a dynamic IN-list into the SQL string.  This is consistent with every
+    // other query in TrackerDomain and avoids any placeholder-count confusion.
+    const stmt = this.#db.query(
+      `SELECT d.source_id, d.depends_on_id, d.depends_on_kind, COALESCE(t.status, s.status) AS dep_status
+       FROM dependencies d
+       LEFT JOIN tasks t ON d.depends_on_kind = 'task' AND d.depends_on_id = t.id
+       LEFT JOIN subtasks s ON d.depends_on_kind = 'subtask' AND d.depends_on_id = s.id
+       WHERE d.source_id = ?
+       ORDER BY d.created_at ASC, d.id ASC;`,
+    );
+
+    for (const taskId of taskIds) {
+      const entry = { totalDependencies: 0, blockers: [] as Array<{ id: string; kind: "task" | "subtask"; status: string }> };
+      result.set(taskId, entry);
+
+      const rows = stmt.all(taskId) as Array<{
+        source_id: string;
+        depends_on_id: string;
+        depends_on_kind: "task" | "subtask";
+        dep_status: string | null;
+      }>;
+
+      for (const row of rows) {
+        entry.totalDependencies += 1;
+
+        // Skip orphaned dependency rows (target deleted).
+        if (row.dep_status === null) {
+          continue;
+        }
+
+        if (row.dep_status !== "done") {
+          entry.blockers.push({
+            id: row.depends_on_id,
+            kind: row.depends_on_kind,
+            status: row.dep_status,
+          });
+        }
+      }
+    }
+
+    return result;
+  }
+
   listReverseDependencies(nodeId: string): readonly ReverseDependencyNode[] {
     const normalizedNodeId: string = assertNonEmpty("nodeId", nodeId);
     this.resolveNodeKind(normalizedNodeId);
@@ -1492,10 +1609,17 @@ export class TrackerDomain {
       }
 
       for (const dependency of this.listDependencies(change.id)) {
-        const dependencyStatus =
+        const dependencyNode =
           dependency.dependsOnKind === "task"
-            ? this.getTaskOrThrow(dependency.dependsOnId).status
-            : this.getSubtaskOrThrow(dependency.dependsOnId).status;
+            ? this.getTask(dependency.dependsOnId)
+            : this.getSubtask(dependency.dependsOnId);
+
+        // Skip orphaned dependency rows where the referenced node no longer exists.
+        if (!dependencyNode) {
+          continue;
+        }
+
+        const dependencyStatus = dependencyNode.status;
         const inScope = scopeIdSet.has(dependency.dependsOnId);
         const willCascade = targetStatus === "done" && changedIdSet.has(dependency.dependsOnId);
         if (dependencyStatus === "done" || willCascade) {
@@ -1560,19 +1684,24 @@ export class TrackerDomain {
     const unresolved: UnresolvedDependencyBlocker[] = [];
 
     for (const dependency of dependencies) {
-      const dependencyStatus =
+      const dependencyNode =
         dependency.dependsOnKind === "task"
-          ? this.getTaskOrThrow(dependency.dependsOnId).status
-          : this.getSubtaskOrThrow(dependency.dependsOnId).status;
+          ? this.getTask(dependency.dependsOnId)
+          : this.getSubtask(dependency.dependsOnId);
+
+      // Skip orphaned dependency rows where the referenced node no longer exists.
+      if (!dependencyNode) {
+        continue;
+      }
 
-      if (dependencyStatus === "done") {
+      if (dependencyNode.status === "done") {
         continue;
       }
 
       unresolved.push({
         id: dependency.dependsOnId,
         kind: dependency.dependsOnKind,
-        status: dependencyStatus,
+        status: dependencyNode.status,
       });
     }
 

package/src/domain/types.ts

@@ -1,5 +1,15 @@
 export type NodeKind = "epic" | "task" | "subtask";
 
+export const VALID_STATUSES = ["todo", "in_progress", "done", "blocked"] as const;
+export type ValidStatus = (typeof VALID_STATUSES)[number];
+
+export const VALID_TRANSITIONS: ReadonlyMap<ValidStatus, ReadonlySet<ValidStatus>> = new Map<ValidStatus, ReadonlySet<ValidStatus>>([
+  ["todo", new Set<ValidStatus>(["in_progress", "blocked"])],
+  ["in_progress", new Set<ValidStatus>(["done", "blocked"])],
+  ["blocked", new Set<ValidStatus>(["in_progress", "todo"])],
+  ["done", new Set<ValidStatus>(["in_progress"])],
+]);
+
 export const COMPACT_TEMP_KEY_PREFIX = "@";
 
 export type CompactTempKey = string;
@@ -95,6 +105,7 @@ export interface TaskRecord {
   readonly title: string;
   readonly description: string;
   readonly status: string;
+  readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
 }
@@ -105,6 +116,7 @@ export interface SubtaskRecord {
   readonly title: string;
   readonly description: string;
   readonly status: string;
+  readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
 }

package/src/index.ts

@@ -5,7 +5,7 @@ import { executeShell, parseInvocation, renderShellResult } from "./runtime/cli-
 export async function run(argv: readonly string[] = process.argv.slice(2)): Promise<void> {
   const parsed = parseInvocation(argv);
   const result = await executeShell(parsed);
-  const rendered: string = renderShellResult(result, parsed.mode, parsed.compatibilityMode);
+  const rendered: string = renderShellResult(result, parsed.mode, parsed.compatibilityMode, { compact: parsed.compact });
 
   if (result.ok) {
     process.stdout.write(`${rendered}\n`);

package/src/io/output.ts

@@ -13,8 +13,9 @@ const CONTRACT_VERSION = "1.0.0";
 const COMPATIBILITY_DEPRECATED_SINCE = "0.1.8";
 const COMPATIBILITY_REMOVAL_AFTER = "2026-09-30";
 
-interface RenderOptions {
+export interface RenderOptions {
   readonly compatibilityMode?: CompatibilityMode | null;
+  readonly compact?: boolean;
 }
 
 function toLegacySyncCommandId(command: string): string {
@@ -136,13 +137,14 @@ export function failResult(input: ResultInput & { readonly error: ToonError }):
 
 export function toToonEnvelope(result: CliResult, options: RenderOptions = {}): ToonEnvelope {
   const compatibilityMode: CompatibilityMode | null = options.compatibilityMode ?? null;
+  const compact: boolean = options.compact ?? false;
   const command: string = resolveCompatibilityCommand(result.command, compatibilityMode);
 
   return {
     ok: result.ok,
     command,
     data: result.data,
-    metadata: createContractMetadata(result, compatibilityMode),
+    ...(compact ? {} : { metadata: createContractMetadata(result, compatibilityMode) }),
     ...(result.error ? { error: result.error } : {}),
     ...(result.meta ? { meta: result.meta } : {}),
   };

package/src/runtime/cli-shell.ts

@@ -8,11 +8,12 @@ import { runMigrate } from "../commands/migrate";
 import { runQuickstart } from "../commands/quickstart";
 import { runSession } from "../commands/session";
 import { runSkills } from "../commands/skills";
+import { runSuggest } from "../commands/suggest";
 import { runSubtask } from "../commands/subtask";
 import { runSync } from "../commands/sync";
 import { runTask } from "../commands/task";
 import { runWipe } from "../commands/wipe";
-import { failResult, okResult, renderResult } from "../io/output";
+import { failResult, okResult, renderResult, type RenderOptions } from "../io/output";
 import { resolveStorageResolutionDiagnostics } from "../storage/database";
 import { type CliContext, type CliResult, type CompatibilityMode, type OutputMode } from "./command-types";
 import { CLI_VERSION } from "./version";
@@ -32,11 +33,13 @@ const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "migrate",
   "sync",
   "skills",
+  "suggest",
   "wipe",
 ];
 
 export interface ParsedInvocation {
   readonly mode: OutputMode;
+  readonly compact: boolean;
   readonly compatibilityMode: CompatibilityMode | null;
   readonly compatibilityModeRaw: string | null;
   readonly compatibilityModeMissingValue: boolean;
@@ -53,6 +56,7 @@ export interface ParseInvocationOptions {
 export function parseInvocation(argv: readonly string[], options: ParseInvocationOptions = {}): ParsedInvocation {
   const stdoutIsTTY: boolean = options.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
   let explicitMode: OutputMode | null = null;
+  let compact = false;
   let compatibilityModeRaw: string | null = null;
   let compatibilityModeMissingValue = false;
   let wantsHelp = false;
@@ -75,6 +79,11 @@ export function parseInvocation(argv: readonly string[], options: ParseInvocatio
       continue;
     }
 
+    if (token === "--compact") {
+      compact = true;
+      continue;
+    }
+
     if (token === "--help" || token === "-h") {
       wantsHelp = true;
       continue;
@@ -105,6 +114,7 @@ export function parseInvocation(argv: readonly string[], options: ParseInvocatio
 
   return {
     mode: explicitMode ?? (stdoutIsTTY ? "human" : "json"),
+    compact,
     compatibilityMode,
     compatibilityModeRaw,
     compatibilityModeMissingValue,
@@ -115,13 +125,23 @@ export function parseInvocation(argv: readonly string[], options: ParseInvocatio
   };
 }
 
-export function renderShellResult(result: CliResult, mode: OutputMode, compatibilityMode: CompatibilityMode | null = null): string {
+export function renderShellResult(
+  result: CliResult,
+  mode: OutputMode,
+  compatibilityMode: CompatibilityMode | null = null,
+  options: { compact?: boolean } = {},
+): string {
   const effectiveCompatibilityMode: CompatibilityMode | null =
     compatibilityMode === "legacy-sync-command-ids" && result.command.startsWith("sync.")
       ? compatibilityMode
       : null;
 
-  return renderResult(result, mode, { compatibilityMode: effectiveCompatibilityMode });
+  const renderOptions: RenderOptions = {
+    compatibilityMode: effectiveCompatibilityMode,
+    compact: options.compact ?? false,
+  };
+
+  return renderResult(result, mode, renderOptions);
 }
 
 function isStringArray(value: unknown): value is string[] {
@@ -375,6 +395,9 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
     case "skills":
       result = await runSkills(context);
       break;
+    case "suggest":
+      result = await runSuggest(context);
+      break;
     default:
       result = failResult({
         command: "shell",

package/src/runtime/command-types.ts

@@ -32,7 +32,7 @@ export interface ToonEnvelope {
   readonly ok: boolean;
   readonly command: string;
   readonly data: unknown;
-  readonly metadata: ContractMetadata;
+  readonly metadata?: ContractMetadata;
   readonly error?: ToonError;
   readonly meta?: Record<string, unknown>;
 }

package/src/storage/database.ts

@@ -98,6 +98,48 @@ export function resolveStorageResolutionDiagnostics(
   }
 }
 
+/** Default connection-level busy_timeout applied at open time. */
+const DEFAULT_BUSY_TIMEOUT_MS = 15000;
+
+/**
+ * Maximum time (ms) to wait when acquiring the write lock via BEGIN IMMEDIATE.
+ * Kept below the default bun test timeout so that lock-contention surfaces as
+ * a SQLITE_BUSY error rather than a test-level timeout.
+ */
+const WRITE_LOCK_BUSY_TIMEOUT_MS = 3000;
+
+/**
+ * Execute a write transaction using BEGIN IMMEDIATE to acquire a reserved lock
+ * up-front, avoiding SQLITE_BUSY errors that occur when a deferred transaction
+ * is promoted to a write lock after readers have already started.
+ *
+ * A shorter busy_timeout is applied while acquiring the lock so callers receive
+ * a prompt SQLITE_BUSY error instead of blocking for the full connection-level
+ * timeout.  The connection-level timeout is restored before returning.
+ */
+export function writeTransaction<T>(db: Database, fn: (db: Database) => T): T {
+  db.exec(`PRAGMA busy_timeout = ${WRITE_LOCK_BUSY_TIMEOUT_MS};`);
+  try {
+    db.exec("BEGIN IMMEDIATE;");
+  } catch (error) {
+    db.exec(`PRAGMA busy_timeout = ${DEFAULT_BUSY_TIMEOUT_MS};`);
+    throw error;
+  }
+  db.exec(`PRAGMA busy_timeout = ${DEFAULT_BUSY_TIMEOUT_MS};`);
+  try {
+    const result: T = fn(db);
+    db.exec("COMMIT;");
+    return result;
+  } catch (error) {
+    try {
+      db.exec("ROLLBACK;");
+    } catch {
+      /* best-effort rollback — propagate the original error */
+    }
+    throw error;
+  }
+}
+
 export function openTrekoonDatabase(
   workingDirectory: string = process.cwd(),
   options: OpenTrekoonDatabaseOptions = {},
@@ -110,7 +152,7 @@ export function openTrekoonDatabase(
 
   const db: Database = new Database(paths.databaseFile, { create: true });
 
-  db.exec("PRAGMA busy_timeout = 5000;");
+  db.exec(`PRAGMA busy_timeout = ${DEFAULT_BUSY_TIMEOUT_MS};`);
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec("PRAGMA foreign_keys = ON;");
 

package/src/storage/events-retention.ts

@@ -1,5 +1,7 @@
 import { type Database } from "bun:sqlite";
 
+import { writeTransaction } from "./database";
+
 export const DEFAULT_EVENT_RETENTION_DAYS = 90;
 const DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
 
@@ -18,6 +20,7 @@ export interface EventPruneSummary {
   readonly candidateCount: number;
   readonly archivedCount: number;
   readonly deletedCount: number;
+  readonly staleCursorCount: number;
 }
 
 function ensureArchiveTable(db: Database): void {
@@ -53,27 +56,72 @@ function countCandidates(db: Database, cutoffTimestamp: number): number {
   return row?.count ?? 0;
 }
 
+function oldestCursorTimestamp(db: Database): number | null {
+  const row = db
+    .query("SELECT MIN(last_event_at) AS oldest FROM sync_cursors WHERE last_event_at IS NOT NULL;")
+    .get() as { oldest: number | null } | null;
+
+  return row?.oldest ?? null;
+}
+
+function countStaleCursors(db: Database): number {
+  // A cursor is stale when its last_event_at references a timestamp
+  // that has no corresponding event remaining in the events table.
+  // We detect this by checking if the oldest event in the table is
+  // newer than the cursor's last_event_at.
+  const oldestEventRow = db
+    .query("SELECT MIN(created_at) AS oldest FROM events;")
+    .get() as { oldest: number | null } | null;
+
+  const oldestEventAt: number | null = oldestEventRow?.oldest ?? null;
+
+  if (oldestEventAt === null) {
+    // No events at all — any cursor with a last_event_at is stale.
+    const row = db
+      .query("SELECT COUNT(*) AS count FROM sync_cursors WHERE last_event_at IS NOT NULL;")
+      .get() as { count: number } | null;
+    return row?.count ?? 0;
+  }
+
+  const row = db
+    .query(
+      "SELECT COUNT(*) AS count FROM sync_cursors WHERE last_event_at IS NOT NULL AND last_event_at < ?;",
+    )
+    .get(oldestEventAt) as { count: number } | null;
+
+  return row?.count ?? 0;
+}
+
 export function pruneEvents(db: Database, options: EventPruneOptions = {}): EventPruneSummary {
   const retentionDays: number = assertRetentionDays(options.retentionDays ?? DEFAULT_EVENT_RETENTION_DAYS);
   const dryRun: boolean = options.dryRun ?? false;
   const archive: boolean = options.archive ?? false;
   const now: number = options.now ?? Date.now();
-  const cutoffTimestamp: number = now - retentionDays * DAY_IN_MILLISECONDS;
-  const candidateCount: number = countCandidates(db, cutoffTimestamp);
+  const retentionCutoff: number = now - retentionDays * DAY_IN_MILLISECONDS;
+
+  // Guard: never prune events that a sync cursor still references.
+  // The effective cutoff is the earlier of the retention cutoff and
+  // the oldest cursor timestamp — so cursors always have replayable history.
+  const oldest: number | null = oldestCursorTimestamp(db);
+  const effectiveCutoff: number = oldest !== null ? Math.min(retentionCutoff, oldest) : retentionCutoff;
+
+  const candidateCount: number = countCandidates(db, effectiveCutoff);
+  const staleCursors: number = countStaleCursors(db);
 
   if (dryRun || candidateCount === 0) {
     return {
       retentionDays,
-      cutoffTimestamp,
+      cutoffTimestamp: effectiveCutoff,
       dryRun,
       archive,
       candidateCount,
       archivedCount: 0,
       deletedCount: 0,
+      staleCursorCount: staleCursors,
     };
   }
 
-  return db.transaction((): EventPruneSummary => {
+  return writeTransaction(db, (): EventPruneSummary => {
     let archivedCount = 0;
 
     if (archive) {
@@ -118,21 +166,22 @@ export function pruneEvents(db: Database, options: EventPruneOptions = {}): Even
             version = excluded.version;
           `,
         )
-        .run(cutoffTimestamp);
+        .run(effectiveCutoff);
 
       archivedCount = archived.changes;
     }
 
-    const deleted = db.query("DELETE FROM events WHERE created_at < ?;").run(cutoffTimestamp);
+    const deleted = db.query("DELETE FROM events WHERE created_at < ?;").run(effectiveCutoff);
 
     return {
       retentionDays,
-      cutoffTimestamp,
+      cutoffTimestamp: effectiveCutoff,
       dryRun,
       archive,
       candidateCount,
       archivedCount,
       deletedCount: deleted.changes,
+      staleCursorCount: staleCursors,
     };
-  })();
+  });
 }