pg-boss 12.32.0 → 12.33.1

package/dist/adapters/pglite.d.ts

@@ -7,6 +7,7 @@ export interface PGliteLike {
         rows: any[];
     }>>;
     listen?(channel: string, callback: (payload: string) => void): Promise<() => Promise<void>>;
+    onLeaderChange?(callback: () => void): () => void;
 }
 export declare function fromPglite(pglite: PGliteLike): IDatabase;
 //# sourceMappingURL=pglite.d.ts.map

package/dist/adapters/pglite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pglite.d.ts","sourceRoot":"","sources":["../../src/adapters/pglite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAM5C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC,CAAA;IACpD,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC5F;AAUD,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CA6CzD"}
+{"version":3,"file":"pglite.d.ts","sourceRoot":"","sources":["../../src/adapters/pglite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAM5C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC,CAAA;IACpD,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3F,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAClD;AAmBD,wBAAgB,UAAU,CAAE,MAAM,EAAE,UAAU,GAAG,SAAS,CAwJzD"}

package/dist/adapters/pglite.js

@@ -1,3 +1,10 @@
+// PGliteWorker's error when leadership moves while a call is in flight. Matched on the message
+// rather than the constructor name: the class is anonymous after bundling, so `name` is just
+// 'Error', while the message is fixed in the worker source.
+const LEADER_CHANGED_MESSAGE = 'Leader changed, pending operation in indeterminate state';
+function isLeaderChange(err) {
+    return err instanceof Error && err.message === LEADER_CHANGED_MESSAGE;
+}
 // Adapts a PGlite instance (embedded single-connection WASM PostgreSQL) to pg-boss's IDatabase.
 // PGlite is full PostgreSQL, so it needs none of the distributed compatibility flags — pair it
 // with `backend: 'pglite'`. The user owns the PGlite instance lifecycle (construction and close).
@@ -23,17 +30,114 @@ export function fromPglite(pglite) {
         const results = await pglite.exec(text);
         return { rows: results.flatMap(r => r.rows ?? []) };
     };
+    // The statements every session must carry, kept so they can be reapplied. A plain PGlite has one
+    // session for the life of the instance and never needs that; PGliteWorker does — see below.
+    let sessionStatements = [];
+    let unsubscribeLeaderChange = null;
+    // While a reapply is in flight, every statement waits for it. Without this a query issued between
+    // the leader change and the reapply lands on a session that has not been set up yet.
+    let reapplying = null;
+    // Statements currently in flight, so a leader change can fail them itself — see executeSql.
+    const inFlight = new Set();
+    // Note what this cannot fix: because one leader instance serves every tab, session state is shared
+    // by all of them. A SET issued through one tab's adapter applies to every other tab's queries
+    // against that database, and there is no way to scope it to the instance that asked for it.
+    //
+    // Only the PGliteWorker leader holds an actual PGlite instance; the other tabs proxy into it. When
+    // the leader tab goes away, the next tab's worker constructs a *new* PGlite over the same data
+    // directory — a new backend, and so a new session. Anything set with SET is gone, and nothing in
+    // the worker replays it, so without this the session would silently revert to defaults: for the
+    // clock override specifically, back to real time with no error anywhere.
+    const watchLeaderChange = () => {
+        if (unsubscribeLeaderChange || typeof pglite.onLeaderChange !== 'function') {
+            return;
+        }
+        unsubscribeLeaderChange = pglite.onLeaderChange(() => {
+            // Fail the in-flight statements first: they were issued against a backend that no longer
+            // exists, and one of them may be holding a reapply behind it.
+            for (const fail of [...inFlight])
+                fail(new Error(LEADER_CHANGED_MESSAGE));
+            if (!sessionStatements.length)
+                return;
+            // Cleared only by the chain that set it: a second leader change during a reapply assigns a
+            // new one, and the first must not open the gate on a session the new chain has not set up.
+            const chain = applySessionStatements().catch(() => { }).then(() => {
+                if (reapplying === chain)
+                    reapplying = null;
+            });
+            reapplying = chain;
+        });
+    };
+    // PGliteWorker settles a statement that was in flight across a leader change only when it was
+    // still queued on the transaction lock: that rejection is raised before _runExclusiveTransaction
+    // enters its try/finally, so it reaches us. A statement that had already *taken* the lock never
+    // settles at all — its own rpc rejects, but the `finally` then posts _releaseTransactionLock to a
+    // tab channel the new leader has not attached to yet, and nothing will ever reply or reject it.
+    // That await swallows the original rejection and hangs forever, which for pg-boss means a
+    // locked() block stalling a maintenance cycle silently and permanently.
+    //
+    // So the leader change fails its own in-flight statements, giving a lock holder the same
+    // indeterminate-state error a queued statement already gets. The abandoned promise is left to
+    // settle or not on its own; only its late rejection has to be swallowed.
+    const raceLeaderChange = async (text, values) => {
+        if (typeof pglite.onLeaderChange !== 'function') {
+            return await run(text, values);
+        }
+        let fail;
+        const lost = new Promise((_resolve, reject) => { fail = reject; });
+        inFlight.add(fail);
+        const statement = run(text, values);
+        statement.catch(() => { });
+        try {
+            return await Promise.race([statement, lost]);
+        }
+        finally {
+            inFlight.delete(fail);
+        }
+    };
+    // Through raceLeaderChange, not run(): a reapply orphaned by a *second* leader change is the
+    // same upstream hang as any other statement, and worse here, because executeSql waits on
+    // `reapplying` - a reapply that never settles stalls the adapter permanently and silently.
+    // Failing it instead leaves the next leader change to reapply from scratch.
+    const applySessionStatements = async () => {
+        for (const statement of sessionStatements) {
+            await raceLeaderChange(statement);
+        }
+    };
     const db = {
+        // A plain PGlite is one session for the life of the instance, so these are applied once and
+        // every later statement sees them. A pooled driver re-runs them per connection; here the only
+        // thing that can take the session away is a PGliteWorker leader change.
+        async setSessionStatements(statements) {
+            sessionStatements = statements;
+            await applySessionStatements();
+        },
         async executeSql(text, values) {
+            // Re-checked, not awaited once: a second leader change during a reapply fails the first
+            // chain's in-flight statement, so that chain settles early and hands the gate back while the
+            // chain that replaced it has not reissued anything yet. Waiting again on whatever is there
+            // now is what keeps a query from reaching a session the current chain has not set up.
+            for (let pending = reapplying; pending; pending = reapplying) {
+                await pending;
+            }
             try {
-                return await run(text, values);
+                return await raceLeaderChange(text, values);
             }
             catch (err) {
-                await pglite.query('ROLLBACK').catch(() => { });
+                // A leader change leaves nothing to roll back on this side: the transaction died with the
+                // old leader's instance, and a ROLLBACK now would go to a different session that was never
+                // in it. The statement's own outcome is genuinely unknown, which is what the error says.
+                if (!isLeaderChange(err)) {
+                    await pglite.query('ROLLBACK').catch(() => { });
+                }
                 throw err;
             }
         }
     };
+    // Taken out once and kept for the adapter's life. It used to be tied to having session statements
+    // to reapply; it now also fails in-flight statements, which every adapter needs whether or not a
+    // TestClock is involved. A plain PGlite has no onLeaderChange and subscribes to nothing.
+    watchLeaderChange();
     // PGlite is embedded single-connection PostgreSQL, so LISTEN/NOTIFY works entirely in-process:
     // the same instance both NOTIFYs (via pg-boss's inlined pg_notify) and delivers to listeners.
     // Only expose `listen` when the instance actually supports it (older builds/mocks may not), so

package/dist/attorney.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAKD,QAAA,MAAM,mBAAmB,uQAaf,CAAA;AA2EV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAgBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CAgCA;AAqBD,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CAyB9F;AAiGD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}
+{"version":3,"file":"attorney.d.ts","sourceRoot":"","sources":["../src/attorney.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC,QAAA,MAAM,MAAM;;;;CAIX,CAAA;AAKD,QAAA,MAAM,mBAAmB,uQAaf,CAAA;AA2EV,iBAAS,iBAAiB,CAAE,MAAM,GAAE,GAAQ,QAc3C;AAgBD,iBAAS,mBAAmB,CAAE,KAAK,EAAE,MAAM,UAE1C;AAED,iBAAS,aAAa,CAAE,IAAI,EAAE,GAAG,GAAG,KAAK,CAAC,OAAO,CAgDhD;AAOD,iBAAS,eAAe,CAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAc,EAAE;;CAAK,GAAG,KAAK,CAAC,OAAO,CA4D3E;AAED,iBAAS,mBAAmB,CAAE,MAAM,EAAE,GAAG,QAOxC;AAED,iBAAS,gBAAgB,CAAE,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,QA2D/C;AA2GD,iBAAS,aAAa,CAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG;IAClD,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAA;IAClC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;CACjC,CAgCA;AAqBD,iBAAS,cAAc,CAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAQlD;AAED,iBAAS,SAAS,CAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,0BAA0B,CA0B9F;AA8GD,iBAAS,wBAAwB,CAAE,IAAI,EAAE,MAAM,QAiC9C;AAED,iBAAS,eAAe,CAAE,IAAI,EAAE,MAAM,QAIrC;AAED,iBAAS,SAAS,CAAE,GAAG,EAAE,MAAM,QAI9B;AA+LD,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,CAAA"}

package/dist/attorney.js

@@ -1,4 +1,5 @@
 import assert from 'node:assert';
+import { systemClock } from "./clock.js";
 import { DEFAULT_SCHEMA } from "./plans.js";
 const POLICY = {
     MAX_EXPIRATION_HOURS: 24,
@@ -409,6 +410,7 @@ function getConfig(value) {
     config.useListenNotify = ('useListenNotify' in config) ? config.useListenNotify : false;
     config.reindex = ('reindex' in config) ? config.reindex : true;
     resolveBackend(config);
+    applyClockConfig(config);
     applySchemaConfig(config);
     applyOpsConfig(config);
     applyScheduleConfig(config);
@@ -417,6 +419,16 @@ function getConfig(value) {
     validateWarningConfig(config);
     return config;
 }
+const CLOCK_METHODS = ['now', 'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval'];
+function applyClockConfig(config) {
+    if (config.clock) {
+        const clock = config.clock;
+        for (const method of CLOCK_METHODS) {
+            assert(typeof clock[method] === 'function', `configuration assert: clock must implement ${method}()`);
+        }
+    }
+    config.clock = config.clock || systemClock;
+}
 function applySchemaConfig(config) {
     if (config.schema) {
         assertPostgresObjectName(config.schema);

package/dist/bam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAOnC,cAAM,GAAI,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAOzD,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAU1C,IAAI,OAAO,IAAK,OAAO,CAEtB;IAEK,KAAK;IAWL,IAAI;CA8HX;AAED,eAAe,GAAG,CAAA"}
+{"version":3,"file":"bam.d.ts","sourceRoot":"","sources":["../src/bam.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAItC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAOnC,cAAM,GAAI,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAOzD,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAU1C,IAAI,OAAO,IAAK,OAAO,CAEtB;IAEK,KAAK;IAcL,IAAI;CAkIX;AAED,eAAe,GAAG,CAAA"}

package/dist/bam.js

@@ -1,4 +1,5 @@
 import EventEmitter from 'node:events';
+import { ClaimTimer } from "./claimTimer.js";
 import * as plans from "./plans.js";
 import { delay } from "./tools.js";
 import * as types from "./types.js";
@@ -9,7 +10,7 @@ const events = {
 class Bam extends EventEmitter {
     #stopped;
     #working;
-    #pollInterval;
+    #pollTimer;
     #db;
     #config;
     events = events;
@@ -27,16 +28,17 @@ class Bam extends EventEmitter {
         if (!this.#stopped)
             return;
         this.#stopped = false;
+        this.#pollTimer = new ClaimTimer(this.#config.clock, this.#config.bamIntervalSeconds, () => this.#onPoll());
         setImmediate(() => this.#onPoll());
-        this.#pollInterval = setInterval(() => this.#onPoll(), this.#config.bamIntervalSeconds * 1000);
+        this.#pollTimer.start();
     }
     async stop() {
         if (this.#stopped)
             return;
         this.#stopped = true;
-        if (this.#pollInterval) {
-            clearInterval(this.#pollInterval);
-            this.#pollInterval = undefined;
+        if (this.#pollTimer) {
+            this.#pollTimer.stop();
+            this.#pollTimer = undefined;
         }
         while (this.#working) {
             await delay(10);
@@ -55,6 +57,9 @@ class Bam extends EventEmitter {
             }
             const sql = plans.trySetBamTime(this.#config.schema, this.#config.bamIntervalSeconds);
             const { rows } = await this.#db.executeSql(sql);
+            // The row is stamped; the next attempt is measured from here rather than from the tick that
+            // started this one. See ClaimTimer.
+            this.#pollTimer?.anchor();
             if (rows.length === 1) {
                 await this.#processCommands();
             }

package/dist/boss.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AACtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgHnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAsC1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAWL,IAAI;IA8FJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAwqBvF;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAwB7E;AAED,eAAe,IAAI,CAAA"}
+{"version":3,"file":"boss.d.ts","sourceRoot":"","sources":["../src/boss.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAGvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAgHnC,cAAM,IAAK,SAAQ,YAAa,YAAW,KAAK,CAAC,WAAW;;IAsC1D,MAAM;;;MAAS;gBAGb,EAAE,EAAE,KAAK,CAAC,SAAS,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,0BAA0B;IAa1C,IAAI,WAAW,IAAK,OAAO,CAE1B;IAEK,KAAK;IAaL,IAAI;IAmGJ,SAAS,CAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,gBAAgB;IAorBvF;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAwB7E;AAED,eAAe,IAAI,CAAA"}

package/dist/boss.js

@@ -1,4 +1,5 @@
 import EventEmitter from 'node:events';
+import { ClaimTimer } from "./claimTimer.js";
 import * as plans from "./plans.js";
 import { delay, unwrapSQLResult } from "./tools.js";
 import * as types from "./types.js";
@@ -75,7 +76,7 @@ class Boss extends EventEmitter {
     #stopped;
     #stopping;
     #maintaining;
-    #superviseInterval;
+    #superviseTimer;
     #db;
     #config;
     #manager;
@@ -125,15 +126,16 @@ class Boss extends EventEmitter {
     async start() {
         if (this.#stopped) {
             this.#stopping = false;
-            this.#superviseInterval = setInterval(() => this.#onSupervise(), this.#config.superviseIntervalSeconds * 1000);
+            this.#superviseTimer = new ClaimTimer(this.#config.clock, this.#config.superviseIntervalSeconds, () => this.#onSupervise());
+            this.#superviseTimer.start();
             this.#stopped = false;
         }
     }
     async stop() {
         if (!this.#stopped) {
             this.#stopping = true;
-            if (this.#superviseInterval)
-                clearInterval(this.#superviseInterval);
+            if (this.#superviseTimer)
+                this.#superviseTimer.stop();
             this.#stopped = true;
             while (this.#maintaining) {
                 await delay(10);
@@ -154,6 +156,7 @@ class Boss extends EventEmitter {
         if (typeof (query) === 'string') {
             query = { text: query, values: [] };
         }
+        // Real time: a stopwatch around I/O reads zero on a frozen clock.
         const started = Date.now();
         const result = unwrapSQLResult(await this.#db.executeSql(query.text, query.values));
         const elapsed = (Date.now() - started) / 1000;
@@ -177,7 +180,11 @@ class Boss extends EventEmitter {
                 await delay(this.#config.__test__delay_maint_ms);
             }
             const queues = await this.#manager.getQueues();
-            !this.#stopped && (await this.supervise(queues));
+            // The timer's own pass is the only one that re-anchors it. A supervise() call from the
+            // application stamps the same claims, but it may be scoped to a single queue, and anchoring
+            // on it would push the background pass - the one that covers every other queue - out by a
+            // full interval each time. An application polling one hot queue would starve the rest.
+            !this.#stopped && (await this.#supervisePass(queues, undefined, () => this.#superviseTimer?.anchor()));
         }
         catch (err) {
             this.emit(events.error, err);
@@ -207,6 +214,11 @@ class Boss extends EventEmitter {
         await this.#executeQuery(sql);
     }
     async supervise(value, options) {
+        await this.#supervisePass(value, options);
+    }
+    // onClaimsSettled fires once every monitor and maintain claim in the pass has been stamped, which
+    // is where the background timer measures its next attempt from. Only #onSupervise passes one.
+    async #supervisePass(value, options, onClaimsSettled) {
         let queues;
         if (Array.isArray(value)) {
             queues = value;
@@ -241,6 +253,11 @@ class Boss extends EventEmitter {
                 await this.#maintain(table, chunk);
             }
         }
+        // Every monitor and maintain claim in this pass has now been stamped, so the next pass is
+        // measured from here rather than from the tick that started this one. See ClaimTimer. Before
+        // the tail below and not at the end of the pass: the tail ends in a rebuild that is DDL and can
+        // run for seconds, and the claims must not be measured from the far side of it.
+        onClaimsSettled?.();
         if (this.#stopping)
             return;
         // Immediately after the aggregates it measures, not at the head of the next pass. Deferring the
@@ -701,9 +718,9 @@ class Boss extends EventEmitter {
                     return;
             }
             else {
-                if (Date.now() < this.#detectOnly)
+                if (this.#config.clock.now() < this.#detectOnly)
                     return;
-                this.#detectOnly = Date.now() + this.#config.reindexIntervalSeconds * 1000;
+                this.#detectOnly = this.#config.clock.now() + this.#config.reindexIntervalSeconds * 1000;
             }
         }
         if (this.#stopping)

package/dist/claimTimer.d.ts

@@ -0,0 +1,44 @@
+import type { Clock } from './types.ts';
+/**
+ * The timer behind an interval claim, anchored to the claim instead of to a fixed grid.
+ *
+ * An interval claim is a conditional UPDATE that only goes through when the row it stamps is at
+ * least `seconds` old by the server's clock, so exactly one instance in a deployment runs the pass
+ * per interval (see plans.trySetTimestamp). Every instance tries on a timer of its own.
+ *
+ * setInterval schedules the next tick from a grid fixed before the callback runs, while the row is
+ * stamped when the UPDATE reaches the server - a moment later by however long the pool wait, the
+ * round trip and the plan took. The two do not move together. When a tick's statement lands faster
+ * than the previous tick's did, the two stamps come out closer together than the period, the claim
+ * is refused, and the pass after it is a whole interval late. Measured on an idle Linux box that is
+ * 4 of 19 ticks at a 45-second period, all of them between 44.990 and 44.998 seconds old, and a
+ * quarter of the queue monitor's passes at its defaults. For the cron pass a lost claim is a
+ * 90-second gap against a 60-second due window, and the occurrences inside it are never sent.
+ *
+ * Anchoring removes the mismatch rather than tolerating it: the next attempt is scheduled once the
+ * claim has been stamped, so the gap between two stamps is the period plus one round trip rather
+ * than the period minus the difference between two of them. It can only ever come out long, never
+ * short, which is the direction that costs nothing - a pass never runs before its interval is up.
+ *
+ * Note what does not appear here: a clock. The claim compares two timestamps that the server wrote,
+ * so the client's clock is already absent from it and skew between the two cancels exactly. There
+ * is nothing for a skew correction to correct, which is why the fix is in when the attempt is made
+ * rather than in what it is measured against.
+ *
+ * `anchor()` is what a pass calls once its claim has been stamped. A pass that returns without ever
+ * reaching its claim - stopped, already working, an error on the way in - is re-armed from the end
+ * of the callback instead, so the chain cannot die on a path that never anchored it.
+ */
+export declare class ClaimTimer {
+    #private;
+    constructor(clock: Clock, seconds: number, fn: () => Promise<void>);
+    start(): void;
+    stop(): void;
+    /**
+     * Re-anchors the next attempt to now, because the claim this timer drives has just been stamped.
+     * Called whether the claim was won or lost: the winner needs its next attempt to fall after its
+     * own stamp, and a loser's phase is its own business either way.
+     */
+    anchor(): void;
+}
+//# sourceMappingURL=claimTimer.d.ts.map

package/dist/claimTimer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimTimer.d.ts","sourceRoot":"","sources":["../src/claimTimer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAc,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,UAAU;;gBASR,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAMnE,KAAK,IAAK,IAAI;IAOd,IAAI,IAAK,IAAI;IAKb;;;;OAIG;IACH,MAAM,IAAK,IAAI;CAwChB"}

package/dist/claimTimer.js

@@ -0,0 +1,95 @@
+/**
+ * The timer behind an interval claim, anchored to the claim instead of to a fixed grid.
+ *
+ * An interval claim is a conditional UPDATE that only goes through when the row it stamps is at
+ * least `seconds` old by the server's clock, so exactly one instance in a deployment runs the pass
+ * per interval (see plans.trySetTimestamp). Every instance tries on a timer of its own.
+ *
+ * setInterval schedules the next tick from a grid fixed before the callback runs, while the row is
+ * stamped when the UPDATE reaches the server - a moment later by however long the pool wait, the
+ * round trip and the plan took. The two do not move together. When a tick's statement lands faster
+ * than the previous tick's did, the two stamps come out closer together than the period, the claim
+ * is refused, and the pass after it is a whole interval late. Measured on an idle Linux box that is
+ * 4 of 19 ticks at a 45-second period, all of them between 44.990 and 44.998 seconds old, and a
+ * quarter of the queue monitor's passes at its defaults. For the cron pass a lost claim is a
+ * 90-second gap against a 60-second due window, and the occurrences inside it are never sent.
+ *
+ * Anchoring removes the mismatch rather than tolerating it: the next attempt is scheduled once the
+ * claim has been stamped, so the gap between two stamps is the period plus one round trip rather
+ * than the period minus the difference between two of them. It can only ever come out long, never
+ * short, which is the direction that costs nothing - a pass never runs before its interval is up.
+ *
+ * Note what does not appear here: a clock. The claim compares two timestamps that the server wrote,
+ * so the client's clock is already absent from it and skew between the two cancels exactly. There
+ * is nothing for a skew correction to correct, which is why the fix is in when the attempt is made
+ * rather than in what it is measured against.
+ *
+ * `anchor()` is what a pass calls once its claim has been stamped. A pass that returns without ever
+ * reaching its claim - stopped, already working, an error on the way in - is re-armed from the end
+ * of the callback instead, so the chain cannot die on a path that never anchored it.
+ */
+export class ClaimTimer {
+    #clock;
+    #ms;
+    #fn;
+    #handle;
+    #stopped = true;
+    #anchored = false;
+    constructor(clock, seconds, fn) {
+        this.#clock = clock;
+        this.#ms = seconds * 1000;
+        this.#fn = fn;
+    }
+    start() {
+        if (!this.#stopped)
+            return;
+        this.#stopped = false;
+        this.#arm();
+    }
+    stop() {
+        this.#stopped = true;
+        this.#disarm();
+    }
+    /**
+     * Re-anchors the next attempt to now, because the claim this timer drives has just been stamped.
+     * Called whether the claim was won or lost: the winner needs its next attempt to fall after its
+     * own stamp, and a loser's phase is its own business either way.
+     */
+    anchor() {
+        if (this.#stopped)
+            return;
+        this.#anchored = true;
+        this.#arm();
+    }
+    #arm() {
+        this.#disarm();
+        if (this.#stopped)
+            return;
+        this.#handle = this.#clock.setTimeout(() => { this.#run(); }, this.#ms);
+    }
+    #disarm() {
+        if (this.#handle !== undefined) {
+            this.#clock.clearTimeout(this.#handle);
+            this.#handle = undefined;
+        }
+    }
+    async #run() {
+        this.#handle = undefined;
+        this.#anchored = false;
+        // Deliberately not caught. Every pass this drives ends its own catch in an error event, so the
+        // only rejection that reaches here is one that could not be reported - an error event with
+        // nothing listening, which EventEmitter throws on. That belongs to the process, the way it did
+        // when these ran on setInterval; a timer that turned it into anything else would be inventing a
+        // failure mode for the host to handle. What the timer does owe is the chain, and finally pays
+        // that whether the pass resolved or not.
+        try {
+            await this.#fn();
+        }
+        finally {
+            // A pass that reached its claim already armed the next attempt through anchor(); this is the
+            // path for one that did not, including one that threw.
+            if (!this.#anchored)
+                this.#arm();
+        }
+    }
+}

package/dist/cli.js

@@ -39,6 +39,8 @@ Options:
                           Non-postgres backends need this to emit schema they accept.
   --dry-run               Output SQL without executing (for plans and reindex commands)
   --force                 Rebuild every job index, not just the bloated ones (reindex)
+  --fix                   Restore a job_now() left overridden by a killed TestClock run
+                          (doctor). Only run this when no instance holds a live TestClock.
 
 Environment Variables:
   PGBOSS_DATABASE_URL     Full connection string
@@ -161,7 +163,8 @@ function parseCliArgs() {
             ssl: { type: 'boolean' },
             backend: { type: 'string' },
             'dry-run': { type: 'boolean' },
-            force: { type: 'boolean' }
+            force: { type: 'boolean' },
+            fix: { type: 'boolean' }
         },
         allowPositionals: true
     });
@@ -179,6 +182,7 @@ function parseCliArgs() {
         backend: values.backend,
         dryRun: values['dry-run'],
         force: values.force,
+        fix: values.fix,
         command: positionals[0],
         subCommand: positionals[1]
     };
@@ -385,7 +389,32 @@ async function cmdDoctor(args) {
         // carried divergent best-effort/backend-gating bugs). Contractor.detectDrift handles the
         // partitioned probe, best-effort catalog fallbacks, and backend-specific gating in one place.
         const contractor = new Contractor(db, { ...config, schema });
-        const report = await contractor.detectDrift();
+        let report = await contractor.detectDrift();
+        // --fix repairs exactly one cause of drift, and only when asked. A TestClock restores job_now()
+        // when its handle is disposed, so a run killed first leaves the override installed; but a
+        // leftover override is indistinguishable from one a peer instance is holding right now, which is
+        // why this cannot be done automatically at startup. An operator knows which it is. Everything
+        // else doctor finds is reported and never repaired.
+        if (args.fix) {
+            // The drift report is the first source, but not the only one: mismatchedFunctions comes from
+            // pg_get_functiondef, and the whole function check is skipped when that query is unsupported
+            // (CockroachDB). detectClockOverride() reads prosrc instead, so a leftover override is still
+            // found - and repaired - on a backend whose functions never reach the report at all.
+            const override = report.mismatchedFunctions.some(f => f.name === 'job_now' && plans.clockFunctionIsOverridden(f.actualDefinition)) ||
+                await contractor.detectClockOverride();
+            if (override) {
+                console.log('\njob_now() carries a TestClock override, left behind by a test run that was');
+                console.log('killed before releasing its clock. Restoring it — make sure no instance is');
+                console.log('holding a live TestClock against this schema.');
+                await contractor.restoreClockFunction();
+                console.log('  restored.');
+                // Report on the repaired schema, so the summary and the exit code describe what is there now.
+                report = await contractor.detectDrift();
+            }
+            else {
+                console.log('\nNothing for --fix to repair: job_now() carries no TestClock override.');
+            }
+        }
         if (report.building.length) {
             console.log(`\nBuilding (async index build in progress — not yet drift) (${report.building.length}):`);
             for (const i of report.building)
@@ -461,6 +490,14 @@ async function cmdDoctor(args) {
                 console.log(`    expected: ${f.definition}`);
             }
         }
+        let clockOverrideNamed = false;
+        const printClockOverrideHint = (marker) => {
+            console.log(`\n${marker}job_now() carries a TestClock override, left behind by a test run that was`);
+            console.log('  killed before releasing its clock. Time is still correct, but the function no');
+            console.log('  longer inlines, so every statement that reads the clock is slower. Restore it');
+            console.log('  with "pg-boss doctor --fix", or by hand:');
+            console.log(plans.restoreClockFunction(schema).split('\n').filter(l => l.trim()).map(l => `    ${l.trim()}`).join('\n'));
+        };
         if (report.mismatchedFunctions.length) {
             console.log(`\nMISMATCHED FUNCTIONS (body differs) (${report.mismatchedFunctions.length}):`);
             for (const f of report.mismatchedFunctions) {
@@ -468,6 +505,23 @@ async function cmdDoctor(args) {
                 console.log(`    expected: ${f.definition}`);
                 console.log(`    actual:   ${f.actualDefinition}`);
             }
+            // One cause of a job_now() mismatch is common and self-inflicted: a TestClock only restores
+            // the function when its handle is disposed, so a killed run leaves the override installed.
+            // The body still returns real time for a session that never opted in, which is why nothing
+            // surfaces it at runtime - but it no longer inlines, so every statement that reads the clock
+            // pays a per-row call. Name it rather than leave an operator to read two bodies and guess.
+            const clockOverride = report.mismatchedFunctions.find(f => f.name === 'job_now' && plans.clockFunctionIsOverridden(f.actualDefinition));
+            if (clockOverride) {
+                clockOverrideNamed = true;
+                printClockOverrideHint('  ');
+            }
+        }
+        // Same hint for a backend that never produced function rows to mismatch: the check above is
+        // gated on pg_get_functiondef, which CockroachDB does not support, so the override is invisible
+        // to drift there. This probe reads prosrc and finds it anyway. It is not drift the report can
+        // show a body for, so it names the condition and stops short of printing an "actual:".
+        if (!clockOverrideNamed && await contractor.detectClockOverride()) {
+            printClockOverrideHint('⚠ ');
         }
         if (report.columnDrift.length) {
             console.log(`\nCOLUMN DRIFT (missing/unexpected columns, or default/type/nullability drift) (${report.columnDrift.length}):`);

package/dist/clock.d.ts

@@ -0,0 +1,31 @@
+import type { AttachableClock, Clock, ClockTimer, IDatabase } from './types.ts';
+export declare const systemClock: Clock;
+export declare function isAttachable(clock: Clock): clock is AttachableClock;
+interface Target {
+    db: IDatabase;
+    schema: string;
+}
+/**
+ * A clock a test drives by hand. Time only moves through setTime() and tick(); timers only fire
+ * from tick(). When attached to a schema, every pg-boss statement there reads the same time
+ * through ${schema}.job_now(), so JavaScript and Postgres agree on what "now" is.
+ */
+export declare class TestClock implements AttachableClock {
+    #private;
+    constructor(start?: Date | number | string);
+    now(): number;
+    setTimeout(fn: () => void, ms: number): ClockTimer;
+    setInterval(fn: () => void, ms: number): ClockTimer;
+    clearTimeout(handle: ClockTimer): void;
+    clearInterval(handle: ClockTimer): void;
+    /** Jumps to a time, forwards or backwards, firing nothing. */
+    setTime(t: Date | number | string): Promise<void>;
+    /**
+     * Advances by ms, firing each due timer in order at its own due time. Does not wait for I/O the
+     * callbacks start; observe effects with spies or by querying.
+     */
+    tick(ms: number): Promise<void>;
+    attach(target: Target): Promise<AsyncDisposable>;
+}
+export {};
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/E,eAAO,MAAM,WAAW,EAAE,KAMzB,CAAA;AAED,wBAAgB,YAAY,CAAE,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAEpE;AASD,UAAU,MAAM;IACd,EAAE,EAAE,SAAS,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAUD;;;;GAIG;AACH,qBAAa,SAAU,YAAW,eAAe;;gBAWlC,KAAK,GAAE,IAAI,GAAG,MAAM,GAAG,MAAmB;IAIvD,GAAG,IAAK,MAAM;IAId,UAAU,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAInD,WAAW,CAAE,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAIpD,YAAY,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAKvC,aAAa,CAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC,8DAA8D;IACxD,OAAO,CAAE,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD;;;OAGG;IACG,IAAI,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsChC,MAAM,CAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CA4ExD"}