@stonyx/cron 0.2.1-alpha.45 → 0.2.1-alpha.46

package/README.md

@@ -35,34 +35,20 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 |  `register`  | `key: string, callback: Function, interval: number, runOnInit?: boolean` | Register a new job with a given interval in seconds. If `runOnInit` is true, the job runs immediately upon registration. |
 | `unregister` |                               `key: string`                              | Remove a previously registered job.                                                                                      |
 
-> **Callback semantics.** Callbacks are invoked fire-and-forget: `Cron` never waits for one to settle, and reschedules a job *before* invoking it. Two *different* jobs that fall due on the same tick may therefore overlap.
->
-> A job that is still running when it next falls due is skipped — and **keeps** being skipped until that invocation settles. `Cron` provides no timeout by design, so **bounding your own callback is your responsibility**: a promise that never settles means that job never runs again for the lifetime of the process, even though the scheduler stays healthy and the job stays visible in `jobs` and in the heap. Other jobs are unaffected.
->
-> One warning is emitted per stuck run (not per tick), including how long the invocation has been running. That warning goes to `log.warn` and is **not** gated by `config.cron.log` — a dropped execution reported on a channel a config flag can silence would be indistinguishable from a healthy scheduler.
->
-> The same-job guarantee holds for the lifetime of a **registration**, not of a key: `unregister` followed by `register` on a key whose invocation is still in flight builds a fresh job object with a fresh guard, so the replacement can run alongside the abandoned invocation. That is also the only way to recover a permanently stuck job.
->
-> Synchronous throws and asynchronous rejections are both caught and reported through `log.error`, with the error's stack interpolated into the message. Neither can stop the scheduler. Note that a rejection which previously escaped `register()` as an unhandled rejection — process-fatal under Node's default — is now swallowed into `log.error`.
-
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
 ## Configuration
 
-Optionally, informational logging and debugging can be controlled through `config.cron`:
+Optionally, logging and debugging can be enabled through `config.cron`:
 
 ```js
 config.cron = {
-  log: true // informational cron job logs; defaults to true
+  log: true // enable cron job logs
 };
 
 config.debug = true; // optional: debug logs for job registration and execution
 ```
 
-`config.cron.log` gates **informational** messages only. Error reports and the
-stuck-job warning described above are never gated by it, so setting it to `false`
-cannot make a dropped execution silent.
-
 ## License
 
 Apache — do what you want, just keep attribution.

package/dist/main.d.ts

@@ -3,24 +3,6 @@ interface CronJob extends HeapItem {
     callback: () => void | Promise<void>;
     interval: string;
     key: string;
-    /**
-     * Timestamp (ms) at which the current invocation started; `undefined` when the
-     * job is idle. Optional so the emitted `CronJob` stays assignable from a job
-     * object built by a consumer — `jobs`, `heap` and `setNextTrigger` all expose
-     * this interface structurally, so a required field is a breaking type change.
-     *
-     * A timestamp rather than a boolean, mirroring `job.state.runningAtMs` in the
-     * service tier (`markRunning` / `applyResult` / `isDue` in `src/job.ts`), and
-     * carrying the one fact a stuck-job warning needs: how long it has been stuck.
-     * `CronService.running` is a class-level re-entrancy flag and a different
-     * concept; reusing that word here would collide.
-     */
-    runningAtMs?: number;
-    /**
-     * True once a skip has been reported for the *current* invocation. Bounds the
-     * still-running warning to one line per stuck run instead of one per tick.
-     */
-    skipReported?: boolean;
 }
 export default class Cron {
     static instance: Cron | null;
@@ -33,33 +15,6 @@ export default class Cron {
     runDueJobs(): Promise<void>;
     register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
     unregister(key: string): void;
-    /**
-     * The one place this class invokes a consumer callback.
-     *
-     * Never blocks the caller, catches synchronous throws and asynchronous
-     * rejections identically, and skips the invocation entirely while the job's
-     * previous invocation has not settled (fire-and-forget would otherwise let a
-     * slow job stack invocations on itself).
-     *
-     * Everything that touches the callback — including the thenable probe and the
-     * handler attachment — is inside the `try`. A callback may return an object
-     * whose `then` is a throwing getter, and reading it outside the guard would
-     * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
-     */
-    invokeJob(job: CronJob, runOnInit?: boolean): void;
-    /**
-     * Report a scheduler-level message without ever letting the logger's own
-     * failure reach the caller.
-     *
-     * `@stonyx/logs` convenience methods return a promise and write to disk
-     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
-     * log volume that promise rejects; an unobserved rejection raised from inside
-     * the handler that exists to prevent unhandled rejections would re-create
-     * exactly the defect this class was fixed for.
-     */
-    report(level: 'error' | 'warn', message: string): void;
-    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
-    release(job: CronJob): void;
     setNextTrigger(job: CronJob): void;
     log(text: string, key?: string | null): void;
 }

package/dist/main.js

@@ -17,30 +17,6 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { getTimestamp } from '@stonyx/utils/date';
 import MinHeap from './min-heap.js';
-/**
- * Render an unknown thrown value as log text.
- *
- * `@stonyx/logs` reads a second argument as `logToFile`, not as a format
- * argument, so `log.error(message, err)` discards the error entirely *and*
- * forces a disk write on every failure. The error has to be interpolated into
- * the message instead — the shape `CronService.executeJob` already uses.
- */
-function describeError(err) {
-    if (err instanceof Error)
-        return err.stack ?? `${err.name}: ${err.message}`;
-    return String(err);
-}
-/**
- * Render a consumer-supplied job key safely for log output.
- *
- * Keys reach the log verbatim, so a key containing a newline can forge a
- * complete, well-formed log line (`'a:\n[FORGED] Cron::admin - all jobs
- * healthy'`). `JSON.stringify` quotes the value and escapes the control
- * characters, which is also how the key is rendered one tier up.
- */
-function describeKey(key) {
-    return JSON.stringify(key);
-}
 export default class Cron {
     static instance;
     jobs = {};
@@ -67,41 +43,28 @@ export default class Cron {
         if (!nextJob)
             return;
         const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
-        // Terminal catch: `runDueJobs` is async, so anything that escapes it would
-        // otherwise become an unhandled rejection raised from a bare timer callback
-        // — the very failure mode this class was fixed for.
-        this.timer = setTimeout(() => {
-            this.runDueJobs().catch((err) => {
-                this.report('error', `Cron scheduler tick failed: ${describeError(err)}`);
-            });
-        }, delay);
+        this.timer = setTimeout(() => this.runDueJobs(), delay);
     }
     async runDueJobs() {
         const now = getTimestamp();
         const { heap } = this;
-        // `finally`, not a trailing statement: `scheduleNextRun()` running on every
-        // exit from the drain loop is the invariant this whole fix is about. If
-        // anything in the loop body ever throws, the scheduler must still re-arm
-        // rather than stopping silently while `timer` still holds a fired handle.
-        try {
-            while (!heap.isEmpty()) {
-                const next = heap.peek();
-                if (!next || next.nextTrigger > now)
-                    break;
-                const job = heap.pop();
-                if (config.debug)
-                    this.log('job has been triggered', job.key);
-                // Reschedule before invoking: a consumer callback is never awaited here,
-                // so a callback that hangs or rejects can no longer starve the drain loop
-                // or leave the job orphaned outside the heap.
-                this.setNextTrigger(job);
-                heap.push(job);
-                this.invokeJob(job);
+        while (!heap.isEmpty()) {
+            const next = heap.peek();
+            if (!next || next.nextTrigger > now)
+                break;
+            const job = heap.pop();
+            if (config.debug)
+                this.log('job has been triggered', job.key);
+            try {
+                await job.callback();
             }
+            catch (err) {
+                log.error(`Cron job "${job.key}" failed:`, err);
+            }
+            this.setNextTrigger(job);
+            heap.push(job);
         }
-        finally {
-            this.scheduleNextRun();
-        }
+        this.scheduleNextRun();
     }
     register(key, callback, interval, runOnInit = false) {
         const job = { callback, interval, key, nextTrigger: 0 };
@@ -111,8 +74,14 @@ export default class Cron {
         if (config.debug) {
             this.log(`job has been registered with interval: ${interval}`, key);
         }
-        if (runOnInit)
-            this.invokeJob(job, true);
+        if (runOnInit) {
+            try {
+                callback();
+            }
+            catch (err) {
+                log.error(`Cron job "${key}" failed on init:`, err);
+            }
+        }
         this.scheduleNextRun();
     }
     unregister(key) {
@@ -126,104 +95,13 @@ export default class Cron {
             this.log('job has been unregistered', key);
         this.scheduleNextRun();
     }
-    /**
-     * The one place this class invokes a consumer callback.
-     *
-     * Never blocks the caller, catches synchronous throws and asynchronous
-     * rejections identically, and skips the invocation entirely while the job's
-     * previous invocation has not settled (fire-and-forget would otherwise let a
-     * slow job stack invocations on itself).
-     *
-     * Everything that touches the callback — including the thenable probe and the
-     * handler attachment — is inside the `try`. A callback may return an object
-     * whose `then` is a throwing getter, and reading it outside the guard would
-     * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
-     */
-    invokeJob(job, runOnInit = false) {
-        const { key } = job;
-        const context = runOnInit ? 'failed on init:' : 'failed:';
-        // The in-flight guard lives on the job object, not in a module-level set
-        // keyed by string. Object identity is invocation identity: the only thing
-        // that clears the guard is the settle handler of the invocation that set it,
-        // and that handler closes over this exact job object, so a stale handler can
-        // never release a later invocation's guard.
-        if (job.runningAtMs !== undefined) {
-            // Bounded to one line per stuck run, not one per tick. A permanently hung
-            // job is re-pushed and re-skipped every interval forever; at the 1s
-            // interval this class's own tests use that measures 43,200 lines/day per
-            // job — a disk-fill and ingest-cost vector whose natural operator response
-            // is to silence the only signal that the job is dead.
-            if (!job.skipReported) {
-                job.skipReported = true;
-                const runningForSeconds = Math.max(0, Math.round((Date.now() - job.runningAtMs) / 1000));
-                // Ungated, deliberately, matching the sibling `CronService` handler. A
-                // skipped run is a *lost* execution, and `runDueJobs`/`register` both
-                // return `void`, so this is the legacy class's only wedged-job channel.
-                // Routing it through `this.log` would put it behind `config.cron.log`,
-                // where a permanently dead job is indistinguishable from a healthy one.
-                this.report('warn', `Cron job ${describeKey(key)} is still running after ${runningForSeconds}s; skipping this `
-                    + 'tick and any further ticks until it settles (this warning is not repeated for this run)');
-            }
-            return;
-        }
-        job.runningAtMs = Date.now();
-        job.skipReported = false;
-        try {
-            const result = job.callback();
-            if (result && typeof result.then === 'function') {
-                Promise.resolve(result)
-                    .catch((err) => {
-                    // Braces matter: returning `report`'s value would put it back into
-                    // the chain, and `.finally` passes a rejection straight through.
-                    this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
-                })
-                    .finally(() => { this.release(job); })
-                    // Backstop: a throw inside the error handler or the release must not
-                    // re-create the unhandled rejection this helper exists to prevent.
-                    .catch(() => { });
-                return;
-            }
-            this.release(job);
-        }
-        catch (err) {
-            this.release(job);
-            this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
-        }
-    }
-    /**
-     * Report a scheduler-level message without ever letting the logger's own
-     * failure reach the caller.
-     *
-     * `@stonyx/logs` convenience methods return a promise and write to disk
-     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
-     * log volume that promise rejects; an unobserved rejection raised from inside
-     * the handler that exists to prevent unhandled rejections would re-create
-     * exactly the defect this class was fixed for.
-     */
-    report(level, message) {
-        try {
-            const result = level === 'error' ? log.error(message) : log.warn(message);
-            void Promise.resolve(result).catch(() => { });
-        }
-        catch {
-            // Nowhere left to report to; the logger must never stop the scheduler.
-        }
-    }
-    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
-    release(job) {
-        job.runningAtMs = undefined;
-        job.skipReported = false;
-    }
     setNextTrigger(job) {
         job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
     }
     log(text, key = null) {
         if (!config.cron?.log)
             return;
-        // The key is consumer-controlled and reaches the log verbatim. Strip the
-        // line terminators so a key cannot forge a second, well-formed log line;
-        // the surrounding format is unchanged.
-        const tag = key ? `Cron::${key.replace(/[\r\n]+/g, ' ')}` : `Cron`;
+        const tag = key ? `Cron::${key}` : `Cron`;
         log.cron(`${tag} - ${text}:`);
     }
 }

package/dist/service.d.ts

@@ -15,7 +15,8 @@ interface ExecuteResult {
     summary?: string;
     durationMs?: number;
     deleted?: boolean;
-    reason?: string;
+    /** Only set when `status` is `'skipped'`. */
+    reason?: 'not due' | 'already running' | 'removed';
 }
 interface ServiceStatus {
     started: boolean;
@@ -27,6 +28,7 @@ interface ListOptions {
 }
 type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
 export default class CronService {
+    #private;
     jobs: Map<string, Job>;
     heap: MinHeap<HeapEntry>;
     timer: ReturnType<typeof setTimeout> | null;
@@ -69,6 +71,21 @@ export default class CronService {
     remove(id: string): Promise<void>;
     /**
      * Manually trigger a job.
+     *
+     * Returns `{ status: 'skipped', reason }` without invoking the callback when
+     * the job is not due (`mode: 'due'`), is already in flight
+     * (`'already running'`), or was removed before the claim landed
+     * (`'removed'`). Before the phase split, a forced run against an in-flight
+     * job launched a second concurrent invocation.
+     *
+     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
+     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
+     * across DIFFERENT jobs is deliberately unbounded — N concurrent `run()`
+     * calls produce N concurrent consumer callbacks. Before the phase split
+     * these serialized behind the module-global lock; that serialization was the
+     * bug rather than the feature (one hung callback wedged every other caller),
+     * so it is not restored here. The fan-out is caller-driven and the scheduler
+     * never produces it on its own.
      */
     run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
     /**
@@ -78,6 +95,25 @@ export default class CronService {
     armTimer(): void;
     onTimer(): Promise<void>;
     findDueJobs(nowMs: number): Job[];
+    /**
+     * Execute a job in three phases:
+     *
+     *   1. claim  (locked)   — take ownership of the job, detach it from the heap
+     *   2. invoke (UNLOCKED) — await the consumer callback
+     *   3. settle (locked)   — apply the result, log it, re-insert into the heap
+     *
+     * The critical section deliberately excludes phase 2. `onJobDue` is
+     * arbitrary, unbounded consumer code; awaiting it under the module-global
+     * lock is what wedged every subsequent `locked()` call (add/update/remove)
+     * when a callback never settled.
+     *
+     * `onTimer` performs the batch claim (`findDueJobs` + `markRunning`) for all
+     * due jobs under a single lock and then enters at phase 2 via
+     * `#executeClaimed`. That entry point is `#private` rather than a parameter
+     * on this method: as a published `alreadyClaimed` flag it would be a
+     * supported way to skip phase 1 entirely, defeating the claim guard and
+     * allowing concurrent `onJobDue` invocations for the same job.
+     */
     executeJob(job: Job): Promise<ExecuteResult>;
     removeFromHeap(id: string): void;
     log(message: string): void;

package/dist/service.js

@@ -12,6 +12,24 @@ import { locked } from './locked.js';
 import { normalizeJobInput, recoverFlatParams } from './normalize.js';
 import RunLog from './run-log.js';
 const MAX_TIMER_DELAY_MS = 60_000;
+/**
+ * Describe a thrown value without ever throwing.
+ *
+ * `String(err)` is not total: a null-prototype object, or any object whose
+ * `toString`/`Symbol.toPrimitive` throws, raises "Cannot convert object to
+ * primitive value". Consumer callbacks throw arbitrary values, so the error
+ * handler must not become a second failure source of its own.
+ */
+function describeError(err) {
+    if (err instanceof Error)
+        return err.message;
+    try {
+        return String(err);
+    }
+    catch {
+        return 'unknown error';
+    }
+}
 export default class CronService {
     jobs;
     heap;
@@ -40,6 +58,23 @@ export default class CronService {
         this.started = true;
         if (initialJobs) {
             for (const job of initialJobs) {
+                // A `runningAtMs` on a rehydrated job is always stale. The claim it
+                // records was taken by a process that is gone, so nothing will ever
+                // settle it, and nothing reaps it — there is no lease on the field
+                // (tracked on #35). Left in place it is a permanently dead job that
+                // still reports healthy: `isDue` returns false forever because of the
+                // flag, `run()` answers `'already running'` forever, `update()` never
+                // touches `state.runningAtMs`, and `status()` counts it like any other.
+                // The consumer's only recovery would be remove() + add(), losing the
+                // job id and its run history.
+                //
+                // Same hazard, same treatment as the hand-release on the `'removed'`
+                // path in `#executeClaimed`: a claim with no reachable settle must be
+                // released. Assigned directly rather than via `applyResult` for the same
+                // reason — this releases the claim and nothing else. The job did not
+                // run, so it gets no run-log row, no `lastStatus`, and no recomputed
+                // `nextRunAtMs`; it is rescheduled from the store's own value below.
+                job.state.runningAtMs = undefined;
                 this.jobs.set(job.id, job);
                 if (job.enabled && job.state.nextRunAtMs) {
                     this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
@@ -136,6 +171,21 @@ export default class CronService {
     }
     /**
      * Manually trigger a job.
+     *
+     * Returns `{ status: 'skipped', reason }` without invoking the callback when
+     * the job is not due (`mode: 'due'`), is already in flight
+     * (`'already running'`), or was removed before the claim landed
+     * (`'removed'`). Before the phase split, a forced run against an in-flight
+     * job launched a second concurrent invocation.
+     *
+     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
+     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
+     * across DIFFERENT jobs is deliberately unbounded — N concurrent `run()`
+     * calls produce N concurrent consumer callbacks. Before the phase split
+     * these serialized behind the module-global lock; that serialization was the
+     * bug rather than the feature (one hung callback wedged every other caller),
+     * so it is not restored here. The fan-out is caller-driven and the scheduler
+     * never produces it on its own.
      */
     async run(id, mode = 'force') {
         const job = this.jobs.get(id);
@@ -144,6 +194,10 @@ export default class CronService {
         if (mode === 'due' && !isDue(job, Date.now())) {
             return { status: 'skipped', reason: 'not due' };
         }
+        // Deliberately NOT wrapped in locked(): executeJob takes the lock itself,
+        // for its claim and settle phases only. Wrapping here would re-create the
+        // wedge through a second door, because the consumer callback would once
+        // again be awaited while a lock is held.
         return this.executeJob(job);
     }
     /**
@@ -172,16 +226,65 @@ export default class CronService {
         }
         this.running = true;
         try {
-            await locked(async () => {
+            // -- Phase 1: claim (locked), batched --
+            // Collecting due jobs pops them off the heap, and marking them running
+            // makes them un-claimable by anyone else. Both must happen under the
+            // same lock turn, or a concurrent run() could claim a job this batch has
+            // already detached.
+            const dueJobs = await locked(() => {
                 const nowMs = Date.now();
-                const dueJobs = this.findDueJobs(nowMs);
-                for (const job of dueJobs) {
+                const due = this.findDueJobs(nowMs);
+                for (const job of due) {
                     markRunning(job);
                 }
-                for (const job of dueJobs) {
-                    await this.executeJob(job);
-                }
+                return due;
             });
+            // Phases 2 and 3 run OUTSIDE the claim lock. The consumer callback is
+            // awaited here holding no lock at all, so a callback that never settles
+            // cannot poison the lock chain and wedge add/update/remove.
+            for (const job of dueJobs) {
+                try {
+                    await this.#executeClaimed(job);
+                }
+                catch (err) {
+                    // One job's unexpected throw must not abort the batch. Every job in
+                    // `dueJobs` is already claimed — marked running and detached from
+                    // the heap — and only its own settle releases it, so aborting here
+                    // would strand every sibling permanently un-due.
+                    //
+                    // Reported on an UNGATED channel. `this.log()` returns early when
+                    // `config.cron.log` is false, which is a supported production
+                    // setting, and a failure here permanently unschedules a job while
+                    // `status()` keeps reporting the service healthy. Silent-and-healthy
+                    // is exactly the failure class this split exists to remove.
+                    //
+                    // This is the outermost handler on the timer path, so it is the one
+                    // that must not be able to throw: `log` is a shared singleton whose
+                    // transports can reach the filesystem, so its own failure is
+                    // swallowed rather than allowed to take the batch down.
+                    //
+                    // BOTH halves of that failure have to be caught, and they are caught
+                    // by different constructs. `log.error` is a chronicle convenience
+                    // method that returns `logAction(...)` -> `async log(...)`, so its
+                    // console write, colour lookup, `mkdirSync` and `appendFile` all
+                    // surface as REJECTIONS, never as synchronous throws. A bare call
+                    // here escapes this `catch` entirely and terminates the process under
+                    // Node's default `--unhandled-rejections=throw` — the handler written
+                    // so it "must not be able to throw" would be the one taking the
+                    // daemon down. The `try` covers the synchronous half (evaluating the
+                    // template literal); `Promise.resolve(...).catch()` covers the async
+                    // half. Deliberately not awaited: the batch must not block on a log
+                    // transport, and `void` marks the floated promise as intentional.
+                    try {
+                        void Promise.resolve(log.error(`Cron — Job "${job.name}" (${job.id}) execution failed unexpectedly: ${describeError(err)}`)).catch(() => {
+                            // Nothing left to report to.
+                        });
+                    }
+                    catch {
+                        // Nothing left to report to.
+                    }
+                }
+            }
         }
         finally {
             this.running = false;
@@ -202,50 +305,190 @@ export default class CronService {
         }
         return due;
     }
+    /**
+     * Execute a job in three phases:
+     *
+     *   1. claim  (locked)   — take ownership of the job, detach it from the heap
+     *   2. invoke (UNLOCKED) — await the consumer callback
+     *   3. settle (locked)   — apply the result, log it, re-insert into the heap
+     *
+     * The critical section deliberately excludes phase 2. `onJobDue` is
+     * arbitrary, unbounded consumer code; awaiting it under the module-global
+     * lock is what wedged every subsequent `locked()` call (add/update/remove)
+     * when a callback never settled.
+     *
+     * `onTimer` performs the batch claim (`findDueJobs` + `markRunning`) for all
+     * due jobs under a single lock and then enters at phase 2 via
+     * `#executeClaimed`. That entry point is `#private` rather than a parameter
+     * on this method: as a published `alreadyClaimed` flag it would be a
+     * supported way to skip phase 1 entirely, defeating the claim guard and
+     * allowing concurrent `onJobDue` invocations for the same job.
+     */
     async executeJob(job) {
+        // -- Phase 1: claim (locked) --
+        const refusal = await locked(() => this.#claimJob(job));
+        if (refusal)
+            return { status: 'skipped', reason: refusal };
+        return this.#executeClaimed(job);
+    }
+    /**
+     * Phases 2 and 3 for a job that has already been claimed — either by
+     * `executeJob` above or by `onTimer`'s batch claim.
+     *
+     * Private: reaching this without a claim would run the consumer callback for
+     * a job nobody owns, and would leave nothing to release the claim.
+     */
+    async #executeClaimed(job) {
+        // Membership re-check. The claim and the invoke are no longer in the same
+        // critical section, and sibling callbacks run unlocked, so a `remove()` can
+        // now land in between AND RESOLVE — it used to deadlock. A resolved
+        // `remove()` must keep meaning "this callback will not fire"; the identity
+        // guard in `#settleJob` only cleans up afterwards, by which point the side
+        // effect has already happened. Identity, not id, so a removed-then-replaced
+        // key is caught too. Deliberately synchronous with the `onJobDue` call
+        // below — nothing can interleave between this check and the invocation.
+        //
+        // This is the one early return after a claim, so it is the one that has to
+        // release the claim by hand. Skipping settle is right — re-inserting or
+        // run-logging a removed job is the resurrection `#settleJob` refuses, and
+        // the heap entry is already gone. But the claim must still come off,
+        // because the detached object is NOT unreachable: it is the object `add()`
+        // returned and `get()`/`list()` hand out, and `start(initialJobs)`
+        // re-registers those objects verbatim, `state` included. A leftover
+        // `runningAtMs` rehydrates a permanently dead job — `isDue` false forever,
+        // `run()` refused forever, `status()` reporting it healthy.
+        //
+        // Assigned directly rather than via `applyResult`: this releases the claim
+        // and nothing else. No run-log row, no heap entry, no `lastStatus`, no
+        // recomputed `nextRunAtMs` — the job did not run.
+        if (this.jobs.get(job.id) !== job) {
+            job.state.runningAtMs = undefined;
+            return { status: 'skipped', reason: 'removed' };
+        }
         const startMs = Date.now();
         let status = 'ok';
         let error;
         let summary;
+        let settled;
+        // The claim marked the job running and detached it from the heap. Phase 3
+        // is the ONLY thing that undoes either, so it must survive every non-local
+        // exit from phase 2 — including a throw from the catch handler itself
+        // (`this.log` is public and overridable and reaches a transport). A claim
+        // with no matching settle is not a degraded state, it is a permanently
+        // dead job.
         try {
-            if (this.onJobDue) {
-                const result = await this.onJobDue(job);
-                if (result) {
-                    status = result.status || 'ok';
-                    error = result.error;
-                    summary = result.summary;
+            // -- Phase 2: invoke (NOT locked) --
+            try {
+                if (this.onJobDue) {
+                    const result = await this.onJobDue(job);
+                    if (result) {
+                        status = result.status || 'ok';
+                        error = result.error;
+                        summary = result.summary;
+                    }
                 }
             }
+            catch (err) {
+                status = 'error';
+                error = describeError(err);
+                this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
+            }
         }
-        catch (err) {
-            status = 'error';
-            error = err instanceof Error ? err.message : String(err);
-            this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
+        finally {
+            // -- Phase 3: settle (locked) --
+            settled = await locked(() => this.#settleJob(job, status, error, summary, startMs, Date.now() - startMs));
         }
-        const durationMs = Date.now() - startMs;
-        const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
-        applyResult(job, validStatus, error, durationMs);
-        // Log the run
-        this.runLog.record({
-            jobId: job.id,
-            status,
-            error,
-            summary,
-            runAtMs: startMs,
-            durationMs,
-            nextRunAtMs: job.state.nextRunAtMs,
-        });
-        // Handle one-shot auto-delete
-        if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
-            this.jobs.delete(job.id);
-            this.runLog.removeJob(job.id);
-            return { status, summary, deleted: true };
+        return settled;
+    }
+    /**
+     * Phase 1 — claim. Must be called while holding the lock (`locked()`, whose
+     * chain is module-global and therefore shared across CronService instances).
+     *
+     * Returns `null` on a successful claim, or the reason the claim was refused.
+     * `'already running'` is what makes a second `run()` report a skip instead of
+     * launching a concurrent invocation. `'removed'` covers the job being deleted
+     * between `run()`'s unlocked lookup and this lock turn — claiming then would
+     * `markRunning` an orphan and, worse, `removeFromHeap` an id that may now
+     * belong to a replacement.
+     *
+     * Detaching from the heap here — rather than relying on phase 3 to push a
+     * fresh entry — is what stops manual runs permanently duplicating entries.
+     *
+     * `#private`: published, this would be a supported call performing
+     * `markRunning` + `removeFromHeap` with no guaranteed settle and no lease on
+     * `runningAtMs`, so a single such call would strand the job forever. The
+     * lock-held precondition cannot be expressed in the type system, so the
+     * method must not be reachable from outside the class body.
+     */
+    #claimJob(job) {
+        if (this.jobs.get(job.id) !== job)
+            return 'removed';
+        if (job.state.runningAtMs)
+            return 'already running';
+        markRunning(job);
+        this.removeFromHeap(job.id);
+        return null;
+    }
+    /**
+     * Phase 3 — settle. Must be called while holding the lock.
+     *
+     * `#private` for the same reason as `#claimJob`: unlocked it would run
+     * `applyResult`, a `runLog.record`, a full `removeFromHeap` rebuild, a
+     * `heap.push` and an `armTimer` with no mutual exclusion — exactly the
+     * corruption `locked()` exists to prevent.
+     */
+    #settleJob(job, status, error, summary, startMs, durationMs) {
+        try {
+            const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
+            applyResult(job, validStatus, error, durationMs);
+            // The callback ran unlocked, so this job may have been removed — or
+            // removed and re-registered under the same id, the shape
+            // `start(initialJobs)` uses — while it was in flight. Identity, not id.
+            //
+            // Deliberately touch NOTHING here. The claim already detached this job's
+            // heap entry and nothing re-added it, so there is nothing to clean up;
+            // any entry now filed under this id belongs to the replacement, and
+            // removing it by id would silently unschedule a live job. Do not
+            // resurrect a removed job's heap entry or run log either.
+            if (this.jobs.get(job.id) !== job) {
+                return { status, error, summary, durationMs };
+            }
+            // Log the run
+            this.runLog.record({
+                jobId: job.id,
+                status,
+                error,
+                summary,
+                runAtMs: startMs,
+                durationMs,
+                nextRunAtMs: job.state.nextRunAtMs,
+            });
+            // Handle one-shot auto-delete. The callback ran unlocked and may have
+            // pushed a heap entry for this job via add()/update(), so drop it — the
+            // job is about to stop existing.
+            if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
+                this.jobs.delete(job.id);
+                this.removeFromHeap(job.id);
+                this.runLog.removeJob(job.id);
+                return { status, summary, deleted: true };
+            }
+            // Re-insert into the heap if still active. Same reason as above: drop any
+            // entry the unlocked callback added for this job first, to preserve
+            // one-entry-per-key.
+            this.removeFromHeap(job.id);
+            if (job.enabled && job.state.nextRunAtMs) {
+                this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+            }
+            return { status, error, summary, durationMs };
         }
-        // Re-insert into heap if still active
-        if (job.enabled && job.state.nextRunAtMs) {
-            this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+        finally {
+            // One re-arm covering every exit, rather than one per branch. The claim
+            // detached this job from the heap, so a timer that fired during the
+            // unlocked invoke would have found nothing to arm — and `run()` has no
+            // `finally { armTimer() }` of its own the way `onTimer` does. Without
+            // this, a manual run() can leave the scheduler with no pending wake.
+            this.armTimer();
         }
-        return { status, error, summary, durationMs };
     }
     // -- Helpers ---------------------------------------------------------
     removeFromHeap(id) {

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.45",
+  "version": "0.2.1-alpha.46",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -79,7 +79,7 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.83"
+    "stonyx": "0.2.3-beta.81"
   },
   "scripts": {
     "build": "tsc",