@stigmer/runner 3.1.7 → 3.1.9

package/src/shared/checkpointer/__tests__/sqlite-saver.test.ts

@@ -0,0 +1,212 @@
+/**
+ * SqliteCheckpointSaver tests.
+ *
+ * The saver is the durable OSS/local checkpointer that makes HITL/pause/
+ * transient-recovery resume across ExecuteDeepAgent invocations (stigmer/stigmer#204).
+ * These tests pin two things:
+ *  1. Behavioral parity with the reference MemorySaver for the operations the
+ *     resume path relies on (put/getTuple round-trip incl. pending writes).
+ *  2. The property MemorySaver cannot provide and that the whole feature rests
+ *     on: durability across a close/reopen of the file (i.e. across the
+ *     per-invocation open/close the activity performs).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  MemorySaver,
+  emptyCheckpoint,
+  WRITES_IDX_MAP,
+  type BaseCheckpointSaver,
+  type Checkpoint,
+  type CheckpointMetadata,
+  type PendingWrite,
+} from "@langchain/langgraph-checkpoint";
+import type { RunnableConfig } from "@langchain/core/runnables";
+import { SqliteCheckpointSaver } from "../sqlite-saver.js";
+
+const THREAD = "thread-abc";
+
+function threadConfig(checkpointId?: string): RunnableConfig {
+  return {
+    configurable: {
+      thread_id: THREAD,
+      checkpoint_ns: "",
+      ...(checkpointId ? { checkpoint_id: checkpointId } : {}),
+    },
+  };
+}
+
+function makeCheckpoint(id: string, values: Record<string, unknown> = {}): Checkpoint {
+  return { ...emptyCheckpoint(), id, channel_values: values };
+}
+
+function meta(source: CheckpointMetadata["source"], step: number): CheckpointMetadata {
+  return { source, step, parents: {} };
+}
+
+describe("SqliteCheckpointSaver", () => {
+  let dir: string;
+  let dbPath: string;
+  let saver: SqliteCheckpointSaver;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "stigmer-sqlite-cp-"));
+    dbPath = join(dir, "checkpoints.db");
+    saver = new SqliteCheckpointSaver(dbPath);
+  });
+
+  afterEach(() => {
+    saver.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("round-trips a checkpoint and its metadata", async () => {
+    const cp = makeCheckpoint("cp-1", { messages: ["hello"] });
+    const returned = await saver.put(threadConfig(), cp, meta("input", 1), {});
+    expect(returned.configurable?.checkpoint_id).toBe("cp-1");
+
+    const tuple = await saver.getTuple(threadConfig("cp-1"));
+    expect(tuple).toBeDefined();
+    expect(tuple!.checkpoint.id).toBe("cp-1");
+    expect(tuple!.checkpoint.channel_values).toEqual({ messages: ["hello"] });
+    expect(tuple!.metadata).toEqual(meta("input", 1));
+  });
+
+  it("returns the latest checkpoint when no checkpoint_id is given", async () => {
+    await saver.put(threadConfig(), makeCheckpoint("cp-1"), meta("input", 1), {});
+    await saver.put(threadConfig("cp-1"), makeCheckpoint("cp-2"), meta("loop", 2), {});
+
+    const latest = await saver.getTuple(threadConfig());
+    expect(latest!.checkpoint.id).toBe("cp-2");
+    // The parent config points back to the previous checkpoint.
+    expect(latest!.parentConfig?.configurable?.checkpoint_id).toBe("cp-1");
+  });
+
+  it("returns undefined for an unknown thread", async () => {
+    const tuple = await saver.getTuple({
+      configurable: { thread_id: "nope", checkpoint_ns: "" },
+    });
+    expect(tuple).toBeUndefined();
+  });
+
+  it("hydrates pending writes on getTuple", async () => {
+    await saver.put(threadConfig(), makeCheckpoint("cp-1"), meta("input", 1), {});
+    const writes: PendingWrite[] = [
+      ["messages", { role: "assistant", content: "hi" }],
+      ["counter", 7],
+    ];
+    await saver.putWrites(threadConfig("cp-1"), writes, "task-1");
+
+    const tuple = await saver.getTuple(threadConfig("cp-1"));
+    expect(tuple!.pendingWrites).toEqual([
+      ["task-1", "messages", { role: "assistant", content: "hi" }],
+      ["task-1", "counter", 7],
+    ]);
+  });
+
+  it("REPLACEs special-channel writes but IGNOREs duplicate regular writes", async () => {
+    await saver.put(threadConfig(), makeCheckpoint("cp-1"), meta("input", 1), {});
+
+    // Special channels (fixed negative idx): a later write overwrites the earlier
+    // one at the same slot — this is what lets a RESUME overwrite an INTERRUPT.
+    const interruptCh = "__interrupt__";
+    expect(interruptCh in WRITES_IDX_MAP).toBe(true);
+    await saver.putWrites(threadConfig("cp-1"), [[interruptCh, "first"]], "task-1");
+    await saver.putWrites(threadConfig("cp-1"), [[interruptCh, "second"]], "task-1");
+
+    // Regular channels: the first write at (task_id, idx) wins; a duplicate is
+    // ignored so concurrent tasks can't clobber each other.
+    await saver.putWrites(threadConfig("cp-1"), [["messages", "original"]], "task-2");
+    await saver.putWrites(threadConfig("cp-1"), [["messages", "overwrite?"]], "task-2");
+
+    const tuple = await saver.getTuple(threadConfig("cp-1"));
+    const byChannel = new Map(
+      tuple!.pendingWrites!.map(([, channel, value]) => [channel, value]),
+    );
+    expect(byChannel.get(interruptCh)).toBe("second");
+    expect(byChannel.get("messages")).toBe("original");
+  });
+
+  it("lists checkpoints newest-first with limit and before", async () => {
+    for (const id of ["cp-1", "cp-2", "cp-3"]) {
+      await saver.put(threadConfig(), makeCheckpoint(id), meta("loop", 1), {});
+    }
+
+    const all: string[] = [];
+    for await (const t of saver.list(threadConfig())) all.push(t.checkpoint.id);
+    expect(all).toEqual(["cp-3", "cp-2", "cp-1"]);
+
+    const limited: string[] = [];
+    for await (const t of saver.list(threadConfig(), { limit: 2 })) {
+      limited.push(t.checkpoint.id);
+    }
+    expect(limited).toEqual(["cp-3", "cp-2"]);
+
+    const before: string[] = [];
+    for await (const t of saver.list(threadConfig(), {
+      before: { configurable: { checkpoint_id: "cp-3" } },
+    })) {
+      before.push(t.checkpoint.id);
+    }
+    expect(before).toEqual(["cp-2", "cp-1"]);
+  });
+
+  it("deleteThread removes checkpoints and writes", async () => {
+    await saver.put(threadConfig(), makeCheckpoint("cp-1"), meta("input", 1), {});
+    await saver.putWrites(threadConfig("cp-1"), [["messages", "x"]], "task-1");
+
+    await saver.deleteThread(THREAD);
+
+    expect(await saver.getTuple(threadConfig("cp-1"))).toBeUndefined();
+    expect(await saver.getTuple(threadConfig())).toBeUndefined();
+  });
+
+  it("persists across a close and reopen of the same file (durability)", async () => {
+    await saver.put(threadConfig(), makeCheckpoint("cp-1", { messages: ["kept"] }), meta("input", 1), {});
+    await saver.putWrites(threadConfig("cp-1"), [["messages", "pending"]], "task-1");
+    saver.close();
+
+    // A fresh saver on the same path — the shape of the activity's per-invocation
+    // open/close — must read what the prior invocation wrote.
+    const reopened = new SqliteCheckpointSaver(dbPath);
+    try {
+      const tuple = await reopened.getTuple(threadConfig("cp-1"));
+      expect(tuple!.checkpoint.channel_values).toEqual({ messages: ["kept"] });
+      expect(tuple!.pendingWrites).toEqual([["task-1", "messages", "pending"]]);
+    } finally {
+      reopened.close();
+    }
+  });
+
+  it("close() is idempotent", () => {
+    saver.close();
+    expect(() => saver.close()).not.toThrow();
+  });
+
+  it("matches MemorySaver on the put -> putWrites -> getTuple path (parity)", async () => {
+    const memory: BaseCheckpointSaver = new MemorySaver();
+
+    const run = async (s: BaseCheckpointSaver) => {
+      await s.put(threadConfig(), makeCheckpoint("cp-1", { step: "a" }), meta("input", 1), {});
+      await s.putWrites(
+        threadConfig("cp-1"),
+        [["messages", { role: "assistant", content: "parity" }]],
+        "task-1",
+      );
+      const tuple = await s.getTuple(threadConfig("cp-1"));
+      return {
+        id: tuple!.checkpoint.id,
+        values: tuple!.checkpoint.channel_values,
+        metadata: tuple!.metadata,
+        pendingWrites: tuple!.pendingWrites,
+      };
+    };
+
+    const sqliteResult = await run(saver);
+    const memoryResult = await run(memory);
+    expect(sqliteResult).toEqual(memoryResult);
+  });
+});

package/src/shared/checkpointer/factory.ts

@@ -2,9 +2,13 @@
  * Checkpointer factory — creates the appropriate LangGraph checkpoint
  * saver based on runner configuration.
  *
- * Two backends:
- * - memory: MemorySaver (ephemeral, zero-config) — for OSS / local mode
- * - http: HttpCheckpointSaver (proxy-backed) — for cloud mode
+ * Three backends:
+ * - sqlite: SqliteCheckpointSaver (durable local file) — the OSS / local /
+ *   desktop default. Survives across ExecuteDeepAgent invocations so HITL,
+ *   pause/resume, and transient recovery resume via Command(resume) rather than
+ *   replaying from the original message (stigmer/stigmer#204).
+ * - http: HttpCheckpointSaver (proxy-backed) — for cloud / managed runners.
+ * - memory: MemorySaver (ephemeral, zero-config) — explicit opt-in for tests.
  *
  * The returned saver is used by the deep agent activity (Phase 3).
  * Cursor executions do not use LangGraph checkpointers — they rely on
@@ -15,6 +19,7 @@ import { MemorySaver } from "@langchain/langgraph-checkpoint";
 import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
 import type { CheckpointerConfig } from "./types.js";
 import { HttpCheckpointSaver } from "./http-saver.js";
+import { SqliteCheckpointSaver } from "./sqlite-saver.js";
 
 export class CheckpointerCreationError extends Error {
   readonly checkpointerType: string;
@@ -31,15 +36,27 @@ export class CheckpointerCreationError extends Error {
 /**
  * Create the appropriate checkpoint saver for the given config.
  *
- * Unlike the Python version (which returns an async context manager),
- * the JS MemorySaver and HttpCheckpointSaver do not require async
- * initialization or cleanup. This function is kept async to accommodate
- * future backends that might need setup (e.g. SQLite connection).
+ * This function is async to accommodate backends that need setup. The
+ * SqliteCheckpointSaver opens its file handle in its constructor and creates
+ * the schema lazily on first use; it must be closed by the caller (the deep
+ * agent activity closes it in its cleanup, alongside the MCP connection).
  */
 export async function createCheckpointer(
   config: CheckpointerConfig,
 ): Promise<BaseCheckpointSaver> {
   switch (config.type) {
+    case "sqlite": {
+      if (!config.sqlitePath) {
+        throw new CheckpointerCreationError(
+          "sqlite",
+          "sqlitePath is required for SQLite checkpointer",
+        );
+      }
+      const saver = new SqliteCheckpointSaver(config.sqlitePath);
+      console.log(`Created SqliteCheckpointSaver checkpointer (path=${config.sqlitePath})`);
+      return saver;
+    }
+
     case "memory":
       console.log("Created MemorySaver checkpointer (ephemeral, in-memory)");
       return new MemorySaver();
@@ -66,7 +83,7 @@ export async function createCheckpointer(
       const exhaustive: never = config.type;
       throw new CheckpointerCreationError(
         String(exhaustive),
-        `Unknown checkpointer type. Valid types: memory, http`,
+        `Unknown checkpointer type. Valid types: sqlite, http, memory`,
       );
     }
   }

package/src/shared/checkpointer/sqlite-saver.ts

@@ -0,0 +1,384 @@
+/**
+ * SQLite-backed LangGraph checkpoint saver — the durable checkpointer for the
+ * OSS / local edition.
+ *
+ * Why this exists: the OSS-local default used to be the ephemeral `MemorySaver`,
+ * recreated empty on every `ExecuteDeepAgent` invocation. The Temporal workflow
+ * re-invokes the activity with the SAME `thread_id` on HITL approval, pause/
+ * resume, and transient recovery — but with an empty checkpointer the graph has
+ * nothing to resume from, so it replays from the original user message instead
+ * of continuing after the interrupt. This saver makes the checkpoint survive
+ * across invocations on a single machine, so those re-invocations resume via
+ * `Command(resume)` exactly like the cloud (`http`) path (see stigmer/stigmer#204).
+ *
+ * Implementation notes:
+ * - Backed by Node's built-in `node:sqlite` (`DatabaseSync`). Zero external
+ *   dependencies and bundles cleanly into the slim artifact — `node:`-prefixed
+ *   builtins stay external to esbuild, unlike a native addon such as
+ *   `better-sqlite3` (which the official `@langchain/langgraph-checkpoint-sqlite`
+ *   depends on and which cannot be bundled).
+ * - Schema and the `put` / `putWrites` conflict-resolution semantics mirror the
+ *   official `@langchain/langgraph-checkpoint-sqlite` saver, so a checkpoint
+ *   written here is byte-compatible with the reference implementation.
+ * - Serialization uses the inherited `JsonPlusSerializer` (`this.serde`), exactly
+ *   like {@link HttpCheckpointSaver}. Serialized payloads are stored as raw BLOBs
+ *   and read back as `Uint8Array`, so binary (msgpack) payloads round-trip
+ *   losslessly — this is why writes are read via a dedicated query rather than
+ *   the reference saver's `CAST(value AS TEXT)` JSON aggregation.
+ * - WAL journaling plus a busy timeout make the file safe to open from more than
+ *   one process at once (the CLI daemon and the desktop runner can share a HOME).
+ */
+
+import { DatabaseSync, type StatementSync, type SQLInputValue } from "node:sqlite";
+import type { RunnableConfig } from "@langchain/core/runnables";
+import {
+  BaseCheckpointSaver,
+  WRITES_IDX_MAP,
+  copyCheckpoint,
+  type ChannelVersions,
+  type Checkpoint,
+  type CheckpointListOptions,
+  type CheckpointMetadata,
+  type CheckpointPendingWrite,
+  type CheckpointTuple,
+  type PendingWrite,
+  type SerializerProtocol,
+} from "@langchain/langgraph-checkpoint";
+
+/** Milliseconds SQLite waits on a locked database before erroring (WAL busy handler). */
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+
+interface CheckpointColumns {
+  thread_id: string;
+  checkpoint_ns: string;
+  checkpoint_id: string;
+  parent_checkpoint_id: string | null;
+  type: string | null;
+  checkpoint: Uint8Array;
+  metadata: Uint8Array;
+}
+
+interface WriteColumns {
+  task_id: string;
+  channel: string;
+  type: string | null;
+  value: Uint8Array;
+}
+
+export class SqliteCheckpointSaver extends BaseCheckpointSaver {
+  private readonly db: DatabaseSync;
+  private isSetup = false;
+
+  constructor(dbPath: string, serde?: SerializerProtocol) {
+    super(serde);
+    this.db = new DatabaseSync(dbPath, { timeout: DEFAULT_BUSY_TIMEOUT_MS });
+  }
+
+  /**
+   * Create the schema on first use. WAL + the constructor's busy timeout make
+   * concurrent readers/writers (across processes sharing the file) safe. The
+   * tables and their primary keys mirror the official
+   * `@langchain/langgraph-checkpoint-sqlite` schema.
+   */
+  private setup(): void {
+    if (this.isSetup) return;
+
+    this.db.exec("PRAGMA journal_mode=WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS checkpoints (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        parent_checkpoint_id TEXT,
+        type TEXT,
+        checkpoint BLOB,
+        metadata BLOB,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+      );
+    `);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS writes (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        channel TEXT NOT NULL,
+        type TEXT,
+        value BLOB,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+      );
+    `);
+
+    this.isSetup = true;
+  }
+
+  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    const checkpointNs = (config.configurable?.checkpoint_ns as string | undefined) ?? "";
+    const checkpointId = config.configurable?.checkpoint_id as string | undefined;
+
+    const row = (checkpointId
+      ? this.db
+          .prepare(
+            `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+             FROM checkpoints
+             WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`,
+          )
+          .get(threadId ?? null, checkpointNs, checkpointId)
+      : this.db
+          .prepare(
+            `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+             FROM checkpoints
+             WHERE thread_id = ? AND checkpoint_ns = ?
+             ORDER BY checkpoint_id DESC LIMIT 1`,
+          )
+          .get(threadId ?? null, checkpointNs)) as unknown as CheckpointColumns | undefined;
+
+    if (row === undefined) return undefined;
+
+    return this.rowToTuple(row);
+  }
+
+  async *list(
+    config: RunnableConfig,
+    options?: CheckpointListOptions,
+  ): AsyncGenerator<CheckpointTuple> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    const checkpointNs = config.configurable?.checkpoint_ns as string | undefined;
+    const before = options?.before?.configurable?.checkpoint_id as string | undefined;
+    const limit = options?.limit;
+
+    // Supported filter subset mirrors HttpCheckpointSaver (thread_id /
+    // checkpoint_ns / before / limit). The runner's resume path reads via
+    // getState -> getTuple, so metadata filtering is not exercised here.
+    const where: string[] = [];
+    const args: SQLInputValue[] = [];
+    if (threadId !== undefined) {
+      where.push("thread_id = ?");
+      args.push(threadId);
+    }
+    if (checkpointNs !== undefined) {
+      where.push("checkpoint_ns = ?");
+      args.push(checkpointNs);
+    }
+    if (before !== undefined) {
+      where.push("checkpoint_id < ?");
+      args.push(before);
+    }
+
+    let sql =
+      `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+       FROM checkpoints`;
+    if (where.length > 0) sql += ` WHERE ${where.join(" AND ")}`;
+    sql += " ORDER BY checkpoint_id DESC";
+    if (limit !== undefined) sql += ` LIMIT ${parseInt(String(limit), 10)}`;
+
+    const rows = this.db.prepare(sql).all(...args) as unknown as CheckpointColumns[];
+    for (const row of rows) {
+      yield await this.rowToTuple(row);
+    }
+  }
+
+  async put(
+    config: RunnableConfig,
+    checkpoint: Checkpoint,
+    metadata: CheckpointMetadata,
+    _newVersions: ChannelVersions,
+  ): Promise<RunnableConfig> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    if (!threadId) {
+      throw new Error(`Missing "thread_id" field in passed "config.configurable".`);
+    }
+    const checkpointNs = (config.configurable?.checkpoint_ns as string | undefined) ?? "";
+    const parentCheckpointId = config.configurable?.checkpoint_id as string | undefined;
+
+    // Defensive copy before serialization, matching the reference saver.
+    const [[checkpointType, serializedCheckpoint], [metadataType, serializedMetadata]] =
+      await Promise.all([
+        this.serde.dumpsTyped(copyCheckpoint(checkpoint)),
+        this.serde.dumpsTyped(metadata),
+      ]);
+
+    if (checkpointType !== metadataType) {
+      throw new Error("Failed to serialize checkpoint and metadata to the same type.");
+    }
+
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO checkpoints
+           (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        threadId,
+        checkpointNs,
+        checkpoint.id,
+        parentCheckpointId ?? null,
+        checkpointType,
+        serializedCheckpoint,
+        serializedMetadata,
+      );
+
+    return {
+      configurable: {
+        thread_id: threadId,
+        checkpoint_ns: checkpointNs,
+        checkpoint_id: checkpoint.id,
+      },
+    };
+  }
+
+  async putWrites(
+    config: RunnableConfig,
+    writes: PendingWrite[],
+    taskId: string,
+  ): Promise<void> {
+    this.setup();
+
+    const threadId = config.configurable?.thread_id as string | undefined;
+    if (!threadId) throw new Error("Missing thread_id field in config.configurable.");
+    const checkpointId = config.configurable?.checkpoint_id as string | undefined;
+    if (!checkpointId) throw new Error("Missing checkpoint_id field in config.configurable.");
+    const checkpointNs = (config.configurable?.checkpoint_ns as string | undefined) ?? "";
+
+    // Conflict resolution matches the reference saver and the
+    // langgraph-checkpoint contract:
+    // - All-special writes (ERROR / SCHEDULED / INTERRUPT / RESUME, each pinned
+    //   to a negative idx by WRITES_IDX_MAP) REPLACE, so e.g. INTERRUPT can be
+    //   overwritten by RESUME.
+    // - Otherwise IGNORE, so a regular write from one task never clobbers a
+    //   regular write another concurrent task already stored at the same
+    //   (task_id, idx).
+    const allSpecial = writes.every(([channel]) => channel in WRITES_IDX_MAP);
+    const stmt: StatementSync = this.db.prepare(
+      `INSERT ${allSpecial ? "OR REPLACE" : "OR IGNORE"} INTO writes
+         (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+
+    const rows = await Promise.all(
+      writes.map(async ([channel, value], idx) => {
+        const [type, serialized] = await this.serde.dumpsTyped(value);
+        return {
+          // Special channels are stored at fixed negative indices so they never
+          // collide with regular per-step writes (whose idx is the ordinal).
+          idx: WRITES_IDX_MAP[channel] ?? idx,
+          channel,
+          type,
+          value: serialized,
+        };
+      }),
+    );
+
+    this.db.exec("BEGIN");
+    try {
+      for (const row of rows) {
+        stmt.run(
+          threadId,
+          checkpointNs,
+          checkpointId,
+          taskId,
+          row.idx,
+          row.channel,
+          row.type,
+          row.value,
+        );
+      }
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  async deleteThread(threadId: string): Promise<void> {
+    this.setup();
+
+    this.db.exec("BEGIN");
+    try {
+      this.db.prepare("DELETE FROM checkpoints WHERE thread_id = ?").run(threadId);
+      this.db.prepare("DELETE FROM writes WHERE thread_id = ?").run(threadId);
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  /** Close the underlying database handle. Idempotent and non-throwing. */
+  close(): void {
+    try {
+      this.db.close();
+    } catch {
+      /* already closed */
+    }
+  }
+
+  /** Deserialize a checkpoint row and hydrate its pending writes. */
+  private async rowToTuple(row: CheckpointColumns): Promise<CheckpointTuple> {
+    const type = row.type ?? "json";
+    const checkpoint = (await this.serde.loadsTyped(type, row.checkpoint)) as Checkpoint;
+    const metadata = (await this.serde.loadsTyped(type, row.metadata)) as CheckpointMetadata;
+
+    const pendingWrites = await this.loadPendingWrites(
+      row.thread_id,
+      row.checkpoint_ns,
+      row.checkpoint_id,
+    );
+
+    return {
+      config: {
+        configurable: {
+          thread_id: row.thread_id,
+          checkpoint_ns: row.checkpoint_ns,
+          checkpoint_id: row.checkpoint_id,
+        },
+      },
+      checkpoint,
+      metadata,
+      parentConfig: row.parent_checkpoint_id
+        ? {
+            configurable: {
+              thread_id: row.thread_id,
+              checkpoint_ns: row.checkpoint_ns,
+              checkpoint_id: row.parent_checkpoint_id,
+            },
+          }
+        : undefined,
+      pendingWrites,
+    };
+  }
+
+  private async loadPendingWrites(
+    threadId: string,
+    checkpointNs: string,
+    checkpointId: string,
+  ): Promise<CheckpointPendingWrite[]> {
+    const writeRows = this.db
+      .prepare(
+        `SELECT task_id, channel, type, value
+         FROM writes
+         WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+         ORDER BY task_id, idx`,
+      )
+      .all(threadId, checkpointNs, checkpointId) as unknown as WriteColumns[];
+
+    return Promise.all(
+      writeRows.map(
+        async (w) =>
+          [
+            w.task_id,
+            w.channel,
+            await this.serde.loadsTyped(w.type ?? "json", w.value),
+          ] as CheckpointPendingWrite,
+      ),
+    );
+  }
+}

package/src/shared/checkpointer/types.ts

@@ -1,12 +1,16 @@
 /**
  * Configuration for the checkpointer factory.
  *
- * Two backends are supported:
- * - memory: ephemeral in-process storage (OSS / local development)
- * - http: routes through the Stigmer Side-Channel Proxy (cloud)
+ * Three backends are supported:
+ * - sqlite: durable local file (OSS / local / desktop default) — survives across
+ *   ExecuteDeepAgent invocations so HITL/pause/transient-recovery truly resume.
+ * - http:   routes through the Stigmer Side-Channel Proxy (cloud / managed).
+ * - memory: ephemeral in-process storage — explicit opt-in, used by tests.
  */
 export interface CheckpointerConfig {
-  readonly type: "memory" | "http";
+  readonly type: "memory" | "http" | "sqlite";
   readonly proxyEndpoint?: string;
   readonly authToken?: string;
+  /** Absolute path to the SQLite database file. Required when type is "sqlite". */
+  readonly sqlitePath?: string;
 }