@getrift/rift 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/src/jobs/queue.d.ts

@@ -10,9 +10,13 @@ import type { Job, JobType, CreateJobResult, JobHandler } from "./types.js";
 export declare class JobQueue {
     private queuePath;
     private jobs;
+    private payloadRefs;
     private handlers;
     private processing;
     private held;
+    private persistRetryTimer;
+    private startRetryTimer;
+    private startRetryDelayMs;
     constructor(queuePath: string);
     /**
      * Hold processing — registerHandler and create won't auto-start queued
@@ -55,6 +59,17 @@ export declare class JobQueue {
     }>;
     /** Get a job by ID, or undefined. */
     get(id: string): Job | undefined;
+    /**
+     * Return all jobs whose `idempotency_key` starts with `prefix`. Used
+     * by the friend-status projection to surface inbox freshness — jobs
+     * created from the inbox watcher all use keys of the form
+     * `inbox:<hex>`, so a prefix scan answers "what's the inbox lane
+     * doing" without leaking queue internals to the route layer.
+     *
+     * Read-only iteration of the in-memory map; safe to call on a hot
+     * queue. Returns the snapshot in insertion order.
+     */
+    listByIdempotencyPrefix(prefix: string): Job[];
     /**
      * Check whether an idempotency key matches an existing active job.
      * Returns the job if found in queued/running/completed state, undefined otherwise.
@@ -70,8 +85,35 @@ export declare class JobQueue {
     cancel(id: string): Promise<Job | {
         conflict: true;
     } | undefined>;
-    /** Atomic write: temp file + rename. */
+    /**
+     * Keep the persisted ledger bounded so `JSON.stringify` can never exceed
+     * V8's max string length (the failure mode that turned every save into a
+     * 500). Two cheap, safe reductions on terminal jobs only:
+     *   1. Drop `payload` — only active jobs need it.
+     *   2. Cap how many terminal jobs we retain (oldest dropped first).
+     * Non-terminal jobs (queued/running/interrupted) are never touched.
+     * Returns true if anything changed.
+     */
+    private compactLedger;
+    /** Atomic write: temp file + rename. Ledger is compacted first so the
+     * serialized form stays well under V8's max string length. */
     private persist;
+    private createLedgerTooLargeError;
+    private snapshotState;
+    private restoreSnapshot;
+    private payloadDir;
+    private payloadPath;
+    private payloadRefPath;
+    private payloadAbsPath;
+    private isPayloadRef;
+    private hydrateJob;
+    private readPayloadRef;
+    private serializeJobForLedger;
+    private writePayloadFile;
+    private prunePayloadRefCache;
+    private deletePayloadFilesForJob;
+    private cleanupPayloadFiles;
+    private deletePayloadPath;
     /**
      * Find the active job for a given idempotency key.
      * Skip superseded jobs (those with `retried_by` set) so we always
@@ -102,6 +144,14 @@ export declare class JobQueue {
     private createRetryJob;
     /** Process the next queued job if no job is currently running. */
     private processNext;
+    private applyPersistedMutation;
+    private applyTerminalMutation;
+    private markPersistDirty;
+    private schedulePersistRetry;
+    private scheduleStartRetry;
+    private clearStartRetry;
+    private clearPersistRetry;
+    private retryDirtyPersist;
     private findNextQueued;
 }
 //# sourceMappingURL=queue.d.ts.map

package/dist/src/jobs/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/jobs/queue.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAa,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGvF;;;;;;;GAOG;AACH,qBAAa,QAAQ;IAMP,OAAO,CAAC,SAAS;IAL7B,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,IAAI,CAAS;gBAED,SAAS,EAAE,MAAM;IAErC;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAIZ,6DAA6D;IAC7D,WAAW,IAAI,IAAI;IAKnB,+EAA+E;IAC/E,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAKzD,uDAAuD;IACvD,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAIlC;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA8C3B;;;;;;;;;;;OAWG;IACG,MAAM,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GACrD,OAAO,CAAC,eAAe,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC;IA0ChD,qCAAqC;IACrC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAIhC;;;;OAIG;IACH,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAatD;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,SAAS,CAAC;IAkBvE,wCAAwC;YAC1B,OAAO;IAOrB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;;;;;;;;OASG;IACG,YAAY,CAChB,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC,eAAe,CAAC;IAwB3B,sDAAsD;IACtD,qBAAqB,IAAI,OAAO;IAYhC;;;;OAIG;IACH,sBAAsB,IAAI,GAAG,GAAG,IAAI;YAStB,cAAc;IA6B5B,kEAAkE;IAClE,OAAO,CAAC,WAAW;IAgCnB,OAAO,CAAC,cAAc;CAMvB"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/jobs/queue.ts"],"names":[],"mappings":"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"}

package/dist/src/jobs/queue.js

@@ -1,6 +1,46 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
+import path from "node:path";
 import { EXCLUSIVE_JOBS } from "./types.js";
+/**
+ * Terminal statuses: the job is done and its `payload` (full
+ * conversation / export text) is dead weight — the durable record lives
+ * in raw files + the vector index, not the queue ledger. Only
+ * queued/running/interrupted jobs still need their payload.
+ */
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+]);
+/**
+ * Terminal statuses whose `payload` is safe to drop. A `failed` job is
+ * still retryable — `create()` with the same idempotency_key turns it into
+ * a retry whose chain root (the failed job) must still carry the canonical
+ * source/raw payload (save.ts resolveChainRoot). The failure path persists
+ * (and thus compacts) the job the instant it fails, before any retry exists,
+ * so stripping `failed` payloads here would silently break changed-source
+ * retries. Failed jobs are few (cap still bounds them); keep their payload.
+ */
+const STRIPPABLE_STATUSES = new Set([
+    "completed",
+    "cancelled",
+]);
+/**
+ * Cap on retained terminal-job records. Metadata is tiny (~200 B/job),
+ * but unbounded retention eventually blows `JSON.stringify`'s max string
+ * length (V8 ~512 MB) — the failure that turned every save into a 500.
+ * We keep the most recent N; idempotency dedup and the friend-status
+ * projection only need recent terminal jobs, and older sessions are
+ * re-guarded by capture-state.json + content-hash dedup.
+ */
+const MAX_TERMINAL_JOBS = 2000;
+const PAYLOAD_OFFLOAD_THRESHOLD_BYTES = 64 * 1024;
+const MAX_LEDGER_BYTES = 64 * 1024 * 1024;
+const PAYLOAD_REF_MARKER = "__rift_queue_payload_ref";
+const PERSIST_RETRY_DELAY_MS = 100;
+const START_RETRY_INITIAL_DELAY_MS = 100;
+const START_RETRY_MAX_DELAY_MS = 5000;
 /**
  * In-process job queue with:
  * - Persistence to `queue.json` (atomic write: temp + rename)
@@ -12,9 +52,13 @@ import { EXCLUSIVE_JOBS } from "./types.js";
 export class JobQueue {
     queuePath;
     jobs = new Map();
+    payloadRefs = new Map();
     handlers = new Map();
     processing = false;
     held = false;
+    persistRetryTimer;
+    startRetryTimer;
+    startRetryDelayMs = START_RETRY_INITIAL_DELAY_MS;
     constructor(queuePath) {
         this.queuePath = queuePath;
     }
@@ -53,9 +97,11 @@ export class JobQueue {
             const raw = fs.readFileSync(this.queuePath, "utf-8");
             const entries = JSON.parse(raw);
             this.jobs.clear();
+            this.payloadRefs.clear();
             // Collect jobs that need recovery (were running at crash time).
             const toRequeue = [];
-            for (const job of entries) {
+            for (const entry of entries) {
+                const job = this.hydrateJob(entry);
                 if (job.status === "running") {
                     job.status = "interrupted";
                     job.updated_at = new Date().toISOString();
@@ -79,7 +125,10 @@ export class JobQueue {
                 job.retried_by = requeuedId;
                 this.jobs.set(requeuedId, requeued);
             }
-            if (toRequeue.length > 0) {
+            // Heal a ledger that bloated before this fix shipped: strip terminal
+            // payloads / cap retention on load, even when nothing needs re-queuing.
+            const compacted = this.compactLedger();
+            if (toRequeue.length > 0 || compacted) {
                 await this.persist();
             }
         }
@@ -134,8 +183,16 @@ export class JobQueue {
             ...(key !== undefined ? { idempotency_key: key } : {}),
             ...(opts?.payload !== undefined ? { payload: opts.payload } : {}),
         };
+        const snapshot = this.snapshotState();
         this.jobs.set(job.id, job);
-        await this.persist();
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            this.restoreSnapshot(snapshot);
+            this.deletePayloadFilesForJob(job.id);
+            throw err;
+        }
         this.processNext();
         return { job, duplicate: false };
     }
@@ -143,6 +200,24 @@ export class JobQueue {
     get(id) {
         return this.jobs.get(id);
     }
+    /**
+     * Return all jobs whose `idempotency_key` starts with `prefix`. Used
+     * by the friend-status projection to surface inbox freshness — jobs
+     * created from the inbox watcher all use keys of the form
+     * `inbox:<hex>`, so a prefix scan answers "what's the inbox lane
+     * doing" without leaking queue internals to the route layer.
+     *
+     * Read-only iteration of the in-memory map; safe to call on a hot
+     * queue. Returns the snapshot in insertion order.
+     */
+    listByIdempotencyPrefix(prefix) {
+        const out = [];
+        for (const job of this.jobs.values()) {
+            if (job.idempotency_key?.startsWith(prefix))
+                out.push(job);
+        }
+        return out;
+    }
     /**
      * Check whether an idempotency key matches an existing active job.
      * Returns the job if found in queued/running/completed state, undefined otherwise.
@@ -169,9 +244,16 @@ export class JobQueue {
         if (!job)
             return undefined;
         if (job.status === "queued" || job.status === "interrupted") {
+            const snapshot = this.snapshotState();
             job.status = "cancelled";
             job.updated_at = new Date().toISOString();
-            await this.persist();
+            try {
+                await this.persist();
+            }
+            catch (err) {
+                this.restoreSnapshot(snapshot);
+                throw err;
+            }
             return job;
         }
         if (job.status === "running") {
@@ -179,12 +261,274 @@ export class JobQueue {
         }
         return undefined;
     }
-    /** Atomic write: temp file + rename. */
+    /**
+     * Keep the persisted ledger bounded so `JSON.stringify` can never exceed
+     * V8's max string length (the failure mode that turned every save into a
+     * 500). Two cheap, safe reductions on terminal jobs only:
+     *   1. Drop `payload` — only active jobs need it.
+     *   2. Cap how many terminal jobs we retain (oldest dropped first).
+     * Non-terminal jobs (queued/running/interrupted) are never touched.
+     * Returns true if anything changed.
+     */
+    compactLedger() {
+        let changed = false;
+        // Protect every job reachable by walking `retry_of` from a non-terminal
+        // job. The save/ingest handlers call resolveChainRoot() to recover the
+        // canonical row id + source from the chain root. If an ancestor is
+        // dropped (payload stripped OR row deleted) while a retry is still
+        // queued/running, resolveChainRoot stops short (save.ts:55), the handler
+        // falls back to the retry's own id/source, and a duplicate row is
+        // created. So these ancestors are exempt from BOTH reductions below.
+        const protectedIds = new Set();
+        for (const job of this.jobs.values()) {
+            if (TERMINAL_STATUSES.has(job.status))
+                continue;
+            let cursor = job;
+            let depth = 0;
+            while (cursor?.retry_of && depth < 50) {
+                const parent = this.jobs.get(cursor.retry_of);
+                if (!parent)
+                    break;
+                protectedIds.add(parent.id);
+                cursor = parent;
+                depth++;
+            }
+        }
+        const terminal = [];
+        for (const job of this.jobs.values()) {
+            if (TERMINAL_STATUSES.has(job.status)) {
+                // Keep payload on retry-chain ancestors: the save handler walks
+                // `retry_of` to the root job and reads its payload to resolve the
+                // canonical source/raw artifact (src/jobs/handlers/save.ts). A job
+                // with `retried_by` set is such an ancestor, as is any ancestor of
+                // a still-active retry (protectedIds). Standalone/leaf terminal jobs
+                // no longer need their payload.
+                if (job.payload !== undefined &&
+                    STRIPPABLE_STATUSES.has(job.status) &&
+                    job.retried_by === undefined &&
+                    !protectedIds.has(job.id)) {
+                    delete job.payload;
+                    changed = true;
+                }
+                terminal.push(job);
+            }
+        }
+        if (terminal.length > MAX_TERMINAL_JOBS) {
+            // Drop the oldest terminal jobs beyond the cap (oldest by updated_at),
+            // but never an ancestor of a still-active retry chain. If protected
+            // jobs prevent reaching the cap, the ledger stays slightly above it —
+            // correctness over a hard bound (the overflow is bounded by in-flight
+            // work, which is small).
+            terminal.sort((a, b) => a.updated_at.localeCompare(b.updated_at));
+            const overflow = terminal.length - MAX_TERMINAL_JOBS;
+            let dropped = 0;
+            for (const job of terminal) {
+                if (dropped >= overflow)
+                    break;
+                if (protectedIds.has(job.id))
+                    continue;
+                this.jobs.delete(job.id);
+                dropped++;
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    /** Atomic write: temp file + rename. Ledger is compacted first so the
+     * serialized form stays well under V8's max string length. */
     async persist() {
-        const data = JSON.stringify([...this.jobs.values()], null, 2);
+        this.compactLedger();
+        this.prunePayloadRefCache();
+        const activePayloadRefs = new Set();
+        const entries = [...this.jobs.values()].map((job) => this.serializeJobForLedger(job, activePayloadRefs));
+        let data;
+        try {
+            data = JSON.stringify(entries, null, 2);
+            if (Buffer.byteLength(data, "utf-8") > MAX_LEDGER_BYTES) {
+                throw this.createLedgerTooLargeError(`Job ledger exceeds ${MAX_LEDGER_BYTES} bytes after payload offload.`);
+            }
+        }
+        catch (err) {
+            // Defense in depth: even after compaction, a pathological volume of
+            // active payloads could exceed V8's max string length. Surface a
+            // typed, actionable error instead of a bare 500 — and never silently
+            // corrupt active jobs by dropping their payloads.
+            if (err instanceof RangeError) {
+                throw this.createLedgerTooLargeError("Job ledger too large to serialize (exceeds V8 max string length).");
+            }
+            throw err;
+        }
         const tmp = this.queuePath + `.tmp.${process.pid}`;
         fs.writeFileSync(tmp, data, "utf-8");
         fs.renameSync(tmp, this.queuePath);
+        this.cleanupPayloadFiles(activePayloadRefs);
+        this.clearPersistRetry();
+    }
+    createLedgerTooLargeError(message) {
+        const e = new Error(`${message} Payloads above ${PAYLOAD_OFFLOAD_THRESHOLD_BYTES} bytes are ` +
+            "offloaded automatically, so this means there are too many queued jobs " +
+            "or a malformed payload reference. Retry after current jobs drain, or " +
+            "see reports/2026-05-25-capture-500-queue-bloat.md for manual recovery.");
+        e.code = "queue_ledger_too_large";
+        return e;
+    }
+    snapshotState() {
+        return {
+            jobs: new Map([...this.jobs.entries()].map(([id, job]) => [id, { ...job }])),
+            payloadRefs: new Map([...this.payloadRefs.entries()].map(([id, entry]) => [
+                id,
+                { ref: { ...entry.ref }, value: entry.value },
+            ])),
+        };
+    }
+    restoreSnapshot(snapshot) {
+        this.jobs = snapshot.jobs;
+        this.payloadRefs = snapshot.payloadRefs;
+    }
+    payloadDir() {
+        return path.join(path.dirname(this.queuePath), "payloads");
+    }
+    payloadPath(jobId, sha256) {
+        return path.join(this.payloadDir(), `${jobId}.${sha256}.json`);
+    }
+    payloadRefPath(jobId, sha256) {
+        return `payloads/${jobId}.${sha256}.json`;
+    }
+    payloadAbsPath(ref) {
+        return path.isAbsolute(ref.path)
+            ? ref.path
+            : path.join(path.dirname(this.queuePath), ref.path);
+    }
+    isPayloadRef(payload) {
+        return (typeof payload === "object" &&
+            payload !== null &&
+            payload[PAYLOAD_REF_MARKER] === true &&
+            typeof payload["path"] === "string" &&
+            typeof payload["byte_length"] === "number" &&
+            typeof payload["sha256"] === "string");
+    }
+    hydrateJob(entry) {
+        const job = { ...entry };
+        if (this.isPayloadRef(entry.payload)) {
+            const payload = this.readPayloadRef(entry.payload);
+            job.payload = payload;
+            this.payloadRefs.set(job.id, {
+                ref: { ...entry.payload },
+                value: payload,
+            });
+        }
+        return job;
+    }
+    readPayloadRef(ref) {
+        const refPath = this.payloadAbsPath(ref);
+        const raw = fs.readFileSync(refPath, "utf-8");
+        const bytes = Buffer.byteLength(raw, "utf-8");
+        const sha256 = crypto.createHash("sha256").update(raw).digest("hex");
+        if (bytes !== ref.byte_length || sha256 !== ref.sha256) {
+            throw new Error(`Job payload ref failed integrity check: ${ref.path}`);
+        }
+        return JSON.parse(raw);
+    }
+    serializeJobForLedger(job, activePayloadRefs) {
+        const persisted = { ...job };
+        if (job.payload === undefined) {
+            delete persisted.payload;
+            this.payloadRefs.delete(job.id);
+            return persisted;
+        }
+        const cached = this.payloadRefs.get(job.id);
+        if (cached &&
+            cached.value === job.payload &&
+            fs.existsSync(this.payloadAbsPath(cached.ref))) {
+            activePayloadRefs.add(this.payloadAbsPath(cached.ref));
+            persisted.payload = cached.ref;
+            return persisted;
+        }
+        const payloadJson = JSON.stringify(job.payload);
+        if (payloadJson === undefined) {
+            throw new Error(`Job ${job.id} payload is not JSON-serializable`);
+        }
+        const byteLength = Buffer.byteLength(payloadJson, "utf-8");
+        if (byteLength <= PAYLOAD_OFFLOAD_THRESHOLD_BYTES) {
+            this.payloadRefs.delete(job.id);
+            persisted.payload = job.payload;
+            return persisted;
+        }
+        const sha256 = crypto.createHash("sha256").update(payloadJson).digest("hex");
+        const refPath = this.payloadRefPath(job.id, sha256);
+        const ref = {
+            [PAYLOAD_REF_MARKER]: true,
+            path: refPath,
+            byte_length: byteLength,
+            sha256,
+        };
+        this.writePayloadFile(this.payloadPath(job.id, sha256), payloadJson);
+        this.payloadRefs.set(job.id, { ref, value: job.payload });
+        activePayloadRefs.add(this.payloadAbsPath(ref));
+        persisted.payload = ref;
+        return persisted;
+    }
+    writePayloadFile(filePath, data) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const tmp = `${filePath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, data, "utf-8");
+        fs.renameSync(tmp, filePath);
+    }
+    prunePayloadRefCache() {
+        for (const jobId of this.payloadRefs.keys()) {
+            if (!this.jobs.has(jobId)) {
+                this.payloadRefs.delete(jobId);
+            }
+        }
+    }
+    deletePayloadFilesForJob(jobId) {
+        const dir = this.payloadDir();
+        let files;
+        try {
+            if (!fs.existsSync(dir))
+                return;
+            files = fs.readdirSync(dir);
+        }
+        catch (err) {
+            process.stderr.write(`queue: warning: failed to scan payload files for ${jobId}: ${err instanceof Error ? err.message : String(err)}\n`);
+            return;
+        }
+        for (const file of files) {
+            if (file === `${jobId}.json` || file.startsWith(`${jobId}.`)) {
+                this.deletePayloadPath(path.join(dir, file), jobId);
+            }
+        }
+    }
+    cleanupPayloadFiles(activePayloadRefs) {
+        const dir = this.payloadDir();
+        let files;
+        try {
+            if (!fs.existsSync(dir))
+                return;
+            files = fs.readdirSync(dir);
+        }
+        catch (err) {
+            process.stderr.write(`queue: warning: failed to scan payload directory for cleanup: ${err instanceof Error ? err.message : String(err)}\n`);
+            return;
+        }
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            const filePath = path.join(dir, file);
+            if (!activePayloadRefs.has(filePath)) {
+                this.deletePayloadPath(filePath, file);
+            }
+        }
+    }
+    deletePayloadPath(filePath, label) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                process.stderr.write(`queue: warning: failed to remove payload file ${label}: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
     }
     /**
      * Find the active job for a given idempotency key.
@@ -219,13 +563,21 @@ export class JobQueue {
         };
         // Rebuild the Map with this job first so findNextQueued() picks it up
         // before any previously queued work.
+        const snapshot = this.snapshotState();
         const entries = [...this.jobs.entries()];
         this.jobs.clear();
         this.jobs.set(job.id, job);
         for (const [id, j] of entries) {
             this.jobs.set(id, j);
         }
-        await this.persist();
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            this.restoreSnapshot(snapshot);
+            this.deletePayloadFilesForJob(job.id);
+            throw err;
+        }
         this.processNext();
         return { job, duplicate: false };
     }
@@ -268,10 +620,18 @@ export class JobQueue {
             retry_of: failed.id,
             ...(opts?.payload !== undefined ? { payload: opts.payload } : {}),
         };
+        const snapshot = this.snapshotState();
         failed.retried_by = retryId;
         failed.updated_at = new Date().toISOString();
         this.jobs.set(retryId, retry);
-        await this.persist();
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            this.restoreSnapshot(snapshot);
+            this.deletePayloadFilesForJob(retryId);
+            throw err;
+        }
         this.processNext();
         return { job: retry, duplicate: false };
     }
@@ -288,25 +648,105 @@ export class JobQueue {
         if (!handler)
             return; // No handler registered — leave queued.
         this.processing = true;
-        next.status = "running";
-        next.updated_at = new Date().toISOString();
-        this.persist().then(() => {
-            handler(next)
-                .then(() => {
-                next.status = "completed";
-                next.updated_at = new Date().toISOString();
-            })
-                .catch((err) => {
-                next.status = "failed";
-                next.error =
-                    err instanceof Error ? err.message : String(err);
-                next.updated_at = new Date().toISOString();
-            })
-                .finally(() => {
+        void (async () => {
+            try {
+                await this.applyPersistedMutation(() => {
+                    next.status = "running";
+                    next.updated_at = new Date().toISOString();
+                });
+            }
+            catch (err) {
                 this.processing = false;
-                this.persist().then(() => this.processNext());
-            });
-        });
+                process.stderr.write(`queue: failed to persist start of job ${next.id}: ${err instanceof Error ? err.message : String(err)}\n`);
+                this.scheduleStartRetry();
+                return;
+            }
+            this.clearStartRetry();
+            try {
+                await handler(next);
+                await this.applyTerminalMutation(`completion of job ${next.id}`, () => {
+                    next.status = "completed";
+                    next.updated_at = new Date().toISOString();
+                });
+            }
+            catch (err) {
+                await this.applyTerminalMutation(`failure of job ${next.id}`, () => {
+                    next.status = "failed";
+                    next.error = err instanceof Error ? err.message : String(err);
+                    next.updated_at = new Date().toISOString();
+                });
+            }
+            finally {
+                this.processing = false;
+                this.processNext();
+            }
+        })();
+    }
+    async applyPersistedMutation(mutator) {
+        const snapshot = this.snapshotState();
+        mutator();
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            this.restoreSnapshot(snapshot);
+            throw err;
+        }
+    }
+    async applyTerminalMutation(label, mutator) {
+        mutator();
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            this.markPersistDirty(label, err);
+        }
+    }
+    markPersistDirty(label, err) {
+        process.stderr.write(`queue: failed to persist ${label}: ${err instanceof Error ? err.message : String(err)}; will retry\n`);
+        this.schedulePersistRetry();
+    }
+    schedulePersistRetry() {
+        if (this.persistRetryTimer)
+            return;
+        this.persistRetryTimer = setTimeout(() => {
+            this.persistRetryTimer = undefined;
+            void this.retryDirtyPersist();
+        }, PERSIST_RETRY_DELAY_MS);
+        this.persistRetryTimer.unref?.();
+    }
+    scheduleStartRetry() {
+        if (this.startRetryTimer)
+            return;
+        const delayMs = this.startRetryDelayMs;
+        this.startRetryDelayMs = Math.min(this.startRetryDelayMs * 2, START_RETRY_MAX_DELAY_MS);
+        this.startRetryTimer = setTimeout(() => {
+            this.startRetryTimer = undefined;
+            this.processNext();
+        }, delayMs);
+        this.startRetryTimer.unref?.();
+    }
+    clearStartRetry() {
+        if (this.startRetryTimer) {
+            clearTimeout(this.startRetryTimer);
+            this.startRetryTimer = undefined;
+        }
+        this.startRetryDelayMs = START_RETRY_INITIAL_DELAY_MS;
+    }
+    clearPersistRetry() {
+        if (!this.persistRetryTimer)
+            return;
+        clearTimeout(this.persistRetryTimer);
+        this.persistRetryTimer = undefined;
+    }
+    async retryDirtyPersist() {
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            process.stderr.write(`queue: failed to retry dirty ledger persist: ${err instanceof Error ? err.message : String(err)}\n`);
+            this.schedulePersistRetry();
+        }
     }
     findNextQueued() {
         for (const job of this.jobs.values()) {