@stratusagent/gateway 0.13.7 → 0.14.1

package/dist/schedules.js

@@ -2,38 +2,52 @@ import { randomUUID } from 'node:crypto';
 import { chmodSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { SENDER_TRUST_METADATA_KEY } from '@stratusagent/core';
-import { canonicalDestination, nextFireAfter, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, } from '@stratusagent/agents';
+import { leastTrusted, SENDER_TRUST_METADATA_KEY, } from '@stratusagent/core';
+import { canonicalDestination, DEFAULT_EVENT_MAX_PER_HOUR, isWithinQuietHours, nextFireAfter, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, } from '@stratusagent/agents';
 import { assertDerivedStatePathSync } from '@stratusagent/state';
+import { tightenSqliteFile } from "./sessions.js";
+/**
+ * Open `fleet.db` the way every store sharing it must: the derived-path
+ * check, an owner-only directory and file, WAL with a busy timeout, then
+ * `schema`, then the sidecars tightened. One implementation, because the
+ * schedule store and the event store (card 590) each hold their own
+ * connection to this file, and a second copy of this sequence is the one
+ * that drifts.
+ */
+export const openFleetDatabase = (filePath, options, schema) => {
+    if (options.stateHome !== undefined) {
+        assertDerivedStatePathSync(options.stateHome, filePath, 'file');
+    }
+    // Same posture as the session store sharing this file: the directory
+    // and the database must not be readable by other local users, and the
+    // sidecar chmods cover databases created under a looser umask.
+    mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const db = new DatabaseSync(filePath);
+    try {
+        chmodSync(filePath, 0o600);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    db.exec('PRAGMA journal_mode = WAL');
+    // WAL serializes writers to one at a time across the whole file, and
+    // this database is shared between two processes: the daemon claims
+    // slots and saves sessions while `stratus schedules cancel` deletes a
+    // row from another connection. Without a busy timeout the loser of that
+    // lock throws `database is locked` immediately — a cancel that silently
+    // failed would leave the schedule (and its destination grant) live.
+    // Wait for the writer instead.
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec(schema);
+    tightenSqliteFile(filePath);
+    return db;
+};
 export class SqliteScheduleStore {
     db;
     constructor(filePath, options = {}) {
-        if (options.stateHome !== undefined) {
-            assertDerivedStatePathSync(options.stateHome, filePath, 'file');
-        }
-        // Same posture as the session store sharing this file: the directory
-        // and the database must not be readable by other local users, and the
-        // sidecar chmods cover databases created under a looser umask.
-        mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
-        this.db = new DatabaseSync(filePath);
-        try {
-            chmodSync(filePath, 0o600);
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT') {
-                throw error;
-            }
-        }
-        this.db.exec('PRAGMA journal_mode = WAL');
-        // WAL serializes writers to one at a time across the whole file, and
-        // this database is shared between two processes: the daemon claims
-        // slots and saves sessions while `stratus schedules cancel` deletes a
-        // row from another connection. Without a busy timeout the loser of that
-        // lock throws `database is locked` immediately — a cancel that silently
-        // failed would leave the schedule (and its destination grant) live.
-        // Wait for the writer instead.
-        this.db.exec('PRAGMA busy_timeout = 5000');
-        this.db.exec(`
+        this.db = openFleetDatabase(filePath, options, `
       CREATE TABLE IF NOT EXISTS schedules (
         id TEXT PRIMARY KEY,
         agent_id TEXT NOT NULL,
@@ -42,16 +56,6 @@ export class SqliteScheduleStore {
         created_at TEXT NOT NULL
       )
     `);
-        for (const sensitive of [filePath, `${filePath}-wal`, `${filePath}-shm`, `${filePath}-journal`]) {
-            try {
-                chmodSync(sensitive, 0o600);
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT') {
-                    throw error;
-                }
-            }
-        }
     }
     insert(record) {
         this.db
@@ -115,11 +119,67 @@ export class SqliteScheduleStore {
 export const SCHEDULE_SESSION_ID_PREFIX = 'schedule:';
 /** Whether a session id belongs to the reserved scheduled-firing namespace. */
 export const isScheduleSessionId = (sessionId) => sessionId.startsWith(SCHEDULE_SESSION_ID_PREFIX);
+/** The longest prefix of `text` that fits in `bytes` of UTF-8, never splitting a character. */
+export const utf8Prefix = (text, bytes) => {
+    const { read } = new TextEncoder().encodeInto(text, new Uint8Array(Math.max(0, bytes)));
+    return text.slice(0, read);
+};
+/** A resumed firing carries at most this much of the stopped run's summary. */
+export const RESUME_SUMMARY_MAX_BYTES = 4_096;
+const STOPPED_EARLY_WHY = {
+    'turn-limit': 'it used all its steps',
+    'repeated-failure': 'it kept hitting the same failure',
+};
+const ordinal = (n) => {
+    const tens = n % 100;
+    const suffix = tens >= 11 && tens <= 13 ? 'th' : (['th', 'st', 'nd', 'rd'][n % 10] ?? 'th');
+    return `${n}${suffix}`;
+};
+/**
+ * What a firing that resumes sees after its schedule's prompt: when the
+ * stopped run ended and why, its own summary of what was done and left
+ * (capped), and, from the second stop in a row, that it's a repeat. The
+ * runtime posts nothing about a repeat: only the agent knows whether a
+ * person is waiting, so it's told it may post one line to the destination
+ * its schedule was approved with, when there is one.
+ */
+export const renderResumeBlock = (stoppedEarly, reply, streak, reportsSomewhere) => {
+    const text = reply?.trim() ?? '';
+    const summary = text === ''
+        ? 'It left no summary.'
+        : Buffer.byteLength(text) <= RESUME_SUMMARY_MAX_BYTES
+            ? text
+            : `${utf8Prefix(text, RESUME_SUMMARY_MAX_BYTES)}\n[summary cut at ${Math.round(RESUME_SUMMARY_MAX_BYTES / 1_024)} KB]`;
+    const when = typeof stoppedEarly.at === 'string' ? `, at ${stoppedEarly.at},` : '';
+    const why = STOPPED_EARLY_WHY[stoppedEarly.reason] ?? 'it stopped before finishing';
+    const lines = [
+        `Your last run of this schedule${when} stopped early: ${why}. What it said was done and what was left:`,
+        '',
+        summary,
+        '',
+        "Carry on from there, and don't redo finished work.",
+    ];
+    if (streak >= 2) {
+        lines.push('', `That was the ${ordinal(streak)} run in a row to stop early.`
+            + (reportsSomewhere ? " If that blocks someone, post one line to this schedule's report destination saying what's stuck." : ''));
+    }
+    return lines.join('\n');
+};
 const DEFAULT_MIN_INTERVAL_MS = 60_000;
 const DEFAULT_MAX_CONCURRENT_PER_AGENT = 1;
 const DEFAULT_TICK_MS = 1_000;
+/** A held event firing older than this expires, so a long pause never ends in a burst. */
+const EVENT_HOLD_MAX_MS = 24 * 60 * 60 * 1_000;
+/** Held firings kept per coalescing key; older ones are superseded. */
+const EVENT_HELD_PER_KEY = 5;
+/** How often the event tables are pruned to their 7-day window and row cap. */
+const EVENT_PRUNE_INTERVAL_MS = 60 * 60 * 1_000;
 export const createSchedulerRuntime = (options) => {
     const { store, dispatch, validateDestination, sessionStatus, hasAgent, log, warn } = options;
+    // Late-bindable once: see `attachEvents`.
+    let events = options.events;
+    const clock = options.now ?? (() => new Date());
+    let maxEventsPerAgent = events?.maxConcurrentPerAgent ?? 1;
     const minIntervalMs = options.limits?.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
     const maxConcurrentPerAgent = options.limits?.maxConcurrentPerAgent ?? DEFAULT_MAX_CONCURRENT_PER_AGENT;
     const tickMs = options.limits?.tickMs ?? DEFAULT_TICK_MS;
@@ -171,11 +231,48 @@ export const createSchedulerRuntime = (options) => {
             }
         }
     };
+    /**
+     * An event trigger: no slot, so the due scan never sees it; it fires when
+     * a delivery matches. Refused for a source the operator hasn't configured,
+     * now, while the person approving it can hear why.
+     */
+    const createTrigger = async (input) => {
+        if (input.cadence.kind !== 'event') {
+            throw new Error('createTrigger takes an event cadence.');
+        }
+        if (!events) {
+            throw new Error('This daemon takes no events: its config has no "events" sources and no plugin feeds one, so a trigger could never fire. The operator adds a source first.');
+        }
+        const configured = events.sources();
+        if (!configured.includes(input.cadence.source)) {
+            throw new Error(`No event source "${input.cadence.source}" is configured on this daemon. `
+                + (configured.length > 0 ? `Configured: ${configured.join(', ')}.` : 'None is.'));
+        }
+        if (input.destination) {
+            await validateDestination(input.agentId, input.destination);
+        }
+        const record = {
+            id: randomUUID(),
+            agentId: input.agentId,
+            cadence: input.cadence,
+            prompt: input.prompt,
+            ...(input.destination ? { destination: input.destination } : {}),
+            createdAt: clock().toISOString(),
+            ...(input.createdBy ? { createdBy: input.createdBy } : {}),
+            ...(input.trust ? { trust: input.trust } : {}),
+        };
+        store.insert(record);
+        log(`event trigger ${record.id} created for ${record.agentId} on source ${input.cadence.source}${record.destination ? `, reports to ${canonicalDestination(record.destination)}` : ''}`);
+        return record;
+    };
     const handle = {
         async create(input) {
             if (!hasAgent(input.agentId)) {
                 throw new Error(`Agent not found: ${input.agentId}`);
             }
+            if (input.cadence.kind === 'event') {
+                return createTrigger(input);
+            }
             enforceFloor(input);
             const now = new Date();
             const next = nextFireAfter(input.cadence, now);
@@ -215,6 +312,7 @@ export const createSchedulerRuntime = (options) => {
             const deleted = store.delete(scheduleId);
             if (deleted) {
                 log(`schedule ${scheduleId} cancelled by ${agentId}`);
+                expireTriggerFirings(scheduleId);
             }
             return deleted;
         },
@@ -240,6 +338,128 @@ export const createSchedulerRuntime = (options) => {
         const { nextFireAt: _spent, ...rest } = record;
         return { ...rest, ...extra, ...(next ? { nextFireAt: next.toISOString() } : {}) };
     };
+    /**
+     * Card 858: a readiness check that failed after an await inside a scan.
+     * Carries the reason out to `tick`, which treats it like the check at the
+     * top of the tick: the scheduler stops, and at start the failure is
+     * `start()`'s rejection.
+     */
+    class NotReady extends Error {
+        scheduleId;
+        reason;
+        constructor(scheduleId, reason) {
+            super(reason instanceof Error ? reason.message : String(reason));
+            this.scheduleId = scheduleId;
+            this.reason = reason;
+        }
+    }
+    const stillReady = async (scheduleId) => {
+        if (!options.ready) {
+            return;
+        }
+        try {
+            await options.ready();
+        }
+        catch (error) {
+            stopped = true;
+            throw new NotReady(scheduleId, error);
+        }
+    };
+    /**
+     * What the firing about to be claimed carries from the one in
+     * `lastSessionId` (card 858): `'defer'` while that run is still going (a
+     * schedule never claims past a run whose outcome it hasn't read, or that
+     * run's summary is lost and the streak breaks), otherwise the new streak
+     * and the stopped run to resume from, if any. Undefined when the daemon
+     * gave no `previousRun`: the claim then leaves both fields as they are.
+     */
+    const planResume = async (record, last, slot) => {
+        const deferKey = `${record.id}:${slot}:previous`;
+        const holdBack = () => {
+            if (!deferralsWarned.has(deferKey)) {
+                deferralsWarned.add(deferKey);
+                warn(`schedule ${record.id}: its previous run ${last} is still going; deferring this firing (slot ${slot})`);
+            }
+            return 'defer';
+        };
+        // Started by this daemon and not settled: its session may not exist yet.
+        if (activeFirings.has(last)) {
+            return holdBack();
+        }
+        const read = options.previousRun;
+        if (!read) {
+            return undefined;
+        }
+        const streak = record.stoppedEarlyStreak ?? 0;
+        const readRun = async (sessionId) => {
+            try {
+                return await read(sessionId);
+            }
+            catch (error) {
+                warn(`schedule ${record.id}: could not read its previous run ${sessionId} (${error instanceof Error ? error.message : String(error)}); firing without it`);
+                return 'unreadable';
+            }
+        };
+        const previous = await readRun(last);
+        if (previous === 'unreadable') {
+            // No outcome to count: the streak stays, and there's no block.
+            return { streak };
+        }
+        if (previous !== undefined) {
+            if (previous.status === 'running' || previous.status === 'pending_approval') {
+                return holdBack();
+            }
+            deferralsWarned.delete(deferKey);
+            return previous.stoppedEarly !== undefined
+                ? { streak: streak + 1, from: { sessionId: last, run: previous } }
+                : { streak: 0 };
+        }
+        deferralsWarned.delete(deferKey);
+        const fallback = record.resumeFrom;
+        if (fallback !== undefined && fallback.firing === last) {
+            // That firing was claimed and never started: the daemon died before
+            // its session existed, or refused it on the way down. It has no
+            // outcome, so the streak stays, and it carried a checkpoint, which
+            // this firing carries instead.
+            const from = await readRun(fallback.from);
+            if (from === 'unreadable') {
+                return { streak };
+            }
+            if (from?.stoppedEarly !== undefined) {
+                return { streak, from: { sessionId: fallback.from, run: from } };
+            }
+            log(`schedule ${record.id}: previous run ${last} never started, and the run it resumed from (${fallback.from}) is gone; starting fresh`);
+            return { streak: 0 };
+        }
+        // Removed after it ran, a home restored without it, or a fallback left
+        // for another firing (an older build moved `lastSessionId` without it).
+        // Replaying an older checkpoint here could redo finished work.
+        log(`schedule ${record.id}: previous run ${last} not found; starting fresh`);
+        return { streak: 0 };
+    };
+    /**
+     * A resumed firing whose session exists no longer needs its fallback: the
+     * next claim reads that session. Only while the row still names this
+     * firing, through the slot claim's own conditional write, so a later
+     * claim's fallback is never the one removed. Best effort: one left
+     * behind is used only while `lastSessionId` names no session.
+     */
+    const dropFallback = async (scheduleId, sessionId) => {
+        try {
+            if ((await sessionStatus(sessionId)) === undefined) {
+                return;
+            }
+            const current = store.get(scheduleId);
+            if (current?.resumeFrom?.firing !== sessionId) {
+                return;
+            }
+            const { resumeFrom: _done, ...rest } = current;
+            store.claimSlot(rest, current.nextFireAt ?? '');
+        }
+        catch (error) {
+            warn(`schedule ${scheduleId}: could not clear the resume fallback for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
     /**
      * Fire one due schedule: consume the slot durably, then dispatch.
      *
@@ -249,7 +469,7 @@ export const createSchedulerRuntime = (options) => {
      * advance past it with a log line, never replay. Anything else fires,
      * which on time is the normal case and late is the single catch-up.
      */
-    const fireOrSkip = (record, now) => {
+    const fireOrSkip = async (record, now) => {
         const slot = record.nextFireAt;
         if (!slot) {
             return;
@@ -270,11 +490,15 @@ export const createSchedulerRuntime = (options) => {
             // and the line that blamed downtime for it sent an operator to look
             // for a restart that never happened.
             const deferralKey = `${record.id}:${slot}`;
-            log(deferralsWarned.has(deferralKey)
-                ? `schedule ${record.id}: the firing deferred by the per-agent cap (slot ${slot}) outlasted its window; skipping to ${next ? next.toISOString() : 'never'}`
-                : `schedule ${record.id}: missed firing(s) while the daemon was down; skipping to ${next ? next.toISOString() : 'never'}`);
+            const skippingTo = next ? next.toISOString() : 'never';
+            log(deferralsWarned.has(`${deferralKey}:previous`)
+                ? `schedule ${record.id}: the firing deferred while its previous run was still going (slot ${slot}) outlasted its window; skipping to ${skippingTo}`
+                : deferralsWarned.has(deferralKey)
+                    ? `schedule ${record.id}: the firing deferred by the per-agent cap (slot ${slot}) outlasted its window; skipping to ${skippingTo}`
+                    : `schedule ${record.id}: missed firing(s) while the daemon was down; skipping to ${skippingTo}`);
             store.claimSlot(withNextFire(record, next), slot);
             deferralsWarned.delete(deferralKey);
+            deferralsWarned.delete(`${deferralKey}:previous`);
             return;
         }
         if (options.paused?.() === true) {
@@ -307,6 +531,25 @@ export const createSchedulerRuntime = (options) => {
             return;
         }
         deferralsWarned.delete(`${record.id}:${slot}`);
+        // Card 858: what this firing carries from the one before it. Read here,
+        // at the claim, so a daemon killed after a wrap-up still leaves the
+        // stopped session for this read; it's the one copy of the checkpoint.
+        let plan;
+        if (record.cadence.kind !== 'at' && record.lastSessionId !== undefined) {
+            const planned = await planResume(record, record.lastSessionId, slot);
+            if (planned === 'defer') {
+                return;
+            }
+            if (planned !== undefined) {
+                // An await sat between the readiness check and the claim below,
+                // which writes into the schedules table: check both again.
+                if (stopped) {
+                    return;
+                }
+                await stillReady(record.id);
+                plan = planned;
+            }
+        }
         const firedAt = now.toISOString();
         const sessionId = `${SCHEDULE_SESSION_ID_PREFIX}${record.id}:${slot}`;
         // Advance from the scheduled slot, not from now: `following` is the
@@ -320,28 +563,53 @@ export const createSchedulerRuntime = (options) => {
         // and spent ATOMICALLY against the slot this tick read: a schedule
         // cancelled between the due scan and here is gone, and its prompt
         // must not run on a grant that was just revoked.
-        if (!store.claimSlot(withNextFire(record, next, { lastFiredAt: firedAt, lastSessionId: sessionId }), slot)) {
+        let claimed = withNextFire(record, next, { lastFiredAt: firedAt, lastSessionId: sessionId });
+        if (plan !== undefined) {
+            // The streak and the fallback are written in the same claim as the
+            // slot, so a crash can't leave one without the other.
+            const { stoppedEarlyStreak: _streak, resumeFrom: _resumeFrom, ...rest } = claimed;
+            claimed = {
+                ...rest,
+                ...(plan.streak > 0 ? { stoppedEarlyStreak: plan.streak } : {}),
+                ...(plan.from !== undefined ? { resumeFrom: { firing: sessionId, from: plan.from.sessionId } } : {}),
+            };
+        }
+        if (!store.claimSlot(claimed, slot)) {
             log(`schedule ${record.id}: slot ${slot} was cancelled or already claimed; not firing`);
             return;
         }
-        runningPerAgent.set(record.agentId, running + 1);
+        const resumeFrom = plan?.from;
+        // Re-read: a firing of this agent's may have settled during the await above.
+        runningPerAgent.set(record.agentId, (runningPerAgent.get(record.agentId) ?? 0) + 1);
         activeFirings.add(sessionId);
         const firing = dispatch({
             sessionId,
             agentId: record.agentId,
-            userMessage: record.prompt,
+            userMessage: resumeFrom === undefined
+                ? record.prompt
+                : [record.prompt, renderResumeBlock(resumeFrom.run.stoppedEarly, resumeFrom.run.reply, plan.streak, record.destination !== undefined)].join('\n\n'),
             metadata: {
                 [SCHEDULED_TURN_METADATA_KEY]: true,
                 [SCHEDULE_ID_METADATA_KEY]: record.id,
                 // The firing's "sender" is the session that wrote the prompt, at
                 // the label it had then; a schedule set before labels existed is
-                // `unknown`, like every other record from before.
-                [SENDER_TRUST_METADATA_KEY]: record.trust ?? 'unknown',
+                // `unknown`, like every other record from before. A resumed firing
+                // also carries the stopped run's own words, so it's sent at the
+                // lower of the two, the rule `agent.delegate` uses for a child: a
+                // run that read a web page can't launder that page's text into a
+                // turn at the schedule's label.
+                [SENDER_TRUST_METADATA_KEY]: resumeFrom === undefined
+                    ? record.trust ?? 'unknown'
+                    : leastTrusted(record.trust ?? 'unknown', resumeFrom.run.trust),
             },
         }).then(() => {
             log(`schedule ${record.id} fired — session ${sessionId} completed`);
         }, (error) => {
             warn(`schedule ${record.id} firing failed: ${error instanceof Error ? error.message : String(error)}`);
+        }).then(async () => {
+            if (resumeFrom !== undefined) {
+                await dropFallback(record.id, sessionId);
+            }
         }).finally(() => {
             activeFirings.delete(sessionId);
             const count = (runningPerAgent.get(record.agentId) ?? 1) - 1;
@@ -360,6 +628,204 @@ export const createSchedulerRuntime = (options) => {
         inflight.add(firing);
         void firing.finally(() => inflight.delete(firing));
     };
+    // ---- event triggers (card 590) ------------------------------------------
+    let started = false;
+    /** When the event tables were last pruned; unset until the first pass after start. */
+    let eventsPrunedAt;
+    /** Batches this process dispatched and has not seen settle. Empty after a restart, which is what makes a claimed batch recoverable. */
+    const inflightBatches = new Set();
+    const runningEventsPerAgent = new Map();
+    /** Groups whose deferral under the per-agent slot was already logged. */
+    const eventDeferralsWarned = new Set();
+    /** A trigger's waiting firings never go out once it is cancelled. */
+    const expireTriggerFirings = (triggerId) => {
+        if (!events) {
+            return;
+        }
+        const ids = events.store.open()
+            .filter((row) => row.triggerId === triggerId && !(row.batchKey !== undefined && inflightBatches.has(row.batchKey)))
+            .map((row) => row.id);
+        if (ids.length > 0) {
+            events.store.retire(ids, 'expired', 'Its trigger was cancelled.', clock().toISOString());
+        }
+    };
+    const fireEventBatch = (record, rows, batchKey) => {
+        const sessionId = rows[0].sessionId;
+        const ids = rows.map((row) => row.id);
+        inflightBatches.add(batchKey);
+        runningEventsPerAgent.set(record.agentId, (runningEventsPerAgent.get(record.agentId) ?? 0) + 1);
+        activeFirings.add(sessionId);
+        const firing = dispatch({
+            sessionId,
+            agentId: record.agentId,
+            // The trigger's prompt, then each event in the order it arrived.
+            userMessage: [record.prompt, ...rows.map((row) => row.block ?? '')].join('\n\n'),
+            idempotencyKey: batchKey,
+            metadata: {
+                [SCHEDULED_TURN_METADATA_KEY]: true,
+                [SCHEDULE_ID_METADATA_KEY]: record.id,
+                // The event text came from outside: a valid signature proves who
+                // delivered it, not who wrote it (anyone can comment on a PR). So
+                // the turn runs at `external`, under the gate that applies after
+                // reading a web page, whatever the trigger's creator was trusted at.
+                [SENDER_TRUST_METADATA_KEY]: 'external',
+            },
+        }).then(() => {
+            events?.store.finish(ids, { status: 'fired' }, clock().toISOString());
+            log(`event trigger ${record.id} fired — session ${sessionId} completed (${ids.length} event${ids.length === 1 ? '' : 's'})`);
+        }, (error) => {
+            const reason = error instanceof Error ? error.message : String(error);
+            // Refused by a daemon on its way down, or cut short by its stop and
+            // left for the next start: the batch stays claimed, and the next
+            // start sends it again under its key, which continues that turn
+            // (or runs it, if it never started) rather than losing the events.
+            // Matched by name, as a channel matches it. Only once this
+            // scheduler has stopped, which the gateway does before it refuses
+            // or aborts anything: a batch left claimed while ticks still ran
+            // would go straight out again.
+            if (stopped && error instanceof Error && error.name === 'GatewayStoppingError') {
+                log(`event trigger ${record.id}: ${reason} The batch stays claimed for the next start.`);
+                return;
+            }
+            events?.store.finish(ids, { status: 'failed', reason }, clock().toISOString());
+            warn(`event trigger ${record.id} firing failed: ${reason}`);
+        }).finally(() => {
+            activeFirings.delete(sessionId);
+            inflightBatches.delete(batchKey);
+            const count = (runningEventsPerAgent.get(record.agentId) ?? 1) - 1;
+            if (count > 0) {
+                runningEventsPerAgent.set(record.agentId, count);
+            }
+            else {
+                runningEventsPerAgent.delete(record.agentId);
+            }
+        });
+        inflight.add(firing);
+        void firing.finally(() => inflight.delete(firing));
+    };
+    /**
+     * The hold-or-fire step, for every waiting event firing: a fresh match, a
+     * hold whose window opened, and at startup whatever a crash left. One
+     * path, so a recovered firing still waits out quiet hours and counts
+     * against its trigger's hour like any other.
+     */
+    const processEvents = (now) => {
+        // Not before start(): a held daemon's scheduler never starts, and its
+        // waiting firings must not go out through a delivery's kick either.
+        // Read once: the closures below would not see a narrowed `let`.
+        const current = events;
+        if (!current || stopped || !started) {
+            return;
+        }
+        const nowIso = now.toISOString();
+        // The 7-day window and the row cap hold only if something enforces
+        // them, and this is the loop that runs for the daemon's whole life: at
+        // the start-up pass, then hourly. Kept off the hold-or-fire path's
+        // failure: a prune that can't get the lock waits for the next hour.
+        if (eventsPrunedAt === undefined || now.getTime() - eventsPrunedAt >= EVENT_PRUNE_INTERVAL_MS) {
+            eventsPrunedAt = now.getTime();
+            try {
+                current.store.prune(nowIso);
+            }
+            catch (error) {
+                warn(`events: could not prune old deliveries: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const triggers = new Map();
+        const triggerFor = (id) => {
+            if (!triggers.has(id)) {
+                const record = store.get(id);
+                triggers.set(id, record?.cadence.kind === 'event' ? record : undefined);
+            }
+            return triggers.get(id);
+        };
+        // A claimed batch stays itself; free firings group by trigger and key.
+        // Map order is first appearance in `open()`, oldest first.
+        const groups = new Map();
+        for (const row of current.store.open()) {
+            if (row.batchKey !== undefined && inflightBatches.has(row.batchKey)) {
+                continue;
+            }
+            const trigger = triggerFor(row.triggerId);
+            if (!trigger || trigger.agentId !== row.agentId) {
+                current.store.retire([row.id], 'expired', 'Its trigger was cancelled.', nowIso);
+                continue;
+            }
+            // Holds expire; a claim does not. A batch claimed before a crash may
+            // already have reached the gateway, and its key either continues that
+            // turn or sends an event that never went out, however long the
+            // daemon was down.
+            if (row.status !== 'firing' && now.getTime() - Date.parse(row.createdAt) > EVENT_HOLD_MAX_MS) {
+                current.store.retire([row.id], 'expired', 'Held for more than 24 hours.', nowIso);
+                continue;
+            }
+            const key = row.batchKey !== undefined ? `batch\n${row.batchKey}` : `key\n${row.triggerId}\n${row.coalescingKey}`;
+            const group = groups.get(key) ?? [];
+            group.push(row);
+            groups.set(key, group);
+        }
+        const holdAs = (rows, status) => {
+            const ids = rows.filter((row) => row.status !== status).map((row) => row.id);
+            if (ids.length > 0) {
+                current.store.hold(ids, status, nowIso);
+            }
+        };
+        for (const [groupKey, all] of groups) {
+            const trigger = triggerFor(all[0].triggerId);
+            if (trigger.cadence.kind !== 'event') {
+                continue;
+            }
+            let rows = all;
+            const batched = rows[0].batchKey !== undefined;
+            if (!batched && rows.length > EVENT_HELD_PER_KEY) {
+                const dropped = rows.slice(0, rows.length - EVENT_HELD_PER_KEY);
+                current.store.retire(dropped.map((row) => row.id), 'superseded', `Over ${EVENT_HELD_PER_KEY} waiting for one subject; newer ones were kept.`, nowIso);
+                rows = rows.slice(-EVENT_HELD_PER_KEY);
+            }
+            const { quietHours } = trigger.cadence;
+            if (options.paused?.() === true || (quietHours !== undefined && isWithinQuietHours(quietHours, now))) {
+                holdAs(rows, 'held');
+                continue;
+            }
+            const running = runningEventsPerAgent.get(trigger.agentId) ?? 0;
+            if (running >= maxEventsPerAgent) {
+                if (!eventDeferralsWarned.has(groupKey)) {
+                    eventDeferralsWarned.add(groupKey);
+                    log(`event trigger ${trigger.id}: ${trigger.agentId} already has ${running} event firing(s) running; this one waits`);
+                }
+                continue;
+            }
+            eventDeferralsWarned.delete(groupKey);
+            const maxPerHour = trigger.cadence.maxPerHour ?? DEFAULT_EVENT_MAX_PER_HOUR;
+            const hourAgo = new Date(now.getTime() - 3_600_000).toISOString();
+            if (current.store.turnsStartedSince(trigger.id, hourAgo, rows[0].batchKey) >= maxPerHour) {
+                if (!batched && rows.length > 1) {
+                    current.store.retire(rows.slice(0, -1).map((row) => row.id), 'superseded', 'A newer event for the same subject replaced it while over the hourly limit.', nowIso);
+                    rows = rows.slice(-1);
+                }
+                holdAs(rows, 'rate_limited');
+                continue;
+            }
+            const batchKey = rows[0].batchKey ?? rows[rows.length - 1].dispatchKey;
+            if (!current.store.claim(rows.map((row) => row.id), batchKey, nowIso, { triggerId: trigger.id })) {
+                continue;
+            }
+            // When it last went out, on the trigger's own row, so `schedule.list`,
+            // `stratus schedules` and the control API show it the way they show a
+            // timed schedule's. The same conditional write a slot claim makes; an
+            // event trigger's slot is always empty, so it only requires the row.
+            // A cancel landing after the claim above makes this a no-op, and the
+            // claimed batch still goes, as a claimed slot does. An audit field, so
+            // a write that fails is warned and never keeps a claimed batch back.
+            try {
+                store.claimSlot(withNextFire(trigger, undefined, { lastFiredAt: nowIso, lastSessionId: rows[0].sessionId }), '');
+            }
+            catch (error) {
+                warn(`event trigger ${trigger.id}: could not record its last firing: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            fireEventBatch(trigger, rows, batchKey);
+        }
+    };
     /**
      * `propagateReadiness` is the startup tick's: a readiness failure there
      * has a caller to reach — `start()`, whose rejection is the gateway's
@@ -383,15 +849,23 @@ export const createSchedulerRuntime = (options) => {
             }
         }
         try {
-            const now = new Date();
+            const now = clock();
             for (const record of store.due(now.toISOString())) {
                 if (stopped) {
                     break;
                 }
-                fireOrSkip(record, now);
+                await fireOrSkip(record, now);
             }
+            processEvents(now);
         }
         catch (error) {
+            if (error instanceof NotReady) {
+                if (propagateReadiness) {
+                    throw error.reason;
+                }
+                warn(`scheduler stopped before claiming schedule ${error.scheduleId}'s firing: ${error.message}`);
+                return;
+            }
             warn(`scheduler tick failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         if (!stopped) {
@@ -406,6 +880,31 @@ export const createSchedulerRuntime = (options) => {
     };
     return {
         handle,
+        eventTriggers(sourceId) {
+            return store.list()
+                .filter((record) => record.cadence.kind === 'event' && record.cadence.source === sourceId)
+                .map((record) => ({
+                triggerId: record.id,
+                agentId: record.agentId,
+                source: sourceId,
+                filter: record.cadence.filter,
+            }));
+        },
+        attachEvents(attached) {
+            if (events) {
+                throw new Error('This scheduler already takes events; its sources are read live, so add a source there instead.');
+            }
+            events = attached;
+            maxEventsPerAgent = attached.maxConcurrentPerAgent ?? 1;
+        },
+        kickEvents() {
+            try {
+                processEvents(clock());
+            }
+            catch (error) {
+                warn(`event triggers: processing failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
         isPreauthorized(session, destination) {
             // A live firing of this scheduler's, first: session metadata is
             // written by whoever dispatches, so on its own it proves nothing —
@@ -463,6 +962,7 @@ export const createSchedulerRuntime = (options) => {
             const deleted = store.delete(scheduleId);
             if (deleted) {
                 log(`schedule ${scheduleId} cancelled`);
+                expireTriggerFirings(scheduleId);
             }
             return deleted;
         },
@@ -497,6 +997,7 @@ export const createSchedulerRuntime = (options) => {
             // The first tick's readiness check propagates too: the stamp can
             // advance between the check above and here, and a `start()` that
             // resolved after noticing would let the gateway's sweeps run.
+            started = true;
             await tick(true);
         },
         stop() {