@north-light/api 0.3.580 → 0.3.587

package/dist/core/canvas/crons.js

@@ -0,0 +1,541 @@
+// crons.ts — the CRONS + CRON_RUNS data-access layer (canvas.db, migration
+// v21). One-module-per-table: ALL SQL touching
+// `crons`/`cron_runs` lives HERE and nowhere else.
+//
+// A CRON is the one scheduling primitive of the cron spec: run this bash,
+// then. The row decides WHEN (fire_at, advanced by the daemon for a
+// recurrence) and snapshots the execution context (cwd/env/profile) at arm
+// time so a job never changes behavior because its creator went away.
+// `created_by` is provenance only — no FK, never cascades. `anchor_node` is
+// the opt-in node coupling carrying the sole FK (ON DELETE CASCADE).
+//
+// Each function is a single-statement query mirroring the canvas.ts atomic-
+// setter pattern — no read-modify-write, serialized by WAL — except the two
+// deliberate multi-statement boundaries under withCanvasWrite (cancelCron's
+// kill-then-delete, recordCronRun's insert-then-prune ring).
+//
+// `cron_id` is CALLER-SUPPLIED (the daemon API handler mints it): the canvas
+// layer never mints ids.
+//
+// Lease primitives (acquireCronRunLease/releaseCronRunLease/runningCrons)
+// serve the daemon-owned run executor in src/daemon/cron-run.ts.
+import { withCanvasWrite, openDb } from './db.js';
+import { capturePidIdentities, identitiesMatch, killProcessGroup } from './pid.js';
+import { isProfilePaused } from '../profiles/manifest.js';
+import { stopAppProcess } from '../spaces/process.js';
+import { emitEvent } from '../events/emit.js';
+import { personId } from './person.js';
+/** Ring bound for `cron_runs`: recordCronRun prunes each cron's history to
+ *  its most recent this-many rows. */
+export const CRON_RUN_RING = 20;
+function scopesFrom(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter((s) => typeof s === 'string') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function cronFrom(r) {
+    return {
+        cron_id: r['cron_id'],
+        name: r['name'],
+        created_by: r['created_by'] ?? null,
+        grantee: r['grantee'],
+        sub: r['sub'] ?? personId(),
+        grant_id: r['grant_id'] ?? null,
+        scopes: scopesFrom(r['scopes_json']),
+        origin_run_id: r['origin_run_id'] ?? null,
+        run_execution_id: r['run_execution_id'] ?? null,
+        armed_from_exec: Number(r['armed_from_exec'] ?? 0) !== 0,
+        isolated: Number(r['isolated']) !== 0,
+        command: r['command'],
+        fire_at: r['fire_at'],
+        recur: r['recur'] ?? null,
+        tz: r['tz'] ?? null,
+        expires_at: r['expires_at'] ?? null,
+        anchor_node: r['anchor_node'] ?? null,
+        cancel_on_wake: Number(r['cancel_on_wake']) !== 0,
+        cwd: r['cwd'],
+        env_json: r['env_json'] ?? null,
+        profile: r['profile'] ?? null,
+        scope: r['scope'],
+        run_timeout_s: Number(r['run_timeout_s']),
+        overlap: r['overlap'],
+        on_output: r['on_output'],
+        sink: r['sink'],
+        tier: r['tier'],
+        last_output_hash: r['last_output_hash'] ?? null,
+        held: Number(r['held']) !== 0,
+        last_poke_at: r['last_poke_at'] ?? null,
+        state: r['state'],
+        run_state: r['run_state'],
+        run_pid: r['run_pid'] ?? null,
+        run_pid_identity: r['run_pid_identity'] ?? null,
+        run_started_at: r['run_started_at'] ?? null,
+        run_lease_owner: r['run_lease_owner'] ?? null,
+        run_out_of_band: Number(r['run_out_of_band']) !== 0,
+        created: r['created'],
+        updated: r['updated'],
+    };
+}
+/** Decode the stored cron sink JSON. A malformed or unrecognised value has no sink. */
+export function parseCronSink(sinkJson) {
+    try {
+        const sink = JSON.parse(sinkJson);
+        if (typeof sink['node'] === 'string')
+            return { kind: 'node', node: sink['node'] };
+        if (typeof sink['spawn'] === 'string')
+            return { kind: 'spawn', spawn: sink['spawn'] };
+        if (sink['human'] === true)
+            return { kind: 'human' };
+    }
+    catch {
+        // A malformed stored value cannot deliver but remains listable and runnable.
+    }
+    return null;
+}
+/** Render a stored cron sink as the arm-time CLI spec, or null when it has no destination. */
+export function cronSinkDisplay(sinkJson) {
+    const sink = parseCronSink(sinkJson);
+    if (sink === null)
+        return null;
+    switch (sink.kind) {
+        case 'node':
+            return `node:${sink.node}`;
+        case 'spawn':
+            return `spawn:${sink.spawn}`;
+        case 'human':
+            return 'human';
+    }
+}
+// Signal safety
+/** Signal only a run whose current pid identity matches its lease. A daemon
+ *  replacement can leave a pid number that the kernel later reuses. */
+export async function stopLeasedCronRun(c, signal = 'SIGTERM') {
+    if (!verifyLeasedCronRun(c))
+        return false;
+    if (process.platform !== 'linux') {
+        killProcessGroup(c.run_pid, signal);
+        return true;
+    }
+    try {
+        await stopAppProcess(c.run_pid, signal, c.anchor_node ?? undefined);
+        return true;
+    }
+    catch (error) {
+        if (!verifyLeasedCronRun(c))
+            return false;
+        throw error;
+    }
+}
+/** Start the signal inside the canvas write boundary; log a launcher refusal.
+ *  Recovery uses the awaitable form so it cannot settle while the run lives. */
+export function killLeasedCronRun(c, signal = 'SIGTERM') {
+    if (!verifyLeasedCronRun(c))
+        return false;
+    void stopLeasedCronRun(c, signal).catch((error) => {
+        emitEvent({ level: 'error', event: 'cron.run.stop_failed', error, fields: { cron_id: c.cron_id, pid: c.run_pid } });
+    });
+    return true;
+}
+/** Positive proof that `run_pid` is STILL the process this lease launched:
+ *  a stored identity exists, the `ps` probe succeeded, the pid has a row, and
+ *  its current identity matches. Anything else — including "we could not tell"
+ *  — is `false`, which is what makes `killLeasedCronRun` fail closed. */
+export function verifyLeasedCronRun(c) {
+    const pid = c.run_pid;
+    if (pid == null || c.run_pid_identity == null)
+        return false;
+    const table = capturePidIdentities([pid]);
+    if (table === null)
+        return false; // probe itself failed — no information
+    const current = table.get(pid);
+    if (current === undefined)
+        return false; // pid genuinely gone
+    return identitiesMatch(current, c.run_pid_identity);
+}
+// Writes
+/** INSERT one cron row from the pinned arm spec, returning its (caller-
+ *  supplied) `cron_id` plus the ids of any deadline it displaced. Stamps
+ *  `created`/`updated`; lease fields start idle.
+ *
+ *  ONE DEADLINE PER ANCHOR: a `cancel_on_wake` arm REPLACES the anchor's
+ *  pending cancel-on-wake cron rather than stacking a second one — re-arming a
+ *  bounded wait moves the deadline. This is the invariant the dropped
+ *  `triggers` partial unique index carried, and `idx_crons_deadline`
+ *  (`crons(anchor_node) WHERE cancel_on_wake = 1`) is still its structural
+ *  backstop; the displace-then-insert runs inside ONE transaction that first
+ *  locks the anchor node row, so two concurrent arms replace one another in
+ *  sequence. Only the anchor's own cancel-on-wake
+ *  rows are displaced — a standing declarative cron on the same anchor is
+ *  untouched. Any displaced in-flight run's process group is killed first (the
+ *  cancelCron discipline). */
+export async function armCron(spec) {
+    return await withCanvasWrite(async (db) => {
+        const replaced = [];
+        if (spec.cancel_on_wake && spec.anchor_node !== null) {
+            // Serialize concurrent re-arms on the anchor: the second waits here until the first commits, then sees (and replaces) its row.
+            await db.prepare('SELECT 1 FROM nodes WHERE node_id = ? FOR UPDATE').get(spec.anchor_node);
+            const rows = (await db.prepare('SELECT * FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1')
+                .all(spec.anchor_node)).map(cronFrom);
+            for (const c of rows) {
+                if (c.run_state === 'running')
+                    killLeasedCronRun(c);
+                await db.prepare('DELETE FROM crons WHERE cron_id = ?').run(c.cron_id);
+                replaced.push(c.cron_id);
+            }
+        }
+        await insertCron(db, spec);
+        return { cron_id: spec.cron_id, replaced };
+    });
+}
+async function insertCron(db, spec) {
+    const now = new Date().toISOString();
+    await db.prepare(`INSERT INTO crons (
+         cron_id, name, created_by, grantee, sub, grant_id, scopes_json, origin_run_id, isolated, command, fire_at, recur, tz, expires_at,
+         anchor_node, cancel_on_wake, cwd, env_json, profile, scope,
+         run_timeout_s, overlap, on_output, sink, tier, created, updated, armed_from_exec
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.cron_id, spec.name, spec.created_by, spec.grantee ?? 'app:terminal', spec.sub ?? personId(), spec.grant_id ?? null, spec.scopes == null ? null : JSON.stringify(spec.scopes), spec.origin_run_id ?? null, spec.isolated ? 1 : 0, spec.command, spec.fire_at, spec.recur, spec.tz, spec.expires_at, spec.anchor_node, spec.cancel_on_wake ? 1 : 0, spec.cwd, spec.env_json, spec.profile, spec.scope, spec.run_timeout_s, spec.overlap, spec.on_output, spec.sink, spec.tier, now, now, spec.armed_from_exec ? 1 : 0);
+}
+/** SELECT one cron by id. */
+export async function getCron(cron_id) {
+    const row = await (await openDb()).prepare('SELECT * FROM crons WHERE cron_id = ?').get(cron_id);
+    return row === undefined ? null : cronFrom(row);
+}
+/** List crons for a scope, next-fire order. `{profile}` = that profile's
+ *  profile-scoped rows; `{global:true}` = global-scoped rows only;
+ *  `{all:true}` = every cron on the canvas. */
+export async function listCrons(scope) {
+    const db = await openDb();
+    let rows;
+    if ('profile' in scope) {
+        rows = await db.prepare("SELECT * FROM crons WHERE scope = 'profile' AND profile = ? ORDER BY fire_at")
+            .all(scope.profile);
+    }
+    else if ('global' in scope) {
+        rows = await db.prepare("SELECT * FROM crons WHERE scope = 'global' ORDER BY fire_at")
+            .all();
+    }
+    else {
+        rows = await db.prepare('SELECT * FROM crons ORDER BY fire_at').all();
+    }
+    return rows.map(cronFrom);
+}
+/** DELETE one cron — the explicit user/surface cancel. Idempotent: an absent
+ *  row is a no-op `false`. Kills any in-flight run process group before
+ *  deleting unless the daemon has proved the caller is that exact run; then
+ *  the process must finish and deliver its already-produced output. The lease
+ *  acquisition still linearizes before this selection (the run is observed
+ *  and killed) or after the delete (and loses the lease). The FK cascade reaps
+ *  the cron's run history with it. */
+export async function cancelCron(cron_id, options) {
+    return await withCanvasWrite(async (db) => {
+        const row = await db.prepare('SELECT * FROM crons WHERE cron_id = ?').get(cron_id);
+        if (row === undefined)
+            return false;
+        const cron = cronFrom(row);
+        if (cron.run_state === 'running' && options?.preserveRunningProcess !== true)
+            killLeasedCronRun(cron);
+        await db.prepare('DELETE FROM crons WHERE cron_id = ?').run(cron_id);
+        return true;
+    });
+}
+function profileCronWhere(profileId, anchorNodeIds) {
+    const anchors = [...new Set(anchorNodeIds)];
+    if (anchors.length === 0)
+        return { sql: 'profile = ?', params: [profileId] };
+    return {
+        sql: `profile = ? OR anchor_node IN (${anchors.map(() => '?').join(',')})`,
+        params: [profileId, ...anchors],
+    };
+}
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export async function cronIdsForProfileDeletion(profileId, anchorNodeIds) {
+    const where = profileCronWhere(profileId, anchorNodeIds);
+    return (await (await openDb())
+        .prepareUncached(`SELECT cron_id FROM crons WHERE ${where.sql} ORDER BY created, cron_id`)
+        .all(...where.params)).map(({ cron_id }) => cron_id);
+}
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export async function deleteCronsForProfile(profileId, anchorNodeIds) {
+    return await withCanvasWrite(async (db) => {
+        const where = profileCronWhere(profileId, anchorNodeIds);
+        const rows = (await db
+            .prepareUncached(`SELECT * FROM crons WHERE ${where.sql} ORDER BY created, cron_id`)
+            .all(...where.params)).map(cronFrom);
+        for (const cron of rows) {
+            if (cron.run_state === 'running')
+                killLeasedCronRun(cron);
+        }
+        await db.prepareUncached(`DELETE FROM crons WHERE ${where.sql}`).run(...where.params);
+        return rows.map(({ cron_id }) => cron_id);
+    });
+}
+/** Cron ids whose snapshotted profile will be detached. */
+export async function cronIdsForProfileDetach(profileId) {
+    return (await (await openDb()).prepare('SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id')
+        .all(profileId)).map(({ cron_id }) => cron_id);
+}
+/** Preserve matching crons while removing their deleted profile dependency. */
+export async function globalizeCronsForProfile(profileId) {
+    return await withCanvasWrite(async (db) => {
+        const ids = (await db.prepare('SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id')
+            .all(profileId)).map(({ cron_id }) => cron_id);
+        if (ids.length > 0) {
+            await db.prepare("UPDATE crons SET profile = NULL, scope = 'global', updated = ? WHERE profile = ?")
+                .run(new Date().toISOString(), profileId);
+        }
+        return ids;
+    });
+}
+/** DELETE one cron by id — one-shot consumption after its run settles.
+ *  Returns whether a live row was removed, so a consumer racing an explicit
+ *  cancel can no-op instead of double-settling. */
+export async function consumeCron(cron_id) {
+    return (await (await openDb()).prepare('DELETE FROM crons WHERE cron_id = ?').run(cron_id)).changes > 0;
+}
+/** UPDATE `state` (active|paused). Returns whether a row changed — pausing an
+ *  already-paused cron (or a gone one) reports `false`. Pausing does NOT kill
+ *  an in-flight run: the run settles normally, the row just stops being due. */
+export async function setCronState(cron_id, state) {
+    return ((await (await openDb()).prepare('UPDATE crons SET state = ?, updated = ? WHERE cron_id = ?')
+        .run(state, new Date().toISOString(), cron_id)).changes > 0);
+}
+/** UPDATE `last_output_hash` — the on-change disposition's memory of the
+ *  previous run's stdout. Written after EVERY settled run of an on-change
+ *  cron, delivered or not. */
+export async function setCronLastOutputHash(cron_id, hash) {
+    await (await openDb()).prepare('UPDATE crons SET last_output_hash = ?, updated = ? WHERE cron_id = ?')
+        .run(hash, new Date().toISOString(), cron_id);
+}
+/** True when a cron can still wake this node. An active deadline is a wake
+ * source by its anchor; output delivery is a wake source by its decoded node
+ * sink. Scheduled rows must remain active and unexpired, while a leased run
+ * remains eligible through settlement even if it has since been paused or
+ * expired. */
+export async function hasPendingCronWake(nodeId) {
+    const rows = await (await openDb()).prepare(`SELECT anchor_node, cancel_on_wake, sink
+     FROM crons
+     WHERE (anchor_node = ? AND cancel_on_wake = 1 AND state = 'active')
+        OR (
+          on_output IN ('always', 'on-change')
+          AND (
+            run_state = 'running'
+            OR (run_state = 'idle' AND state = 'active' AND (expires_at IS NULL OR expires_at > ?))
+          )
+        )`).all(nodeId, new Date().toISOString());
+    for (const row of rows) {
+        if (row['anchor_node'] === nodeId && Number(row['cancel_on_wake']) !== 0)
+            return true;
+        const sink = parseCronSink(row['sink']);
+        if (sink?.kind === 'node' && sink.node === nodeId)
+            return true;
+    }
+    return false;
+}
+/** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
+ *  A real wake consumes the wait at its delivery boundary or, as a dormant
+ *  fallback, in reviveNode; recovery replacement and a viewer attach are not
+ *  wakes and leave the deadline armed. Terminal
+ *  lifecycle transitions also clear the wait. Standing declarative crons are
+ *  untouched. Kills an in-flight run process group first (the cancelCron
+ *  discipline), under one canvas write boundary. Returns the removed crons. A wake must
+ *  go through `consumeDeadlineOnWake` (feed/messages.ts), which also tells the
+ *  node; ending a node calls this directly because nobody is left to tell. */
+export async function cancelCronsOnWake(anchor_node) {
+    return await withCanvasWrite(async (db) => {
+        const rows = (await db.prepare('SELECT * FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1')
+            .all(anchor_node)).map(cronFrom);
+        for (const c of rows) {
+            if (c.run_state === 'running')
+                killLeasedCronRun(c);
+            await db.prepare('DELETE FROM crons WHERE cron_id = ?').run(c.cron_id);
+        }
+        return rows;
+    });
+}
+/** UPDATE the next fire time — recurrence advancement. The daemon settles a
+ *  recurring row to its next slot BEFORE enacting the run (crash-safe). */
+export async function advanceCron(cron_id, nextFireIso) {
+    await (await openDb()).prepare('UPDATE crons SET fire_at = ?, updated = ? WHERE cron_id = ?')
+        .run(nextFireIso, new Date().toISOString(), cron_id);
+}
+// Daemon run-executor primitives (src/daemon/cron-run.ts)
+/** The daemon's per-tick due query: active, idle, fire_at arrived, in
+ *  deterministic order. The idle-only filter IS the default `overlap='skip'`
+ *  behavior — a row whose previous run is still leased is simply not due.
+ *  Returns exactly ONE row per cron regardless of missed slots — coalescing
+ *  is structural (fire_at holds a single next occurrence). */
+export async function dueClockCrons(nowIso) {
+    return (await (await openDb()).prepare(`SELECT * FROM crons
+         WHERE state = 'active' AND run_state = 'idle' AND fire_at <= ?
+         ORDER BY fire_at, created, cron_id`)
+        .all(nowIso)).map(cronFrom).filter((cron) => !isProfilePaused(cron.profile));
+}
+/** Atomically acquire the idle run lease: flips `run_state` to 'running' and
+ *  records lease/pid metadata, but ONLY if the row is still idle (the
+ *  `WHERE run_state = 'idle'` guard is the atomicity). Returns whether THIS
+ *  call acquired it.
+ *
+ *  The pid is recorded WITH its launch-time identity fingerprint, captured here
+ *  from the just-spawned child: that fingerprint is what later authorizes any
+ *  signal against this pid (`killLeasedCronRun`). A failed capture stores NULL,
+ *  which costs the row its kill rights rather than licensing a blind kill.
+ *
+ *  `outOfBand` stamps the lease as a `cron run` (manual verification) so the
+ *  overlap pass leaves it alone — see `dueOverlapCrons`. */
+export async function acquireCronRunLease(cron_id, leaseOwner, startedAtIso, outOfBand, executionId = null) {
+    const res = await (await openDb()).prepare(`UPDATE crons
+       SET run_state = 'running', run_started_at = ?, run_pid = NULL, run_pid_identity = NULL,
+           run_lease_owner = ?, run_out_of_band = ?, run_execution_id = ?, updated = ?
+       WHERE cron_id = ? AND run_state = 'idle'`)
+        .run(startedAtIso, leaseOwner, outOfBand ? 1 : 0, executionId, new Date().toISOString(), cron_id);
+    return Number(res.changes) > 0;
+}
+/** Attach the launcher's pid only to the run that claimed this lease. */
+export async function attachCronRunPid(cron_id, leaseOwner, startedAtIso, pid) {
+    const identity = capturePidIdentities([pid])?.get(pid) ?? null;
+    const res = await (await openDb()).prepare(`UPDATE crons SET run_pid = ?, run_pid_identity = ?, updated = ?
+     WHERE cron_id = ? AND run_state = 'running' AND run_lease_owner = ?
+       AND run_started_at = ? AND run_pid IS NULL`).run(pid, identity, new Date().toISOString(), cron_id, leaseOwner, startedAtIso);
+    return Number(res.changes) > 0;
+}
+/** Release the run lease back to idle (run settled, or stale-lease recovery
+ *  for a dead pid) — only while the row still holds run `runId`, so a settlement of
+ *  an old run cannot clear a newer run's lease. Applies the settlement's `held` disposition in the same
+ *  statement. */
+export async function releaseCronRunLease(cron_id, runId, held) {
+    let heldSql = '';
+    const heldParams = [];
+    if (held !== undefined) {
+        if (held.kind === 'clear') {
+            heldSql = ', held = 0';
+        }
+        else if (held.kind === 'park') {
+            heldSql = held.fireAt !== undefined ? ', held = 1, fire_at = ?' : ', held = 1';
+            if (held.fireAt !== undefined)
+                heldParams.push(held.fireAt);
+        }
+        else {
+            heldSql = ', held = 0, fire_at = ?';
+            heldParams.push(held.nowIso);
+        }
+    }
+    await (await openDb())
+        .prepareUncached(`UPDATE crons
+       SET run_state = 'idle', run_started_at = NULL, run_pid = NULL, run_pid_identity = NULL,
+           run_lease_owner = NULL, run_out_of_band = 0, run_execution_id = NULL, updated = ?${heldSql}
+       WHERE cron_id = ? AND run_execution_id = ?`)
+        .run(new Date().toISOString(), ...heldParams, cron_id, runId);
+}
+/** Persist a run identity on a running row that has none, but only while it is still the same run (same start and lease owner).
+ *  Recovery calls this under its claim so every later write and release names one stored run. Returns whether it was stored. */
+export async function adoptCronRunId(c, runId) {
+    const res = await (await openDb()).prepare(`UPDATE crons SET run_execution_id = ?, updated = ?
+     WHERE cron_id = ? AND run_state = 'running' AND run_execution_id IS NULL
+       AND run_started_at IS NOT DISTINCT FROM ? AND run_lease_owner IS NOT DISTINCT FROM ?`).run(runId, new Date().toISOString(), c.cron_id, c.run_started_at, c.run_lease_owner);
+    return Number(res.changes) > 0;
+}
+/** The daemon-level eligibility poke (`POST /v1/crons/poke`): "something
+ *  changed; re-check now". One write boundary, two statements:
+ *    1. stamp `last_poke_at` on EVERY row — this is what reaches a gate check
+ *       in flight right now, which statement 2 deliberately skips: its exit-75
+ *       settlement sees the stamp and re-dues itself (the F2 branch in
+ *       cron-run.ts);
+ *    2. re-due every held active IDLE row now (fire_at=now, held=0). A leased
+ *       row is excluded: its running gate check settles against the stamp —
+ *       75 re-dues, and success means the gate resolved and the occurrence
+ *       fired, poke satisfied. Unparking mid-run would overwrite the row's
+ *       pre-advanced backstop slot with `now`, so a PASSING gate would fire a
+ *       second time on the next tick.
+ *  Paused rows are not unparked — pause is user-owned and freezes everything;
+ *  a paused held row keeps its state and unparks via a later poke/backstop
+ *  after resume (it still receives the stamp, harmlessly). Returns the
+ *  unparked count. Idempotent and free when nothing is held. */
+export async function pokeHeldCrons(nowIso, grantee = null) {
+    return await withCanvasWrite(async (db) => {
+        const own = grantee === null ? '' : ' AND grantee = ?';
+        const ownArgs = grantee === null ? [] : [grantee];
+        await db.prepareUncached(`UPDATE crons SET last_poke_at = ? WHERE 1 = 1${own}`).run(nowIso, ...ownArgs);
+        const res = await db
+            .prepareUncached(`UPDATE crons SET fire_at = ?, held = 0, updated = ? WHERE held = 1 AND state = 'active' AND run_state = 'idle'${own}`)
+            .run(nowIso, nowIso, ...ownArgs);
+        return Number(res.changes);
+    });
+}
+/** Recurring crons whose NEXT fire has arrived while their previous run is
+ *  still leased — the overlap-policy pass. One-shots never appear here (a
+ *  one-shot has exactly one fire, already consumed by its running lease).
+ *
+ *  An OUT-OF-BAND lease (`cron run`) is excluded: overlap policy arbitrates
+ *  between a SCHEDULED fire and the scheduled run already in flight. A manual
+ *  verification is neither, so letting it participate would either advance
+ *  `fire_at` past a genuine occurrence (`skip`) or SIGTERM the invoker's own
+ *  run (`replace`). Such a row simply is not due for overlap; the real
+ *  occurrence stays past-due and fires the moment the manual lease releases. */
+export async function dueOverlapCrons(nowIso) {
+    return (await (await openDb()).prepare(`SELECT * FROM crons
+         WHERE state = 'active' AND run_state = 'running' AND run_out_of_band = 0
+           AND recur IS NOT NULL AND fire_at <= ?
+         ORDER BY fire_at, created, cron_id`)
+        .all(nowIso)).map(cronFrom);
+}
+/** Crons whose clock bound (`expires_at`) has passed — the daemon deletes
+ *  these each tick. Idle rows only: an expired row whose run is still in
+ *  flight is picked up on a later tick, after the run settles. */
+export async function expiredIdleCrons(nowIso) {
+    return (await (await openDb()).prepare(`SELECT * FROM crons
+         WHERE expires_at IS NOT NULL AND expires_at <= ? AND run_state = 'idle'
+         ORDER BY expires_at`)
+        .all(nowIso)).map(cronFrom);
+}
+/** The run-log ring for one cron, most recent first. */
+export async function listCronRuns(cron_id) {
+    return (await (await openDb()).prepare('SELECT * FROM cron_runs WHERE cron_id = ? ORDER BY started DESC, run_id DESC')
+        .all(cron_id)).map((r) => ({
+        run_id: r['run_id'],
+        cron_id: r['cron_id'],
+        started: r['started'],
+        finished: r['finished'],
+        duration_ms: Number(r['duration_ms']),
+        exit_code: r['exit_code'] ?? null,
+        stdout_head: r['stdout_head'] ?? null,
+        stderr_head: r['stderr_head'] ?? null,
+        delivered: r['delivered'] ?? null,
+    }));
+}
+/** Every cron currently marked 'running' — the daemon's stale-lease recovery
+ *  scan checks each recorded `run_pid` for liveness. */
+export async function runningCrons() {
+    return (await (await openDb()).prepare("SELECT * FROM crons WHERE run_state = 'running'").all()).map(cronFrom);
+}
+/** INSERT one settled run record, then prune that cron's history down to the
+ *  most recent CRON_RUN_RING rows — one canvas write boundary, so the ring
+ *  bound holds atomically with the insert. Returns whether the record was
+ *  written: a cron canceled while its run was in flight is already gone (and
+ *  its history cascaded), so a settling run no-ops with `false` instead of
+ *  violating the FK. */
+export async function recordCronRunLocked(db, run) {
+    if (await db.prepare('SELECT 1 FROM crons WHERE cron_id = ?').get(run.cron_id) === undefined) {
+        return false;
+    }
+    await db.prepare(`INSERT INTO cron_runs (
+       run_id, cron_id, started, finished, duration_ms, exit_code,
+       stdout_head, stderr_head, delivered
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.run_id, run.cron_id, run.started, run.finished, run.duration_ms, run.exit_code, run.stdout_head, run.stderr_head, run.delivered);
+    await db.prepare(`DELETE FROM cron_runs
+     WHERE cron_id = ? AND run_id NOT IN (
+       SELECT run_id FROM cron_runs WHERE cron_id = ?
+       ORDER BY started DESC, run_id DESC LIMIT ?
+     )`).run(run.cron_id, run.cron_id, CRON_RUN_RING);
+    return true;
+}
+export async function recordCronRun(run) {
+    return await withCanvasWrite(async (db) => await recordCronRunLocked(db, run));
+}

package/dist/core/canvas/daemon-actions.d.ts

@@ -0,0 +1,42 @@
+import { type DeliverySettlement } from './deliveries.js';
+import { type DeliveryFailure, type DeliverySettlement as ProcessDeliverySettlement } from './delivery-contract.js';
+export type DaemonActionState = 'pending' | 'handed_off' | 'acknowledged' | 'permanent_failed';
+export interface DaemonActionAdapter {
+    adapter: 'subprocess' | 'cron_spawn' | 'cron_human';
+    [key: string]: unknown;
+}
+export interface DaemonActionInput {
+    adapter: DaemonActionAdapter;
+    bodyJson: unknown;
+    /** Cron run id, or `human-action:<inbox ticket id>`. A duplicate returns the original action. */
+    idempotencyKey: string;
+}
+export interface DaemonActionRecord {
+    actionId: string;
+    adapter: DaemonActionAdapter;
+    body: unknown | null;
+    idempotencyKey: string;
+    state: DaemonActionState;
+    attempts: number;
+    nextAttemptAt: number | null;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acknowledgedAt: number | null;
+    failedAt: number | null;
+    lastFailure: DeliveryFailure | null;
+    canceledAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Insert one frozen daemon action, due now. A duplicate idempotency key returns the original action id. */
+export declare function enqueueDaemonAction(input: DaemonActionInput): Promise<string>;
+export declare function readDaemonAction(idempotencyKey: string): Promise<DaemonActionRecord | null>;
+export declare function readDaemonActionById(actionId: string): Promise<DaemonActionRecord | null>;
+export declare function dueDaemonActions(now: number): Promise<DaemonActionRecord[]>;
+export declare function claimDaemonAction(actionId: string, now: number, claimOwner: string): Promise<DaemonActionRecord | null>;
+/** The state/attempt/owner fence, identical in shape to `settleDelivery`. */
+export declare function settleDaemonAction(actionId: string, attempts: number, claimOwner: string, settlement: DeliverySettlement | ProcessDeliverySettlement, now?: number): Promise<boolean>;
+/** Deliberate operator retry of a daemon action that failed for good: pending, due now, fresh attempt budget. */
+export declare function retryFailedDaemonAction(actionId: string, now?: number): Promise<boolean>;
+/** Daemon startup: an action a previous daemon handed off is due again now. */
+export declare function resetHandedOffDaemonActions(now: number): Promise<number>;