@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/daemon/manage.d.ts

@@ -6,11 +6,28 @@ export interface SpawnDaemonResult {
     /** PID of the already-running daemon, if it was already up. */
     existing_pid?: number;
 }
+export interface DaemonStartupDeps {
+    readPidfile?: () => number | null;
+    isPidAlive?: (pid: number) => boolean;
+    childExited?: () => {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
+    sleepMs?: (ms: number) => Promise<void> | void;
+    now?: () => number;
+}
+/** Tiny bounded post-spawn guard: wait for the daemon pidfile and live pid to
+ *  appear before reporting success. This catches the "started:true but not yet
+ *  plausibly alive" race without turning startup into a retry loop.
+ *
+ *  Returns null when the spawned pid owns the pidfile; returns a different live
+ *  daemon pid when startup lost the race to an already-running daemon. */
+export declare function verifyDaemonStartup(pid: number, timeoutMs?: number, deps?: DaemonStartupDeps): Promise<number | null>;
 /** Spawn crtrd detached. Returns immediately; the child outlives this process.
  *
  *  If the daemon is already running, returns {started:false, existing_pid}.
  *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
-export declare function spawnDaemon(): SpawnDaemonResult;
+export declare function spawnDaemon(): Promise<SpawnDaemonResult>;
 /** Start the daemon if it is not already running. No-op if already up.
  *  Silently swallows spawn errors (the canvas still works without the daemon;
  *  nodes just won't be auto-revived). */

package/dist/daemon/manage.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { mkdirSync } from 'node:fs';
 import { crtrHome } from '../core/canvas/paths.js';
 import { hostExecPath } from '../core/runtime/branded-host.js';
-import { isDaemonRunning, readPidfile } from './crtrd.js';
+import { isDaemonRunning, readPidfile, isPidAlive } from './crtrd.js';
 // ---------------------------------------------------------------------------
 // Entry point resolution
 // ---------------------------------------------------------------------------
@@ -21,11 +21,45 @@ function resolveCrtrdEntry() {
     const here = dirname(fileURLToPath(import.meta.url));
     return join(here, 'crtrd-cli.js');
 }
+// Cold guests can take a few seconds to settle their pidfile + liveness probe.
+const STARTUP_VERIFY_WINDOW_MS = 5_000;
+const STARTUP_VERIFY_POLL_MS = 10;
+function sleepMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Tiny bounded post-spawn guard: wait for the daemon pidfile and live pid to
+ *  appear before reporting success. This catches the "started:true but not yet
+ *  plausibly alive" race without turning startup into a retry loop.
+ *
+ *  Returns null when the spawned pid owns the pidfile; returns a different live
+ *  daemon pid when startup lost the race to an already-running daemon. */
+export async function verifyDaemonStartup(pid, timeoutMs = STARTUP_VERIFY_WINDOW_MS, deps = {}) {
+    const read = deps.readPidfile ?? readPidfile;
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const exited = deps.childExited;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    while (now() <= deadline) {
+        const owner = read();
+        if (owner !== null && alive(owner))
+            return owner === pid ? null : owner;
+        const exitState = exited?.();
+        if (exitState !== null && exitState !== undefined) {
+            const exitDetail = exitState.signal !== null ? `by ${exitState.signal}` : `with exit code ${exitState.code ?? '?'}`;
+            throw new Error(`daemon ${pid} exited before becoming ready (${exitDetail})`);
+        }
+        await sleep(STARTUP_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} did not become ready within ${timeoutMs}ms`);
+}
 /** Spawn crtrd detached. Returns immediately; the child outlives this process.
  *
  *  If the daemon is already running, returns {started:false, existing_pid}.
  *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
-export function spawnDaemon() {
+export async function spawnDaemon() {
     if (isDaemonRunning()) {
         return { started: false, existing_pid: readPidfile() ?? undefined };
     }
@@ -41,7 +75,20 @@ export function spawnDaemon() {
         stdio: 'ignore',
     });
     const pid = child.pid;
+    if (pid === undefined) {
+        throw new Error('daemon spawn did not return a pid');
+    }
+    let exitState = null;
+    child.once('exit', (code, signal) => {
+        exitState = { code, signal };
+    });
     child.unref();
+    const existingPid = await verifyDaemonStartup(pid, STARTUP_VERIFY_WINDOW_MS, {
+        childExited: () => exitState,
+    });
+    if (existingPid !== null) {
+        return { started: false, existing_pid: existingPid };
+    }
     return { started: true, pid };
 }
 // ---------------------------------------------------------------------------
@@ -51,12 +98,10 @@ export function spawnDaemon() {
  *  Silently swallows spawn errors (the canvas still works without the daemon;
  *  nodes just won't be auto-revived). */
 export function ensureDaemon() {
-    try {
-        if (!isDaemonRunning())
-            spawnDaemon();
-    }
-    catch {
-        // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
-        // pre-build) must not break the calling command.
+    if (!isDaemonRunning()) {
+        void spawnDaemon().catch(() => {
+            // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
+            // pre-build) must not break the calling command.
+        });
     }
 }

package/dist/daemon/predicate-eval.d.ts

@@ -0,0 +1,52 @@
+import { type Trigger } from '../core/canvas/index.js';
+export declare const STDOUT_CAP_BYTES: number;
+export declare const STDERR_TAIL_BYTES: number;
+export interface PredicateCapacity {
+    maxCanvas: number;
+    maxPerOwner: number;
+    evalTimeoutMs: number;
+}
+/** Read fresh each pass (not cached at module load) so a test/operator can
+ *  tune it via env without a daemon restart mid-run. */
+export declare function predicateCapacity(): PredicateCapacity;
+/** One id per daemon PROCESS instance — distinguishes THIS process's own
+ *  in-flight leases from a stale 'running' row a prior (crashed/restarted)
+ *  daemon left behind (spec §Lease / in-flight contract, daemon-restart
+ *  recovery). Generated once per process; tests that want deterministic
+ *  recovery behavior can ignore it (recovery only special-cases OWN leases). */
+export declare const daemonInstanceId: `${string}-${string}-${string}-${string}-${string}`;
+export type PredicateOutcome = {
+    kind: 'fired';
+    trigger: Trigger;
+    stdout: string;
+} | {
+    kind: 'stdout_overflow';
+    trigger: Trigger;
+} | {
+    kind: 'target_gone';
+    trigger: Trigger;
+};
+/** Recover stale in-flight rows left by a PRIOR daemon instance (crash/
+ *  restart): a still-alive process group past its own eval timeout is killed +
+ *  recorded as a timeout; a dead pid resets straight to idle with no
+ *  diagnostics (spec: "if not alive, the row is reset to idle and eligible for
+ *  the next evaluation slot"). Rows this SAME instance owns are left alone —
+ *  they are genuinely in flight, not stale. */
+export declare function recoverStalePredicateLeases(now: number, config: PredicateCapacity): void;
+/** Wall-clock `timeout_at` reap — independent of eval_state/next_eval_at.
+ *  Kills any in-flight process group for a timed-out row, consumes it, and
+ *  invokes `onTimeout` once per row so the caller can send the owner urgent
+ *  notice (spec: "consume and notify owner"). Call BEFORE
+ *  evaluateDuePredicates each tick so a timed-out row can never also be
+ *  freshly evaluated in the same tick (consumeTrigger removes it from the due
+ *  query). */
+export declare function reapTimedOutPredicates(now: number, onTimeout: (t: Trigger) => void): void;
+/** Pass 3c: select due idle predicates (deterministic order from the DAO),
+ *  enforce capacity in-memory (seeded from the current running-row snapshot),
+ *  and kick off evaluations — NEVER awaited. `onDone` fires per trigger,
+ *  whenever it settles (possibly after this call returns). Rows over capacity,
+ *  or whose owner is at its per-owner cap, are left untouched (idle,
+ *  next_eval_at unchanged) and are retried next tick. A `msg` trigger whose
+ *  target no longer exists is reaped here (consumed + `target_gone`) instead
+ *  of being spawned against a dangling id. */
+export declare function evaluateDuePredicates(now: number, onDone: (o: PredicateOutcome) => void): void;

package/dist/daemon/predicate-eval.js

@@ -0,0 +1,248 @@
+// src/daemon/predicate-eval.ts — the daemon-owned `--when` predicate
+// evaluator: subprocess spawn/capture/timeout/capacity/lease mechanics ONLY.
+// No enactment logic lives here (no appendInbox/reviveNode/spawnChild) — every
+// settled outcome is handed to the caller's `onDone`/`onTimeout` callback, and
+// crtrd.ts is the SINGLE place that turns a settled trigger into an inbox
+// message / revive / spawn (reusing the exact same enactment code the clock-
+// trigger pass uses). This keeps enactment in ONE place regardless of whether
+// the trigger fired off a clock or a predicate.
+//
+// Fire-and-forget contract: evaluateDuePredicates NEVER awaits a subprocess —
+// it kicks off child processes and returns immediately; each settles later via
+// its own `close`/timeout handler calling `onDone`. The daemon tick must never
+// block on a slow/hung predicate (spec §Predicate triggers: "cannot block the
+// daemon tick").
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { duePredicateTriggers, duePredicateTimeouts, runningPredicateTriggers, acquirePredicateLease, recordPredicateEvalResult, resetPredicateLease, consumeTrigger, getNode, } from '../core/canvas/index.js';
+import { isPidAlive, killProcessGroup } from '../core/canvas/pid.js';
+import { nextSlotAfter } from '../core/wake.js';
+export const STDOUT_CAP_BYTES = 16 * 1024;
+export const STDERR_TAIL_BYTES = 4 * 1024;
+/** Read fresh each pass (not cached at module load) so a test/operator can
+ *  tune it via env without a daemon restart mid-run. */
+export function predicateCapacity() {
+    const num = (name, fallback) => {
+        const raw = process.env[name];
+        const n = raw !== undefined ? Number(raw) : NaN;
+        return Number.isFinite(n) && n > 0 ? n : fallback;
+    };
+    return {
+        maxCanvas: num('CRTR_PREDICATE_MAX_CANVAS', 8),
+        maxPerOwner: num('CRTR_PREDICATE_MAX_OWNER', 2),
+        evalTimeoutMs: num('CRTR_PREDICATE_EVAL_TIMEOUT_MS', 10_000),
+    };
+}
+/** One id per daemon PROCESS instance — distinguishes THIS process's own
+ *  in-flight leases from a stale 'running' row a prior (crashed/restarted)
+ *  daemon left behind (spec §Lease / in-flight contract, daemon-restart
+ *  recovery). Generated once per process; tests that want deterministic
+ *  recovery behavior can ignore it (recovery only special-cases OWN leases). */
+export const daemonInstanceId = randomUUID();
+function nextEvalAfter(t, nowMs) {
+    return t.eval_every != null ? nextSlotAfter(t.eval_every, new Date(nowMs)) : new Date(nowMs).toISOString();
+}
+/** Recover stale in-flight rows left by a PRIOR daemon instance (crash/
+ *  restart): a still-alive process group past its own eval timeout is killed +
+ *  recorded as a timeout; a dead pid resets straight to idle with no
+ *  diagnostics (spec: "if not alive, the row is reset to idle and eligible for
+ *  the next evaluation slot"). Rows this SAME instance owns are left alone —
+ *  they are genuinely in flight, not stale. */
+export function recoverStalePredicateLeases(now, config) {
+    for (const t of runningPredicateTriggers()) {
+        if (t.eval_lease_owner === daemonInstanceId)
+            continue;
+        const pid = t.eval_pid;
+        if (pid == null || !isPidAlive(pid)) {
+            resetPredicateLease(t.trigger_id);
+            continue;
+        }
+        const startedAtMs = t.eval_started_at != null ? new Date(t.eval_started_at).getTime() : now;
+        if (now - startedAtMs < config.evalTimeoutMs)
+            continue; // still within its own window — leave it
+        killProcessGroup(pid);
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date(now).toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, now),
+            exitCode: null,
+            stderrTail: `evaluation timed out after ${config.evalTimeoutMs}ms (recovered stale lease from a prior daemon instance)`,
+        });
+    }
+}
+/** Wall-clock `timeout_at` reap — independent of eval_state/next_eval_at.
+ *  Kills any in-flight process group for a timed-out row, consumes it, and
+ *  invokes `onTimeout` once per row so the caller can send the owner urgent
+ *  notice (spec: "consume and notify owner"). Call BEFORE
+ *  evaluateDuePredicates each tick so a timed-out row can never also be
+ *  freshly evaluated in the same tick (consumeTrigger removes it from the due
+ *  query). */
+export function reapTimedOutPredicates(now, onTimeout) {
+    for (const t of duePredicateTimeouts(new Date(now).toISOString())) {
+        if (t.eval_state === 'running' && t.eval_pid != null)
+            killProcessGroup(t.eval_pid);
+        consumeTrigger(t.trigger_id);
+        onTimeout(t);
+    }
+}
+function runOneEvaluation(t, config, onDone) {
+    let cwd;
+    if (t.action === 'msg') {
+        const target = t.node_id != null ? getNode(t.node_id) : null;
+        if (target === null) {
+            // Shouldn't reach here — the caller checks target existence before
+            // calling this — but never spawn against an unresolved cwd.
+            return;
+        }
+        cwd = target.cwd;
+    }
+    else {
+        cwd = t.payload.cwd;
+    }
+    const env = {
+        ...process.env,
+        CRTR_TRIGGER_ID: t.trigger_id,
+        CRTR_TRIGGER_OWNER_ID: t.owner_id,
+    };
+    if (t.node_id != null)
+        env['CRTR_TRIGGER_TARGET_ID'] = t.node_id;
+    const startedAtIso = new Date().toISOString();
+    let child;
+    try {
+        child = spawn('bash', ['-c', t.when_script ?? 'exit 1'], {
+            cwd,
+            env,
+            detached: true, // own process group — killProcessGroup(-pid) reaps the whole tree
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: null,
+            stderrTail: `evaluation failed to spawn: ${err.message}`.slice(-STDERR_TAIL_BYTES),
+        });
+        return;
+    }
+    if (child.pid == null || !acquirePredicateLease(t.trigger_id, daemonInstanceId, child.pid, startedAtIso)) {
+        // Lost a race (canceled / grabbed between selection and spawn, or the
+        // process never got a pid) — abandon; never leave an unaccounted child.
+        if (child.pid != null)
+            killProcessGroup(child.pid);
+        return;
+    }
+    let stdout = '';
+    let stdoutBytes = 0;
+    let overflowed = false;
+    let stderrTail = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        if (child.pid != null)
+            killProcessGroup(child.pid);
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: null,
+            stderrTail: `evaluation timed out after ${config.evalTimeoutMs}ms`,
+        });
+    }, config.evalTimeoutMs);
+    timer.unref?.();
+    child.stdout?.on('data', (chunk) => {
+        stdoutBytes += chunk.length;
+        if (stdout.length < STDOUT_CAP_BYTES)
+            stdout += chunk.toString('utf8');
+        if (stdoutBytes > STDOUT_CAP_BYTES)
+            overflowed = true;
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderrTail = (stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL_BYTES);
+    });
+    const finish = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (code === 0) {
+            // stdout only matters (and only needs a size cap) when it is ABOUT to
+            // become the message body: msg/inbox_message with no inline body
+            // supplied at arm time. A non-zero exit always reschedules below
+            // regardless of overflow — a verbose "not yet" predicate must stay armed
+            // (spec criterion 7) — and an exit-0 node_birth or a msg with a supplied
+            // body never reads stdout at all, so an overflow there is harmless noise,
+            // not a delivery failure.
+            const stdoutIsBody = t.action === 'msg' &&
+                t.action_mode === 'inbox_message' &&
+                t.payload.body === undefined;
+            if (overflowed && stdoutIsBody) {
+                // Guard against the narrow cross-path race: a wall-clock reaper
+                // (reapTimedOutPredicates) may have already killed + consumed this
+                // exact trigger between the kill signal and this close event firing
+                // (the `settled` guard above is local to this evaluation and doesn't
+                // see a racing reaper). consumeTrigger reports whether IT actually
+                // removed a live row; if the row is already gone, no-op instead of
+                // delivering a second, now-orphaned outcome.
+                if (!consumeTrigger(t.trigger_id))
+                    return;
+                onDone({ kind: 'stdout_overflow', trigger: t });
+                return;
+            }
+            if (!consumeTrigger(t.trigger_id))
+                return; // settle-before-enact; no-op if a racing reaper already consumed it
+            onDone({ kind: 'fired', trigger: t, stdout: stdout.slice(0, STDOUT_CAP_BYTES).trim() });
+            return;
+        }
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: code,
+            stderrTail: stderrTail === '' ? null : stderrTail,
+        });
+    };
+    child.on('close', (code) => finish(code));
+    child.on('error', (err) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        recordPredicateEvalResult(t.trigger_id, {
+            completedAtIso: new Date().toISOString(),
+            nextEvalAtIso: nextEvalAfter(t, Date.now()),
+            exitCode: null,
+            stderrTail: `evaluation process error: ${err.message}`.slice(-STDERR_TAIL_BYTES),
+        });
+    });
+}
+/** Pass 3c: select due idle predicates (deterministic order from the DAO),
+ *  enforce capacity in-memory (seeded from the current running-row snapshot),
+ *  and kick off evaluations — NEVER awaited. `onDone` fires per trigger,
+ *  whenever it settles (possibly after this call returns). Rows over capacity,
+ *  or whose owner is at its per-owner cap, are left untouched (idle,
+ *  next_eval_at unchanged) and are retried next tick. A `msg` trigger whose
+ *  target no longer exists is reaped here (consumed + `target_gone`) instead
+ *  of being spawned against a dangling id. */
+export function evaluateDuePredicates(now, onDone) {
+    const config = predicateCapacity();
+    const running = runningPredicateTriggers();
+    let globalCount = running.length;
+    const perOwner = new Map();
+    for (const r of running)
+        perOwner.set(r.owner_id, (perOwner.get(r.owner_id) ?? 0) + 1);
+    for (const t of duePredicateTriggers(new Date(now).toISOString())) {
+        if (t.action === 'msg' && t.node_id != null && getNode(t.node_id) === null) {
+            consumeTrigger(t.trigger_id);
+            onDone({ kind: 'target_gone', trigger: t });
+            continue;
+        }
+        if (globalCount >= config.maxCanvas)
+            break; // no capacity left for anyone
+        const ownerCount = perOwner.get(t.owner_id) ?? 0;
+        if (ownerCount >= config.maxPerOwner)
+            continue; // this owner is at cap; try the next row
+        globalCount++;
+        perOwner.set(t.owner_id, ownerCount + 1);
+        runOneEvaluation(t, config, onDone);
+    }
+}

package/dist/hearth/control-plane/__tests__/node-message.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+// Bug-regression test (CLAUDE.md "Testing policy" #2) — locks in the P5-review
+// (mr1ganv3-e3401250) CRITICAL fix: `wakeAndExecNodeMessage` invoked a
+// nonexistent `crtr node spine msg <target> --tier <tier>` command (no `node
+// spine` branch exists, and the `msg` leaf takes its target via `--to`, not
+// positionally). Every exec exited non-zero, so `deliverTrigger` recorded
+// `failed` for every cron fire and webhook — the entire SEAM-5 delivery path
+// was dead. This test fails if the argv regresses to `node spine msg` or a
+// positional target.
+test('wakeAndExecNodeMessage runs `crtr node msg --to <target> --tier <tier>` with the body on stdin', async () => {
+    const { wakeAndExecNodeMessage, nodeMessageInternals } = await import('../node-message.js');
+    const orig = { ...nodeMessageInternals };
+    const execCalls = [];
+    nodeMessageInternals.getHomeById = ((home_id) => ({
+        home_id,
+        tenant_id: 't1',
+        user_id: 'u1',
+        provider: 'blaxel',
+        provider_sandbox_id: 'sbx-1',
+        provider_volume_id: null,
+        preview_endpoint: null,
+        home_agent_target: 'home-agent-1',
+        relay_auth_ref: null,
+        status: 'running',
+        template_version: null,
+        last_ready_at: null,
+        last_wake_at: null,
+        last_suspend_at: null,
+        last_wake_latency_ms: null,
+        health_verdict: 'healthy',
+        created_at: '2026-06-30T00:00:00.000Z',
+        updated_at: '2026-06-30T00:00:00.000Z',
+    }));
+    nodeMessageInternals.ensureAwake = async () => ({ preview_endpoint: 'https://x.example', relayToken: 'tok' });
+    nodeMessageInternals.loadM0Config = (() => ({}));
+    nodeMessageInternals.getHomeBackend = (() => ({
+        wake: async () => ({ provider_sandbox_id: 'sbx-1', provider_volume_id: null, preview_endpoint: null }),
+        suspend: async () => ({ provider_sandbox_id: 'sbx-1', provider_volume_id: null, preview_endpoint: null }),
+        getMachine: async () => null,
+        exec: async (machineId, input) => {
+            execCalls.push({ machineId, argv: input.argv, stdin: input.stdin });
+            return { exitCode: 0, timedOut: false, stdout: '', stderr: '' };
+        },
+    }));
+    try {
+        await wakeAndExecNodeMessage('h1', '{"source":"cron","trigger_id":"f1"}', 'urgent');
+        assert.equal(execCalls.length, 1);
+        const call = execCalls[0];
+        assert.equal(call.machineId, 'sbx-1');
+        // The real CLI form: `crtr node msg --to <target> --tier <tier>` — never
+        // `node spine msg` and never a positional target.
+        assert.deepEqual(call.argv, ['crtr', 'node', 'msg', '--to', 'home-agent-1', '--tier', 'urgent']);
+        assert.equal(call.argv.includes('spine'), false);
+        assert.equal(call.stdin, '{"source":"cron","trigger_id":"f1"}');
+    }
+    finally {
+        Object.assign(nodeMessageInternals, orig);
+    }
+});

package/dist/hearth/control-plane/__tests__/rate-limit-recurrence.test.js

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRateLimiter } from '../ingress/rate-limit.js';
+import { computeNextFire } from '../scheduler/recurrence.js';
+// Category-2 (rate limiter) + category-3 (recurrence) test. The rate-limiter
+// case locks the fix for an observed bug found during P5.5 implementation: an
+// over-eager idle-prune deleted a per-key bucket right after its first draw,
+// so per-key limiting never actually bit. The recurrence case locks the custom
+// interval-parsing + timezone plumbing (my code, not cron-parser's) that cron
+// firing depends on.
+test('the per-key token bucket actually limits a burst and refills over time', () => {
+    let nowMs = 1_000_000;
+    const limiter = createRateLimiter({ capacity: 3, refillPerSec: 1, globalCapacity: 1_000, globalRefillPerSec: 1_000, now: () => nowMs });
+    // Three tokens available for one key, then it trips (the prune bug would let
+    // every request through by resetting the bucket to full each call).
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, true);
+    const tripped = limiter.checkRate('k');
+    assert.equal(tripped.ok, false);
+    assert.equal(typeof tripped.retryAfterMs, 'number');
+    // A different key has its own independent bucket.
+    assert.equal(limiter.checkRate('other').ok, true);
+    // After ~2s one key refills 2 tokens.
+    nowMs += 2_000;
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, true);
+    assert.equal(limiter.checkRate('k').ok, false);
+});
+test('the global ceiling sheds a flood spread across many distinct keys', () => {
+    let nowMs = 0;
+    const limiter = createRateLimiter({ capacity: 100, refillPerSec: 100, globalCapacity: 5, globalRefillPerSec: 0.0001, now: () => nowMs });
+    let ok = 0;
+    for (let i = 0; i < 20; i++) {
+        if (limiter.checkRate(`key-${i}`).ok)
+            ok += 1;
+    }
+    assert.equal(ok, 5); // global ceiling caps total admits regardless of key spread
+});
+test('computeNextFire handles cron expressions, timezones, and @every intervals', () => {
+    assert.equal(computeNextFire('*/5 * * * *', 'UTC', '2026-06-30T12:01:00.000Z'), '2026-06-30T12:05:00.000Z');
+    // Interval form is timezone-independent, strictly after `after`.
+    assert.equal(computeNextFire('@every 30m', 'America/New_York', '2026-06-30T12:00:00.000Z'), '2026-06-30T12:30:00.000Z');
+    assert.equal(computeNextFire('@every 90s', 'UTC', '2026-06-30T12:00:00.000Z'), '2026-06-30T12:01:30.000Z');
+    // A tz-bearing daily schedule resolves to the correct UTC instant: 09:00
+    // EDT the same day is 13:00 UTC (after 08:00 EDT / 12:00 UTC).
+    assert.equal(computeNextFire('0 9 * * *', 'America/New_York', '2026-06-30T12:00:00.000Z'), '2026-06-30T13:00:00.000Z');
+    assert.throws(() => computeNextFire('not a cron', 'UTC', '2026-06-30T12:00:00.000Z'));
+});