aiden-runtime 4.0.2 → 4.1.0

package/dist/core/v4/cron/cronState.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/cron/cronState.ts — Phase v4.1-cron
+ *
+ * Durable state for the cron scheduler. One JSON file at
+ * `~/.aiden/cron_jobs.json` with shape:
+ *
+ *   {
+ *     schemaVersion: 2,
+ *     updatedAt:     "2026-05-09T..",
+ *     jobs:          [<CronJob>, ...]
+ *   }
+ *
+ * Three responsibilities:
+ *
+ *   1. Whole-state file lock via `proper-lockfile`. Lock path:
+ *      `<state>.lock`. Non-blocking acquire (retries=0). Two
+ *      processes racing → first wins, second gets `lockHeld`. The
+ *      heartbeat skips silently when locked; user-driven API calls
+ *      surface a clear error so the user can retry.
+ *
+ *   2. Schema migration. v1 = bare array `[CronJob, ...]`,
+ *      v2 = enveloped. Detected on first read; auto-migrated
+ *      transparently with one stderr line per process boot.
+ *
+ *   3. Auto-repair on JSON corruption. Try strict parse → fallback
+ *      strip-trailing-commas → fallback empty + rename original
+ *      to `.bak.<ts>`. Mirrors prior multi-agent systems' lesson:
+ *      a partial write or external editor truncation should NOT
+ *      leave the user with no scheduled jobs.
+ *
+ * Stateless module — every call opens, reads, mutates, writes,
+ * closes. The in-memory cache lives in `cronManager.ts` and is
+ * refreshed by the heartbeat.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCronPaths = defaultCronPaths;
+exports.migrateToV2 = migrateToV2;
+exports.readCronState = readCronState;
+exports.writeCronState = writeCronState;
+exports.acquireCronLock = acquireCronLock;
+exports.isCronLockHeld = isCronLockHeld;
+exports.__resetMigrationLogForTests = __resetMigrationLogForTests;
+const node_fs_1 = require("node:fs");
+const node_fs_2 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const atomicWrite_1 = require("./atomicWrite");
+const diagnostics_1 = require("./diagnostics");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const lockfile = require('proper-lockfile');
+function defaultCronPaths(homeOverride) {
+    // Honor AIDEN_HOME (used by tests + multi-profile workflows). When
+    // set, paths root IS AIDEN_HOME directly (no `.aiden` suffix —
+    // mirrors `core/v4/paths.ts::resolveAidenRoot`). Otherwise default
+    // to ~/.aiden.
+    let root;
+    if (homeOverride && homeOverride.length > 0) {
+        root = homeOverride;
+    }
+    else if (process.env.AIDEN_HOME && process.env.AIDEN_HOME.trim().length > 0) {
+        root = process.env.AIDEN_HOME.trim();
+    }
+    else {
+        root = node_path_1.default.join(node_os_1.default.homedir(), '.aiden');
+    }
+    const stateFile = node_path_1.default.join(root, 'cron_jobs.json');
+    return {
+        stateFile,
+        lockFile: `${stateFile}.lock`,
+        logsDir: node_path_1.default.join(root, 'cron-logs'),
+    };
+}
+// ── Migration ────────────────────────────────────────────────────────────
+let _migrationLogged = false;
+/** Migrate a parsed v1 (bare array) to v2 envelope. Idempotent —
+ *  v2 envelopes pass through unchanged. Mutates in place + returns
+ *  the new envelope. Logs ONE stderr line per process boot. */
+function migrateToV2(parsed) {
+    // v2 envelope — pass through.
+    if (parsed
+        && typeof parsed === 'object'
+        && !Array.isArray(parsed)
+        && 'schemaVersion' in parsed
+        && parsed.schemaVersion === diagnostics_1.CRON_SCHEMA_VERSION) {
+        return enrichV2(parsed);
+    }
+    // v1 bare array — wrap.
+    if (Array.isArray(parsed)) {
+        if (!_migrationLogged) {
+            try {
+                process.stderr.write('v4.1-cron: migrated cron_jobs.json schema v1 → v2\n');
+            }
+            catch { /* non-fatal */ }
+            _migrationLogged = true;
+        }
+        return {
+            schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+            updatedAt: new Date().toISOString(),
+            jobs: parsed.map(migrateJobToV2).filter((j) => j !== null),
+        };
+    }
+    // Anything else — empty registry.
+    return {
+        schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+        updatedAt: new Date().toISOString(),
+        jobs: [],
+    };
+}
+/** Per-job migration. Adds default values for fields that didn't
+ *  exist in v1. Drops malformed records (returns null). */
+function migrateJobToV2(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    if (typeof o.id !== 'string' || !o.id)
+        return null;
+    if (typeof o.action !== 'string')
+        return null;
+    // Detect kind if missing (pre-v4.1-cron legacy).
+    let kind = 'interval';
+    if (typeof o.kind === 'string'
+        && (o.kind === 'interval' || o.kind === 'cron' || o.kind === 'oneshot')) {
+        kind = o.kind;
+    }
+    else if (typeof o.cronExpr === 'string')
+        kind = 'cron';
+    else if (typeof o.oneshotIso === 'string')
+        kind = 'oneshot';
+    // Discriminated state — derive from `enabled` when absent.
+    const enabled = typeof o.enabled === 'boolean' ? o.enabled : true;
+    let state = enabled ? 'scheduled' : 'paused';
+    if (typeof o.state === 'string'
+        && (o.state === 'scheduled' || o.state === 'paused'
+            || o.state === 'completed' || o.state === 'error')) {
+        state = o.state;
+    }
+    return {
+        id: String(o.id),
+        description: typeof o.description === 'string' ? o.description : '',
+        schedule: typeof o.schedule === 'string' ? o.schedule : '',
+        kind,
+        intervalMs: typeof o.intervalMs === 'number' ? o.intervalMs : undefined,
+        cronExpr: typeof o.cronExpr === 'string' ? o.cronExpr : undefined,
+        oneshotIso: typeof o.oneshotIso === 'string' ? o.oneshotIso : undefined,
+        action: String(o.action),
+        enabled,
+        state,
+        pausedAt: typeof o.pausedAt === 'string' ? o.pausedAt : null,
+        pausedReason: typeof o.pausedReason === 'string' ? o.pausedReason : null,
+        createdAt: typeof o.createdAt === 'string' ? o.createdAt : new Date().toISOString(),
+        lastRun: typeof o.lastRun === 'string' ? o.lastRun : undefined,
+        lastResult: typeof o.lastResult === 'string' ? o.lastResult : undefined,
+        lastOutput: typeof o.lastOutput === 'string' ? o.lastOutput : undefined,
+        lastError: typeof o.lastError === 'string' ? o.lastError : null,
+        lastDeliveryError: typeof o.lastDeliveryError === 'string' ? o.lastDeliveryError : null,
+        nextRun: typeof o.nextRun === 'string' ? o.nextRun : undefined,
+        runCount: typeof o.runCount === 'number' ? o.runCount : 0,
+    };
+}
+/** v2-shaped envelope — make sure all jobs have the new fields with
+ *  defaults. Catches the "user manually edited cron_jobs.json"
+ *  case. */
+function enrichV2(env) {
+    return {
+        schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+        updatedAt: env.updatedAt ?? new Date().toISOString(),
+        jobs: (env.jobs ?? []).map((j) => ({
+            ...j,
+            state: j.state ?? (j.enabled ? 'scheduled' : 'paused'),
+            pausedAt: j.pausedAt ?? null,
+            pausedReason: j.pausedReason ?? null,
+            lastError: j.lastError ?? null,
+            lastDeliveryError: j.lastDeliveryError ?? null,
+        })),
+    };
+}
+// ── Auto-repair / load ────────────────────────────────────────────────────
+/** Read state from disk. Auto-migrates v1 → v2; auto-repairs on
+ *  corrupt JSON. Returns an empty envelope when the file doesn't
+ *  exist. NEVER throws — corrupt-state is ALWAYS recoverable. */
+async function readCronState(stateFile) {
+    let raw;
+    try {
+        raw = await node_fs_1.promises.readFile(stateFile, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return {
+                schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+                updatedAt: new Date().toISOString(),
+                jobs: [],
+            };
+        }
+        // Permission / EBUSY — leave caller to handle, but do NOT lose state.
+        throw err;
+    }
+    // Try strict parse.
+    try {
+        return migrateToV2(JSON.parse(raw));
+    }
+    catch { /* fall through to repair */ }
+    // Auto-repair: strip trailing commas (most common bare-edit corruption).
+    try {
+        const stripped = raw
+            .replace(/,(\s*[}\]])/g, '$1') // trailing comma in object/array
+            .replace(/^\s*\/\/.*$/gm, ''); // line comments (defensive)
+        return migrateToV2(JSON.parse(stripped));
+    }
+    catch { /* fall through to bak-and-empty */ }
+    // Last resort: rename the corrupt file aside, return empty.
+    const bak = `${stateFile}.bak.${Date.now()}`;
+    try {
+        await node_fs_1.promises.rename(stateFile, bak);
+    }
+    catch { /* noop */ }
+    try {
+        process.stderr.write(`v4.1-cron: cron_jobs.json corrupt — moved to ${node_path_1.default.basename(bak)}, starting empty\n`);
+    }
+    catch { /* noop */ }
+    return {
+        schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+        updatedAt: new Date().toISOString(),
+        jobs: [],
+    };
+}
+/** Write state to disk via atomicWrite. Updates `updatedAt` to now. */
+async function writeCronState(stateFile, state) {
+    const next = {
+        ...state,
+        schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+        updatedAt: new Date().toISOString(),
+    };
+    await (0, atomicWrite_1.writeJsonAtomic)(stateFile, next);
+}
+/** Acquire the whole-cron-state lock. Returns null when contended
+ *  (failFast) or after retry exhausted (non-failFast). NEVER
+ *  throws — caller checks for null. */
+async function acquireCronLock(paths, opts = {}) {
+    // proper-lockfile requires the target to exist. Touch it.
+    try {
+        await node_fs_1.promises.mkdir(node_path_1.default.dirname(paths.stateFile), { recursive: true });
+        if (!(0, node_fs_2.existsSync)(paths.stateFile)) {
+            await node_fs_1.promises.writeFile(paths.stateFile, JSON.stringify({
+                schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+                updatedAt: new Date().toISOString(),
+                jobs: [],
+            }, null, 2), { flag: 'wx', encoding: 'utf-8' }).catch(() => undefined);
+        }
+    }
+    catch { /* non-fatal */ }
+    const lockOpts = {
+        realpath: true,
+        stale: 20000, // proper-lockfile default 10s; bump to 20s
+        retries: opts.failFast ? 0 : 1,
+        lockfilePath: paths.lockFile,
+    };
+    let release = null;
+    try {
+        release = await lockfile.lock(paths.stateFile, lockOpts);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // proper-lockfile throws ELOCKED — that's a "skip" signal, not
+        // an error. Other errors (permission, etc.) are silently NULLed
+        // — caller checks for null and proceeds in degraded mode.
+        if (!/lock(ed)?/i.test(msg)) {
+            // Surface unusual failures via stderr but never crash.
+            try {
+                process.stderr.write(`v4.1-cron: lock acquire failed: ${msg}\n`);
+            }
+            catch { /* noop */ }
+        }
+        return null;
+    }
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                await release();
+            }
+            catch { /* best effort; OS releases on process exit anyway */ }
+        },
+    };
+}
+/** Best-effort check: is the lock currently held? Used by /cron
+ *  status diagnostics. Never throws. */
+async function isCronLockHeld(paths) {
+    try {
+        return await lockfile.check(paths.stateFile, {
+            realpath: true,
+            lockfilePath: paths.lockFile,
+        });
+    }
+    catch {
+        return false;
+    }
+}
+// ── Test hook ────────────────────────────────────────────────────────────
+function __resetMigrationLogForTests() {
+    _migrationLogged = false;
+}

package/dist/core/v4/cron/cronTick.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/cron/cronTick.ts — Phase v4.1-cron
+ *
+ * 60-second heartbeat. The hybrid tick architecture:
+ *
+ *   - Per-job `setTimeout` arms each job for its specific next-
+ *     fire time (existing legacy behaviour preserved). Sub-second
+ *     precision, no extra latency.
+ *
+ *   - This heartbeat re-reads `cron_jobs.json` every 60s under
+ *     lock. If another process (or the user editing the file)
+ *     added / removed / paused jobs, this picks up the change
+ *     and re-arms timers accordingly.
+ *
+ *   - When the lock is held by another process, the tick skips
+ *     silently with a logged "skipped: lock held" line and a
+ *     diagnostics increment.
+ *
+ *   - Fast-forward / catch-up after sleep: when the heartbeat
+ *     wakes after a long pause (laptop slept past nextRun for
+ *     multiple jobs), graceWindow.evaluateRecurring decides
+ *     whether to fire-now or skip-and-fast-forward per job.
+ *
+ * The heartbeat is a singleton — calling `startHeartbeat()`
+ * twice is a no-op. `stopHeartbeat()` clears the timer; the
+ * caller is responsible for calling it on graceful shutdown
+ * (CLI signal handler, REPL exit, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startHeartbeat = startHeartbeat;
+exports.stopHeartbeat = stopHeartbeat;
+exports.isHeartbeatActive = isHeartbeatActive;
+const cronState_1 = require("./cronState");
+const diagnostics_1 = require("./diagnostics");
+// Module-level singleton — one heartbeat per process.
+let _heartbeatTimer = null;
+let _heartbeatActive = false;
+/** Start the 60s heartbeat. Idempotent — second call no-ops. */
+function startHeartbeat(opts) {
+    if (_heartbeatTimer)
+        return;
+    const intervalMs = opts.intervalMs ?? (0, diagnostics_1.resolveTickMs)();
+    const tick = async () => {
+        const lock = await (0, cronState_1.acquireCronLock)(opts.paths, { failFast: true });
+        if (!lock) {
+            (0, diagnostics_1.noteSkippedTick)();
+            return;
+        }
+        try {
+            (0, diagnostics_1.noteHeartbeat)(true);
+            const state = await (0, cronState_1.readCronState)(opts.paths.stateFile);
+            await opts.onTick(state.jobs);
+        }
+        catch {
+            // Heartbeat must never throw out — caller's onTick is
+            // best-effort. Errors land in the in-process logger via
+            // the caller's own logging.
+        }
+        finally {
+            await lock.release();
+        }
+    };
+    _heartbeatActive = true;
+    // Fire once immediately (the tick is the catch-up boundary).
+    void tick();
+    _heartbeatTimer = setInterval(() => { void tick(); }, intervalMs);
+    // Don't keep the event loop alive just for the heartbeat.
+    if (typeof _heartbeatTimer.unref === 'function') {
+        _heartbeatTimer.unref();
+    }
+}
+/** Stop the heartbeat. Idempotent. */
+function stopHeartbeat() {
+    if (_heartbeatTimer) {
+        clearInterval(_heartbeatTimer);
+        _heartbeatTimer = null;
+    }
+    _heartbeatActive = false;
+    (0, diagnostics_1.noteHeartbeat)(false);
+}
+function isHeartbeatActive() {
+    return _heartbeatActive;
+}

package/dist/core/v4/cron/diagnostics.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/cron/diagnostics.ts — Phase v4.1-cron
+ *
+ * Build fingerprint + diagnostics envelope for `/cron status`,
+ * `aiden cron status`, and the heartbeat tracker. Bump on every
+ * shipped phase. Format: `v4.1-cron[+suffix]`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECENT_FIRES_KEEP = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_TICK_MS = exports.CRON_SCHEMA_VERSION = exports.AIDEN_CRON_BUILD = void 0;
+exports.noteHeartbeat = noteHeartbeat;
+exports.noteSkippedTick = noteSkippedTick;
+exports.noteFireStarted = noteFireStarted;
+exports.recordFire = recordFire;
+exports.getDiagnosticsSnapshot = getDiagnosticsSnapshot;
+exports.resolveTickMs = resolveTickMs;
+exports.resolveTimeoutMs = resolveTimeoutMs;
+exports.__resetDiagnosticsForTests = __resetDiagnosticsForTests;
+/** Build fingerprint — bump per phase. */
+exports.AIDEN_CRON_BUILD = 'v4.1-cron';
+/** Schema version — bumped when on-disk format changes. v1 = bare
+ *  array, v2 = enveloped `{ jobs: [...], updatedAt, schemaVersion }`. */
+exports.CRON_SCHEMA_VERSION = 2;
+/** Default 60s heartbeat — env override `AIDEN_CRON_TICK_MS`. */
+exports.DEFAULT_TICK_MS = 60000;
+/** Default per-fire timeout — env override `AIDEN_CRON_TIMEOUT_MS`.
+ *  Long-running shell_exec (web research, deep file ops) legitimately
+ *  takes minutes; 600s gives ample headroom. */
+exports.DEFAULT_TIMEOUT_MS = 600000;
+/** Recent-fires retention — diagnostics surface the last N. */
+exports.RECENT_FIRES_KEEP = 5;
+/** In-process diagnostics ring buffer. Module singleton — survives
+ *  across calls but resets on process boot. */
+const _state = {
+    heartbeatActive: false,
+    lastHeartbeatAt: null,
+    skippedTicks: 0,
+    firesStarted: 0,
+    recentFires: [],
+};
+function noteHeartbeat(active, at = new Date()) {
+    _state.heartbeatActive = active;
+    _state.lastHeartbeatAt = at.toISOString();
+}
+function noteSkippedTick() {
+    _state.skippedTicks += 1;
+}
+function noteFireStarted() {
+    _state.firesStarted += 1;
+}
+function recordFire(rec) {
+    _state.recentFires.unshift(rec);
+    if (_state.recentFires.length > exports.RECENT_FIRES_KEEP) {
+        _state.recentFires.length = exports.RECENT_FIRES_KEEP;
+    }
+}
+function getDiagnosticsSnapshot(opts) {
+    return {
+        build: exports.AIDEN_CRON_BUILD,
+        schemaVersion: opts.schemaVersion,
+        tickMs: resolveTickMs(),
+        timeoutMs: resolveTimeoutMs(),
+        heartbeatActive: _state.heartbeatActive,
+        lastHeartbeatAt: _state.lastHeartbeatAt,
+        skippedTicks: _state.skippedTicks,
+        firesStarted: _state.firesStarted,
+        recentFires: [..._state.recentFires],
+        lock: { path: opts.lockPath, held: opts.lockHeld },
+    };
+}
+/** Resolve tick interval — env override > default. */
+function resolveTickMs(env = process.env) {
+    const raw = env.AIDEN_CRON_TICK_MS;
+    if (raw && /^\d+$/.test(raw)) {
+        const n = Number.parseInt(raw, 10);
+        if (n >= 1000 && n <= 3600000)
+            return n;
+    }
+    return exports.DEFAULT_TICK_MS;
+}
+/** Resolve per-fire timeout — env override > default. */
+function resolveTimeoutMs(env = process.env) {
+    const raw = env.AIDEN_CRON_TIMEOUT_MS;
+    if (raw && /^\d+$/.test(raw)) {
+        const n = Number.parseInt(raw, 10);
+        if (n >= 1000 && n <= 24 * 3600000)
+            return n;
+    }
+    return exports.DEFAULT_TIMEOUT_MS;
+}
+/** Test-only: reset diagnostics state. */
+function __resetDiagnosticsForTests() {
+    _state.heartbeatActive = false;
+    _state.lastHeartbeatAt = null;
+    _state.skippedTicks = 0;
+    _state.firesStarted = 0;
+    _state.recentFires = [];
+}

package/dist/core/v4/cron/graceWindow.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/cron/graceWindow.ts — Phase v4.1-cron
+ *
+ * Adaptive grace window for fast-forward / catch-up after sleep.
+ *
+ * Hard-won lesson (port from prior multi-agent systems): a fixed
+ * global grace cap is wrong for cron. Daily jobs that ran at 9am
+ * yesterday and the laptop slept past 9am today should still fire
+ * within a reasonable window (up to ~2h late). But sub-hourly jobs
+ * (every 5 minutes) should NOT fire 30 missed instances after a
+ * long sleep — that's a thundering-herd disaster.
+ *
+ * Solution: scale the grace window to the schedule period. Half
+ * the period, capped at 2h, floored at 2 minutes. Then SKIP, don't
+ * REPLAY: when a job is overdue beyond its grace, fast-forward
+ * `nextRunAt` to the next future occurrence and skip this firing
+ * entirely. "One missed run lost; no thundering-herd risk."
+ *
+ *   grace = max(120s, min(period/2, 7200s))
+ *
+ * This module is a pure function — no I/O, no state. Caller
+ * threads the snapshot and decides what to do based on the
+ * verdict.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ONESHOT_GRACE_MS = exports.GRACE_CEIL_MS = exports.GRACE_FLOOR_MS = void 0;
+exports.computeGraceMs = computeGraceMs;
+exports.evaluateRecurring = evaluateRecurring;
+exports.evaluateOneShot = evaluateOneShot;
+/** Constants — exposed for tests. */
+exports.GRACE_FLOOR_MS = 120 * 1000; // 2 minutes
+exports.GRACE_CEIL_MS = 2 * 60 * 60 * 1000; // 2 hours
+/** One-shot jobs get a fixed 2-minute grace window — they cannot
+ *  fast-forward (no recurring schedule), so a delivery that hits
+ *  the second after a one-shot's `runAt` should still fire. */
+exports.ONESHOT_GRACE_MS = 120 * 1000;
+/** Compute the grace window for a recurring schedule. `periodMs` is
+ *  the interval between fires (e.g. interval=300_000 for every 5
+ *  minutes, or the croner-computed gap between successive cron
+ *  fires). */
+function computeGraceMs(periodMs) {
+    if (!Number.isFinite(periodMs) || periodMs <= 0)
+        return exports.GRACE_FLOOR_MS;
+    const half = Math.floor(periodMs / 2);
+    const clamped = Math.max(exports.GRACE_FLOOR_MS, Math.min(half, exports.GRACE_CEIL_MS));
+    return clamped;
+}
+/** Determine whether a recurring job should fire, skip-and-advance,
+ *  or wait. Pure — no clock injection issue: caller passes `now`. */
+function evaluateRecurring(args) {
+    const { nextRunAtMs, periodMs, nowMs } = args;
+    if (nowMs < nextRunAtMs)
+        return { kind: 'wait' };
+    const overdueMs = nowMs - nextRunAtMs;
+    const grace = computeGraceMs(periodMs);
+    if (overdueMs <= grace)
+        return { kind: 'fire' };
+    return { kind: 'skip-fast-forward' };
+}
+/** One-shot variant — different grace window, no fast-forward. */
+function evaluateOneShot(args) {
+    const { runAtMs, nowMs } = args;
+    if (nowMs < runAtMs)
+        return { kind: 'wait' };
+    // One-shot: fire if within ONESHOT_GRACE_MS, else "skip" — the
+    // caller flips `enabled=false` on this job rather than advancing
+    // because there's no next occurrence.
+    const overdueMs = nowMs - runAtMs;
+    if (overdueMs <= exports.ONESHOT_GRACE_MS)
+        return { kind: 'fire' };
+    return { kind: 'skip-fast-forward' };
+}