@lobu/worker 7.1.0 → 7.2.0

package/src/__tests__/transcript-snapshot.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Unit tests for the worker-side per-run snapshot helpers
+ * (`hydrateFromSnapshot`, `writeSnapshot`).
+ *
+ * These exercise the HTTP-client side of the snapshot path against a mocked
+ * gateway. Coverage:
+ *  - Hydrate writes the gateway's bytes verbatim to disk, fsyncs, returns
+ *    the post-hydrate file size matching the byte_size column contract.
+ *  - Hydrate handles 404 (no completed snapshot) → returns false, leaves
+ *    the local file untouched.
+ *  - Hydrate failures are non-fatal at the caller's discretion (we re-throw,
+ *    caller logs+continues; behaviour verified in worker.ts but we assert
+ *    the throw shape here).
+ *  - writeSnapshot reads the session file, POSTs body, handles 409 (race
+ *    win), missing file (early-exit worker), and empty file all silently.
+ *  - The transport layer never throws — `cleanup()` runs in the worker's
+ *    dying breath and any throw would abort the surrounding `finally`.
+ *
+ * The gateway test (`packages/server/src/gateway/__tests__/
+ * agent-transcript-snapshot.test.ts`) covers the route + PG side; this
+ * file is the symmetric client side.
+ */
+
+import { promises as fs } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  hydrateFromSnapshot,
+  writeSnapshot,
+} from "../openclaw/transcript-snapshot";
+
+let tmp: string;
+let originalFetch: typeof globalThis.fetch;
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), "snapshot-test-"));
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(async () => {
+  globalThis.fetch = originalFetch;
+  await rm(tmp, { recursive: true, force: true });
+});
+
+function stubFetch(
+  handler: (url: string, init: RequestInit) => Response
+): void {
+  globalThis.fetch = mock(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      return handler(url, init ?? {});
+    }
+  ) as unknown as typeof globalThis.fetch;
+}
+
+describe("hydrateFromSnapshot", () => {
+  test("boot-hydrate-fsync: writes bytes verbatim, file size matches body length", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    const expected =
+      `{"type":"session","version":3,"id":"hydrate","timestamp":"2026-05-18T10:00:00Z","cwd":"/w"}\n` +
+      `{"type":"message","id":"m1","parentId":null,"timestamp":"2026-05-18T10:00:01Z","message":{"role":"user","content":[{"type":"text","text":"resume"}]}}\n`;
+
+    stubFetch((url, init) => {
+      expect(url.endsWith("/worker/transcript/snapshot")).toBe(true);
+      expect(init.method).toBe("GET");
+      expect((init.headers as Record<string, string>).Authorization).toBe(
+        "Bearer test-jwt"
+      );
+      return new Response(expected, { status: 200 });
+    });
+
+    const hydrated = await hydrateFromSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+    });
+    expect(hydrated).toBe(true);
+
+    // File written + fsynced → stat size matches byte_size we'd compute.
+    const stats = await fs.stat(sessionFile);
+    expect(stats.size).toBe(Buffer.byteLength(expected, "utf-8"));
+    const back = await fs.readFile(sessionFile, "utf-8");
+    expect(back).toBe(expected);
+  });
+
+  test("returns false on 404 and does not touch the file", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    stubFetch(() => new Response("", { status: 404 }));
+
+    const hydrated = await hydrateFromSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+    });
+    expect(hydrated).toBe(false);
+    // No file created.
+    let exists = false;
+    try {
+      await fs.stat(sessionFile);
+      exists = true;
+    } catch {
+      exists = false;
+    }
+    expect(exists).toBe(false);
+  });
+
+  test("throws on non-2xx, non-404 — caller logs + continues with local file", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    stubFetch(() => new Response("boom", { status: 500 }));
+    await expect(
+      hydrateFromSnapshot({
+        sessionFile,
+        gatewayUrl: "http://gw.test/lobu",
+        workerToken: "test-jwt",
+      })
+    ).rejects.toThrow(/transcript hydrate failed: 500/);
+  });
+});
+
+describe("writeSnapshot", () => {
+  test("happy path: reads file, POSTs body + terminalStatus, gateway 200", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    const body =
+      `{"type":"session","version":3,"id":"write","timestamp":"2026-05-18T10:00:00Z","cwd":"/w"}\n` +
+      `{"type":"message","id":"u1","parentId":null,"timestamp":"2026-05-18T10:00:01Z","message":{"role":"user","content":[{"type":"text","text":"hi"}]}}\n`;
+    await fs.writeFile(sessionFile, body, "utf-8");
+
+    let postedBody: string | null = null;
+    stubFetch((url, init) => {
+      expect(url.endsWith("/worker/transcript/snapshot")).toBe(true);
+      expect(init.method).toBe("POST");
+      postedBody = init.body as string;
+      return new Response('{"id":1}', { status: 200 });
+    });
+
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+    expect(postedBody).not.toBeNull();
+    const parsed = JSON.parse(postedBody!);
+    expect(parsed.snapshotJsonl).toBe(body);
+    expect(parsed.terminalStatus).toBe("completed");
+    // P1#1: runId MUST be on the POST body so the route attributes the
+    // snapshot to the exact run this worker claimed, not "latest run for
+    // (org, agent, conv)".
+    expect(parsed.runId).toBe(42);
+  });
+
+  test("non-completed terminalStatus is skipped (no POST, no waste)", async () => {
+    // Hydrate filters terminal_status='completed' — writing failed/
+    // timeout/cancelled rows is pure network waste. Codex round 2
+    // quality win C on PR #865. The cleanup() path is also gated on
+    // `terminalStatus === "completed"`, but writeSnapshot defends in
+    // depth so any future caller can't accidentally write a row that
+    // hydrate will never read.
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+
+    let calls = 0;
+    stubFetch(() => {
+      calls++;
+      return new Response("{}", { status: 200 });
+    });
+
+    for (const terminalStatus of ["failed", "timeout", "cancelled"] as const) {
+      await writeSnapshot({
+        sessionFile,
+        gatewayUrl: "http://gw.test/lobu",
+        workerToken: "test-jwt",
+        terminalStatus,
+        runId: 42,
+      });
+    }
+    expect(calls).toBe(0);
+  });
+
+  test("race-win-409 is benign — no throw", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+
+    stubFetch(() => new Response("conflict", { status: 409 }));
+
+    // No throw — cleanup() in the worker's dying breath must never
+    // re-throw inside a `finally`.
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+  });
+
+  test("no session file (early-exit worker): silently skips, no fetch", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    let calls = 0;
+    stubFetch(() => {
+      calls++;
+      return new Response("", { status: 200 });
+    });
+
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "failed",
+      runId: 42,
+    });
+    expect(calls).toBe(0);
+  });
+
+  test("empty session file is skipped — never POST an empty snapshot", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, "", "utf-8");
+    let calls = 0;
+    stubFetch(() => {
+      calls++;
+      return new Response("{}", { status: 200 });
+    });
+
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+    expect(calls).toBe(0);
+  });
+
+  test("server 500 is logged, not thrown", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+    stubFetch(() => new Response("boom", { status: 500 }));
+
+    // No throw — same invariant as the 409 case. Logs go to pino; we
+    // don't assert log content here.
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+  });
+
+  test("fetch throw is caught — cleanup() must never re-throw", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+    globalThis.fetch = (() => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof globalThis.fetch;
+
+    // No throw escapes — caller is the cleanup() finally block.
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+  });
+});

package/src/core/types.ts

@@ -28,6 +28,24 @@ export interface WorkerConfig {
   workspace: {
     baseDirectory: string;
   };
+  /**
+   * The runs.id of the row that dispatched this job. Set by the gateway
+   * (MessageConsumer stamps it from the runs-queue claim's job.id) so the
+   * worker's cleanup() snapshot can attribute itself to the correct run
+   * even when a follow-up run for the same conversation has already been
+   * enqueued (codex P1#1 on PR #865). Optional for backward-compatibility
+   * with legacy direct-enqueue paths that don't go through the runs queue.
+   */
+  runId?: number;
+  /**
+   * Per-run worker JWT bound to `runId`. Set by MessageConsumer at
+   * dispatch time and used by cleanup()'s writeSnapshot call as the
+   * Authorization bearer — replaces the deployment-lifetime WORKER_TOKEN
+   * for the snapshot path so the gateway's route can require token-runId
+   * equality with body.runId (codex round 2 finding A on PR #865).
+   * When absent (legacy direct-enqueue), the snapshot write is skipped.
+   */
+  runJobToken?: string;
 }
 
 export interface WorkspaceSetupConfig {

package/src/gateway/sse-client.ts

@@ -81,20 +81,33 @@ const AgentOptionsSchema = z
   .passthrough();
 
 const JobEventSchema = z.object({
-  payload: z.object({
-    botId: z.string(),
-    userId: z.string(),
-    agentId: z.string(),
-    conversationId: z.string(),
-    platform: z.string(),
-    channelId: z.string(),
-    messageId: z.string(),
-    messageText: z.string(),
-    platformMetadata: PlatformMetadataSchema,
-    agentOptions: AgentOptionsSchema,
-    jobId: z.string().optional(),
-    teamId: z.string().optional(), // Optional for WhatsApp (top-level) and Slack (in platformMetadata)
-  }),
+  payload: z
+    .object({
+      botId: z.string(),
+      userId: z.string(),
+      agentId: z.string(),
+      conversationId: z.string(),
+      platform: z.string(),
+      channelId: z.string(),
+      messageId: z.string(),
+      messageText: z.string(),
+      platformMetadata: PlatformMetadataSchema,
+      agentOptions: AgentOptionsSchema,
+      jobId: z.string().optional(),
+      teamId: z.string().optional(), // Optional for WhatsApp (top-level) and Slack (in platformMetadata)
+      // Threaded through from MessageConsumer's runs-queue claim. The worker
+      // asserts these in snapshot mode (LOBU_SESSION_STORE != "file") — see
+      // worker.ts:353-360. The default zod object mode strips unknown keys,
+      // which silently dropped these fields and broke every Telegram chat
+      // when snapshot mode became the default in PR #871. Declare them
+      // explicitly so they survive parsing, and `.passthrough()` keeps any
+      // future MessagePayload field (mcpConfig, nixConfig, egressConfig,
+      // preApprovedTools, exec* fields, organizationId, networkConfig...)
+      // from regressing the same way.
+      runId: z.number().optional(),
+      runJobToken: z.string().optional(),
+    })
+    .passthrough(),
   processedIds: z.array(z.string()).optional(),
 });
 
@@ -919,6 +932,21 @@ export class GatewayClient {
       workspace: {
         baseDirectory: process.env.WORKSPACE_DIR || "/workspace",
       },
+      // Threaded through from MessageConsumer (set from the runs-queue
+      // claim's job.id). Used by cleanup() to attribute the snapshot to
+      // the correct run; codex P1#1 on PR #865.
+      runId:
+        typeof payload.runId === "number" && Number.isFinite(payload.runId)
+          ? payload.runId
+          : undefined,
+      // Per-run JWT minted by MessageConsumer alongside runId. Worker
+      // uses this for the snapshot POST instead of the deployment-
+      // lifetime WORKER_TOKEN, so the gateway can enforce
+      // tokenData.runId === body.runId — codex round 2 finding A.
+      runJobToken:
+        typeof payload.runJobToken === "string" && payload.runJobToken
+          ? payload.runJobToken
+          : undefined,
     };
   }
 

package/src/gateway/types.ts

@@ -41,6 +41,21 @@ export interface MessagePayload {
   jobId?: string; // Optional job ID from gateway
   teamId?: string; // Optional team ID (WhatsApp uses top-level, Slack uses platformMetadata)
 
+  // The runs.id of the row that dispatched this job. Set by the gateway
+  // MessageConsumer (stamped from the runs-queue claim's job.id) and
+  // threaded into WorkerConfig.runId. The worker's cleanup() uses it to
+  // attribute the agent_transcript_snapshot row to the correct run —
+  // see codex P1#1 on PR #865.
+  runId?: number;
+
+  // Per-run worker JWT bound to `runId` above. Minted by MessageConsumer
+  // and threaded into WorkerConfig.runJobToken. The worker uses THIS
+  // token (not the deployment-lifetime WORKER_TOKEN) when calling the
+  // snapshot endpoint, so the route's `tokenData.runId === body.runId`
+  // equality check can reject any cross-run impersonation — codex round
+  // 2 finding A on PR #865.
+  runJobToken?: string;
+
   // Job type (default: "message")
   jobType?: JobType;
 

package/src/openclaw/transcript-snapshot.ts

@@ -0,0 +1,238 @@
+/**
+ * Per-run snapshot client for OpenClaw's `session.jsonl`.
+ *
+ * Why this exists: today's PVC-backed `workspaces/` directory is read-write-
+ * once, which forces the helm chart to pin `replicaCount: 1` for the
+ * gateway/worker. Mirroring the post-run session.jsonl to Postgres lets a
+ * second pod hydrate the file on boot and resume the conversation, which is
+ * the prerequisite for dropping the PVC (Phase 5, separate PR).
+ *
+ * Design contract for the next reader:
+ *   - We do NOT fork or wrap `@mariozechner/pi-coding-agent`'s `SessionManager`.
+ *     It owns the file on disk; we read it back at terminal time and write
+ *     the bytes verbatim to PG. The next boot writes those bytes back to
+ *     disk verbatim before SessionManager.open(), so SessionManager observes
+ *     a byte-identical file to what it last wrote.
+ *   - The snapshot is taken in `OpenClawWorker.cleanup()` on every terminal
+ *     status — `completed`, `failed`, `timeout`, `cancelled`. Hydrate filters
+ *     for `terminal_status='completed'` so a failed run can't poison the
+ *     next worker with a dangling `tool_use` content block. Older completed
+ *     snapshots remain readable; the hydrate query takes the latest one.
+ *   - The worker is sandboxed — no PG access. Two new endpoints live on the
+ *     existing worker gateway: `GET /worker/transcript/snapshot` for
+ *     hydrate, `POST /worker/transcript/snapshot` for write. (org, agent,
+ *     conv) are pulled from the worker JWT on the gateway side, so the
+ *     worker can't impersonate another conversation.
+ *   - Phase 5: snapshot mode is the default. `LOBU_SESSION_STORE=file`
+ *     opts out for legacy/local-dev single-replica deploys. Phase 6
+ *     drops the env var entirely.
+ *
+ * Trade-off accepted: a mid-run crash loses the partial transcript for that
+ * run. The next attempt re-runs from the previous user message. Tools must
+ * be idempotent (or accept user-visible re-execution).
+ */
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { createLogger } from "@lobu/core";
+
+const logger = createLogger("transcript-snapshot");
+
+export type TerminalStatus = "completed" | "failed" | "timeout" | "cancelled";
+
+export interface TranscriptSnapshotOptions {
+  /** Absolute path to the session.jsonl SessionManager reads/writes. */
+  sessionFile: string;
+  /** Gateway base URL (e.g. `http://127.0.0.1:8787/lobu`). */
+  gatewayUrl: string;
+  /** Worker JWT. The gateway pulls (org, agent, conv) from this token. */
+  workerToken: string;
+}
+
+/**
+ * Pull the latest `terminal_status='completed'` snapshot for this worker's
+ * (org, agent, conv) and write the bytes to `sessionFile`. Must run BEFORE
+ * SessionManager.open() so the rehydrated content is visible at open time.
+ *
+ * Returns `true` if a snapshot was found and written, `false` if no snapshot
+ * exists yet (first turn). Throws on transport errors — caller decides
+ * whether to fall back to a fresh session.
+ */
+export async function hydrateFromSnapshot(
+  opts: TranscriptSnapshotOptions
+): Promise<boolean> {
+  const url = `${opts.gatewayUrl}/worker/transcript/snapshot`;
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${opts.workerToken}` },
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  // 404 = no completed snapshot for this (org, agent, conv). First turn or
+  // every previous attempt failed/timed out. Caller should start fresh.
+  if (res.status === 404) {
+    return false;
+  }
+  if (!res.ok) {
+    throw new Error(
+      `transcript hydrate failed: ${res.status} ${res.statusText}`
+    );
+  }
+
+  const body = await res.text();
+  await fs.mkdir(path.dirname(opts.sessionFile), { recursive: true });
+  // writeFile truncates atomically (open with O_TRUNC); no partial state
+  // is visible to SessionManager.open() because that call runs after this
+  // function resolves.
+  await fs.writeFile(opts.sessionFile, body, "utf-8");
+  // fsync so a pod crash between this return and SessionManager.open()
+  // doesn't leave the file half-written. The cost is one extra disk flush
+  // on every worker boot — acceptable.
+  const handle = await fs.open(opts.sessionFile, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+
+  logger.info(
+    `Hydrated session file from snapshot: ${body.length} bytes → ${opts.sessionFile}`
+  );
+  return true;
+}
+
+/**
+ * Read the session file in full and POST it to the gateway. Called once per
+ * worker run at terminal time, from `OpenClawWorker.cleanup()`. The
+ * `terminal_status` discriminator lets the hydrate path skip failed/timeout
+ * snapshots so a dangling `tool_use` doesn't poison the next attempt.
+ *
+ * Failure to snapshot is logged but does NOT throw — there's nothing the
+ * caller can do beyond what cleanup already does (the worker is exiting).
+ * The next attempt will hydrate from the previous successful snapshot.
+ */
+export async function writeSnapshot(
+  opts: TranscriptSnapshotOptions & {
+    terminalStatus: TerminalStatus;
+    /**
+     * The runs.id this worker claimed. Sent in the POST body so the route
+     * binds the snapshot to the correct run unambiguously; the route then
+     * verifies the runId actually belongs to the JWT's (org, agent, conv)
+     * tuple before INSERTing. Codex P1#1 on PR #865 — without this, the
+     * route fell back to a "latest run for (org, agent, conv)" lookup
+     * which raced with the next user message enqueuing a fresh run.
+     */
+    runId: number;
+  }
+): Promise<void> {
+  // Hydrate filters `terminal_status='completed'` — failed/timeout/cancelled
+  // snapshots are never used. POSTing them is pure network waste; the
+  // route would store them but no future hydrate would pick them up.
+  // Skip at the source so any caller (cleanup() today, future paths
+  // tomorrow) stays out of the wasteful write. Codex round 2 quality
+  // win C on PR #865.
+  if (opts.terminalStatus !== "completed") {
+    logger.debug(
+      `Skipping snapshot POST: terminal_status='${opts.terminalStatus}' is never read by hydrate`
+    );
+    return;
+  }
+
+  let body: string;
+  try {
+    body = await fs.readFile(opts.sessionFile, "utf-8");
+  } catch (err) {
+    // No session file = nothing to snapshot. Common when the worker exits
+    // before SessionManager.open() ran (early error path).
+    const isMissing =
+      err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (isMissing) {
+      logger.debug(`No session file at ${opts.sessionFile}; skipping snapshot`);
+      return;
+    }
+    logger.warn(
+      `Failed to read session file for snapshot: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return;
+  }
+
+  if (body.length === 0) {
+    logger.debug("Empty session file; skipping snapshot");
+    return;
+  }
+
+  const url = `${opts.gatewayUrl}/worker/transcript/snapshot`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${opts.workerToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        terminalStatus: opts.terminalStatus,
+        snapshotJsonl: body,
+        runId: opts.runId,
+      }),
+      // Snapshots can be large (633 KB max measured); 60s timeout covers
+      // slow links + PG TOAST writes.
+      signal: AbortSignal.timeout(60_000),
+    });
+    if (!res.ok) {
+      // 409 = UNIQUE (org, agent, conv, run_id) collision. Means another
+      // pod (or a retry) already wrote this snapshot — benign, drop it.
+      if (res.status === 409) {
+        logger.info(
+          `Snapshot for run already exists (status=${opts.terminalStatus}); skipping duplicate`
+        );
+        return;
+      }
+      logger.error(`Snapshot POST failed: ${res.status} ${res.statusText}`);
+      return;
+    }
+    logger.info(
+      `Wrote snapshot: ${body.length} bytes, status=${opts.terminalStatus}`
+    );
+  } catch (err) {
+    logger.error(
+      `Snapshot POST threw: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return;
+  }
+}
+
+/**
+ * Purge all snapshot rows for this worker's (org, agent, conv). Called
+ * by the session-reset path so the next boot doesn't rehydrate the
+ * conversation from Postgres after a `/new`. Idempotent — a 404 / empty
+ * result is treated as success.
+ *
+ * Failures are logged but not thrown — reset is best-effort; if the
+ * purge HTTP call fails the worst case is the next boot hydrates from
+ * the previous transcript (the legacy file-mode behaviour). The local
+ * session.jsonl unlink is the primary signal; this is the multi-replica
+ * complement to it.
+ */
+export async function clearSnapshots(
+  opts: Pick<TranscriptSnapshotOptions, "gatewayUrl" | "workerToken">
+): Promise<void> {
+  const url = `${opts.gatewayUrl}/worker/transcript/snapshot`;
+  try {
+    const res = await fetch(url, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${opts.workerToken}` },
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+      logger.warn(
+        `Snapshot DELETE failed: ${res.status} ${res.statusText} — next boot may rehydrate stale history`
+      );
+      return;
+    }
+    logger.info("Purged conversation snapshots for session reset");
+  } catch (err) {
+    logger.warn(
+      `Snapshot DELETE threw: ${err instanceof Error ? err.message : String(err)} — next boot may rehydrate stale history`
+    );
+  }
+}