@north-light/crouter 0.3.154

package/dist/core/canvas/crons.d.ts

@@ -0,0 +1,222 @@
+export type CronScope = 'profile' | 'global';
+export type CronOverlap = 'skip' | 'queue' | 'replace';
+export type CronOnOutput = 'silent' | 'on-failure' | 'always' | 'on-change';
+export type CronState = 'active' | 'paused';
+export type CronRunState = 'idle' | 'running';
+/** A hydrated `crons` row. */
+export interface Cron {
+    cron_id: string;
+    name: string;
+    created_by: string | null;
+    command: string;
+    fire_at: string;
+    recur: string | null;
+    tz: string | null;
+    expires_at: string | null;
+    anchor_node: string | null;
+    cancel_on_wake: boolean;
+    cwd: string;
+    env_json: string | null;
+    profile: string | null;
+    scope: CronScope;
+    run_timeout_s: number;
+    overlap: CronOverlap;
+    on_output: CronOnOutput;
+    /** Sink JSON: `{node}` | `{spawn,kind,...}` | `{human}` (stored raw). */
+    sink: string;
+    tier: string;
+    last_output_hash: string | null;
+    state: CronState;
+    run_state: CronRunState;
+    run_pid: number | null;
+    /** `capturePidIdentities` fingerprint of `run_pid`, taken at lease
+     *  acquisition. NULL on a pre-v23 row or when the capture failed — either
+     *  way `killLeasedCronRun` refuses to signal. */
+    run_pid_identity: string | null;
+    run_started_at: string | null;
+    run_lease_owner: string | null;
+    /** True when the in-flight lease belongs to an OUT-OF-BAND run (`cron run`)
+     *  rather than a scheduled fire. The overlap pass excludes such rows: a
+     *  manual verification must neither eat a real occurrence (`skip`) nor be
+     *  killed by one (`replace`). */
+    run_out_of_band: boolean;
+    created: string;
+    updated: string;
+}
+/** The pinned arm-time spec — every stored column except the runtime lease
+ *  fields, which always start idle. */
+export interface ArmCronSpec {
+    cron_id: string;
+    name: string;
+    created_by: string | null;
+    command: string;
+    fire_at: string;
+    recur: string | null;
+    tz: string | null;
+    expires_at: string | null;
+    anchor_node: string | null;
+    cancel_on_wake: boolean;
+    cwd: string;
+    env_json: string | null;
+    profile: string | null;
+    scope: CronScope;
+    run_timeout_s: number;
+    overlap: CronOverlap;
+    on_output: CronOnOutput;
+    sink: string;
+    tier: string;
+}
+/** One settled `cron_runs` record, written after the subprocess closes. */
+export interface CronRunRecord {
+    run_id: string;
+    cron_id: string;
+    started: string;
+    finished: string;
+    duration_ms: number;
+    /** -1 = timeout kill (schema contract); otherwise the observed exit code,
+     *  null when no exit was observed (process error). */
+    exit_code: number | null;
+    stdout_head: string | null;
+    stderr_head: string | null;
+    delivered: string | null;
+}
+/** Ring bound for `cron_runs`: recordCronRun prunes each cron's history to
+ *  its most recent this-many rows. */
+export declare const CRON_RUN_RING = 20;
+/** The ONLY sanctioned way to signal a cron run's process group from a stored
+ *  row. Re-captures the CURRENT identity of `run_pid` and signals only when it
+ *  MATCHES the fingerprint recorded at lease acquisition. Returns whether the
+ *  signal was sent.
+ *
+ *  FAIL-CLOSED, unlike the rest of this repo's pid handling. Elsewhere the
+ *  baseline was captured by the same daemon life that is now signaling, so an
+ *  absent baseline or a failed `ps` probe means "no evidence of reuse" and
+ *  failing open to the signal is right. A cron lease outlives its daemon: after
+ *  a SIGKILL or a host reboot, `run_pid` is a number from a dead kernel's pid
+ *  space that the OS has very likely handed to an unrelated process, and
+ *  `isPidAlive` cheerfully confirms that stranger. So here the ONLY thing that
+ *  authorizes a kill is positive proof of sameness — no identity (pre-v23 row,
+ *  capture failed), no `ps` table (probe failed), no row for the pid (process
+ *  gone), or a mismatch (reused) all mean: do not signal. The caller settles the
+ *  lease instead; the worst case is a leaked runaway process, versus SIGTERMing
+ *  a stranger's process group. */
+export declare function killLeasedCronRun(c: Cron, signal?: NodeJS.Signals): boolean;
+/** 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 declare function verifyLeasedCronRun(c: Cron): boolean;
+/** 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 canvas write boundary so
+ *  two concurrent arms cannot both pass. 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 declare function armCron(spec: ArmCronSpec): {
+    cron_id: string;
+    replaced: string[];
+};
+/** SELECT one cron by id. */
+export declare function getCron(cron_id: string): Cron | null;
+/** 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 declare function listCrons(scope: {
+    profile: string;
+} | {
+    global: true;
+} | {
+    all: true;
+}): Cron[];
+/** 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, under one canvas write boundary (the reapThenDelete precedent):
+ *  lease acquisition linearizes either 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 declare function cancelCron(cron_id: string): boolean;
+/** 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 declare function consumeCron(cron_id: string): boolean;
+/** 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 declare function setCronState(cron_id: string, state: CronState): boolean;
+/** 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 declare function setCronLastOutputHash(cron_id: string, hash: string): void;
+/** True when this node has a pending cancel-on-wake cron. The stop guard uses
+ *  this focused deadline check to distinguish legitimate clock dormancy from a
+ *  terminal node that stopped without finishing. */
+export declare function hasPendingCancelOnWakeCron(anchor_node: string): boolean;
+/** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
+ *  Two seams call it: reviveNode on every revive-for-any-reason (the wake won
+ *  the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
+ *  with the node, so its deadline must not fire against a finalized or closed
+ *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
+ *  Kills any in-flight
+ *  run process group first (the cancelCron discipline), under one canvas write
+ *  boundary. Returns the removed cron ids. */
+export declare function cancelCronsOnWake(anchor_node: string): string[];
+/** UPDATE the next fire time — recurrence advancement. The daemon settles a
+ *  recurring row to its next slot BEFORE enacting the run (crash-safe). */
+export declare function advanceCron(cron_id: string, nextFireIso: string): void;
+/** 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 declare function dueClockCrons(nowIso: string): Cron[];
+/** 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 declare function acquireCronRunLease(cron_id: string, leaseOwner: string, pid: number, startedAtIso: string, outOfBand: boolean): boolean;
+/** Release the run lease back to idle (run settled, or stale-lease recovery
+ *  for a dead pid). */
+export declare function releaseCronRunLease(cron_id: string): void;
+/** 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 declare function dueOverlapCrons(nowIso: string): Cron[];
+/** 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 declare function expiredIdleCrons(nowIso: string): Cron[];
+/** The run-log ring for one cron, most recent first. */
+export declare function listCronRuns(cron_id: string): CronRunRecord[];
+/** Every cron currently marked 'running' — the daemon's stale-lease recovery
+ *  scan checks each recorded `run_pid` for liveness. */
+export declare function runningCrons(): Cron[];
+/** 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 declare function recordCronRun(run: CronRunRecord): boolean;

package/dist/core/canvas/crons.js

@@ -0,0 +1,367 @@
+// 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 { openDb, withCanvasWrite } from './db.js';
+import { capturePidIdentities, identitiesMatch, killProcessGroup } from './pid.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 cronFrom(r) {
+    return {
+        cron_id: r['cron_id'],
+        name: r['name'],
+        created_by: r['created_by'] ?? null,
+        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,
+        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'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Signal safety
+// ---------------------------------------------------------------------------
+/** The ONLY sanctioned way to signal a cron run's process group from a stored
+ *  row. Re-captures the CURRENT identity of `run_pid` and signals only when it
+ *  MATCHES the fingerprint recorded at lease acquisition. Returns whether the
+ *  signal was sent.
+ *
+ *  FAIL-CLOSED, unlike the rest of this repo's pid handling. Elsewhere the
+ *  baseline was captured by the same daemon life that is now signaling, so an
+ *  absent baseline or a failed `ps` probe means "no evidence of reuse" and
+ *  failing open to the signal is right. A cron lease outlives its daemon: after
+ *  a SIGKILL or a host reboot, `run_pid` is a number from a dead kernel's pid
+ *  space that the OS has very likely handed to an unrelated process, and
+ *  `isPidAlive` cheerfully confirms that stranger. So here the ONLY thing that
+ *  authorizes a kill is positive proof of sameness — no identity (pre-v23 row,
+ *  capture failed), no `ps` table (probe failed), no row for the pid (process
+ *  gone), or a mismatch (reused) all mean: do not signal. The caller settles the
+ *  lease instead; the worst case is a leaked runaway process, versus SIGTERMing
+ *  a stranger's process group. */
+export function killLeasedCronRun(c, signal = 'SIGTERM') {
+    if (!verifyLeasedCronRun(c))
+        return false;
+    killProcessGroup(c.run_pid, signal);
+    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 canvas write boundary so
+ *  two concurrent arms cannot both pass. 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 function armCron(spec) {
+    return withCanvasWrite((db) => {
+        const replaced = [];
+        if (spec.cancel_on_wake && spec.anchor_node !== null) {
+            const rows = 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);
+                db.prepare('DELETE FROM crons WHERE cron_id = ?').run(c.cron_id);
+                replaced.push(c.cron_id);
+            }
+        }
+        insertCron(db, spec);
+        return { cron_id: spec.cron_id, replaced };
+    });
+}
+function insertCron(db, spec) {
+    const now = new Date().toISOString();
+    db
+        .prepare(`INSERT INTO crons (
+         cron_id, name, created_by, 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
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.cron_id, spec.name, spec.created_by, 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);
+}
+/** SELECT one cron by id. */
+export function getCron(cron_id) {
+    const row = 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 function listCrons(scope) {
+    const db = openDb();
+    let rows;
+    if ('profile' in scope) {
+        rows = db
+            .prepare("SELECT * FROM crons WHERE scope = 'profile' AND profile = ? ORDER BY fire_at")
+            .all(scope.profile);
+    }
+    else if ('global' in scope) {
+        rows = db
+            .prepare("SELECT * FROM crons WHERE scope = 'global' ORDER BY fire_at")
+            .all();
+    }
+    else {
+        rows = 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, under one canvas write boundary (the reapThenDelete precedent):
+ *  lease acquisition linearizes either 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 function cancelCron(cron_id) {
+    return withCanvasWrite((db) => {
+        const row = 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')
+            killLeasedCronRun(cron);
+        db.prepare('DELETE FROM crons WHERE cron_id = ?').run(cron_id);
+        return true;
+    });
+}
+/** 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 function consumeCron(cron_id) {
+    return 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 function setCronState(cron_id, state) {
+    return (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 function setCronLastOutputHash(cron_id, hash) {
+    openDb()
+        .prepare('UPDATE crons SET last_output_hash = ?, updated = ? WHERE cron_id = ?')
+        .run(hash, new Date().toISOString(), cron_id);
+}
+/** True when this node has a pending cancel-on-wake cron. The stop guard uses
+ *  this focused deadline check to distinguish legitimate clock dormancy from a
+ *  terminal node that stopped without finishing. */
+export function hasPendingCancelOnWakeCron(anchor_node) {
+    return (openDb()
+        .prepare("SELECT 1 FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1 AND state = 'active' LIMIT 1")
+        .get(anchor_node) !== undefined);
+}
+/** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
+ *  Two seams call it: reviveNode on every revive-for-any-reason (the wake won
+ *  the race), and the `finish`/`cancel` lifecycle transitions (the wait ended
+ *  with the node, so its deadline must not fire against a finalized or closed
+ *  row). Standing declarative crons are untouched — only cancel-on-wake rows.
+ *  Kills any in-flight
+ *  run process group first (the cancelCron discipline), under one canvas write
+ *  boundary. Returns the removed cron ids. */
+export function cancelCronsOnWake(anchor_node) {
+    return withCanvasWrite((db) => {
+        const rows = 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);
+            db.prepare('DELETE FROM crons WHERE cron_id = ?').run(c.cron_id);
+        }
+        return rows.map((c) => c.cron_id);
+    });
+}
+/** UPDATE the next fire time — recurrence advancement. The daemon settles a
+ *  recurring row to its next slot BEFORE enacting the run (crash-safe). */
+export function advanceCron(cron_id, nextFireIso) {
+    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 function dueClockCrons(nowIso) {
+    return 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);
+}
+/** 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 function acquireCronRunLease(cron_id, leaseOwner, pid, startedAtIso, outOfBand) {
+    const identity = capturePidIdentities([pid])?.get(pid) ?? null;
+    const res = openDb()
+        .prepare(`UPDATE crons
+       SET run_state = 'running', run_started_at = ?, run_pid = ?, run_pid_identity = ?,
+           run_lease_owner = ?, run_out_of_band = ?, updated = ?
+       WHERE cron_id = ? AND run_state = 'idle'`)
+        .run(startedAtIso, pid, identity, leaseOwner, outOfBand ? 1 : 0, new Date().toISOString(), cron_id);
+    return Number(res.changes) > 0;
+}
+/** Release the run lease back to idle (run settled, or stale-lease recovery
+ *  for a dead pid). */
+export function releaseCronRunLease(cron_id) {
+    openDb()
+        .prepare(`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, updated = ?
+       WHERE cron_id = ?`)
+        .run(new Date().toISOString(), cron_id);
+}
+/** 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 function dueOverlapCrons(nowIso) {
+    return 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 function expiredIdleCrons(nowIso) {
+    return 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 function listCronRuns(cron_id) {
+    return 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 function runningCrons() {
+    return 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 function recordCronRun(run) {
+    return withCanvasWrite((db) => {
+        if (db.prepare('SELECT 1 FROM crons WHERE cron_id = ?').get(run.cron_id) === undefined) {
+            return false;
+        }
+        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);
+        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;
+    });
+}

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

@@ -0,0 +1,67 @@
+import { type RecordedPidLiveness } from './pid.js';
+/** The single `canvas_meta` key this module exclusively owns. No other module
+ *  may read or write this key. */
+export declare const DAEMON_OWNER_META_KEY = "daemon_owner";
+/** The exact shape persisted as `canvas_meta.value` for `DAEMON_OWNER_META_KEY`.
+ *  `token` is an unpredictable per-invocation string minted by the caller
+ *  (`crtrd.ts`) — this module never generates, inspects, or compares it beyond
+ *  exact-string equality of the whole serialized claim. */
+export interface DaemonOwnerClaim {
+    readonly pid: number;
+    readonly pid_identity: string;
+    readonly token: string;
+}
+/** Every terminal, non-retriable way `claimDaemonOwnership` can lose. A loss
+ *  never deletes or otherwise mutates the incumbent row — only a positively
+ *  DEAD incumbent is ever CAS-replaced. */
+export type DaemonOwnerClaimLossReason = 
+/** This invocation's OWN pid identity couldn't be captured before any write
+ *  was attempted — no identity-less claim is ever installed. */
+'own_identity_indeterminate'
+/** The incumbent row's `value` failed validated parsing. */
+ | 'incumbent_malformed'
+/** The incumbent's recorded pid is confirmed alive under its recorded
+ *  identity. */
+ | 'incumbent_alive'
+/** The incumbent's liveness could not be confirmed either way (a failed
+ *  `ps` probe) — treated the same as alive: never reclaimed on mere
+ *  uncertainty. */
+ | 'incumbent_indeterminate';
+export type DaemonOwnerClaimResult = {
+    readonly claimed: true;
+    readonly claim: DaemonOwnerClaim;
+} | {
+    readonly claimed: false;
+    readonly reason: DaemonOwnerClaimLossReason;
+    /** The incumbent's recorded pid, present whenever a parsed incumbent
+     *  claim was actually read (absent for `own_identity_indeterminate`). */
+    readonly incumbentPid?: number;
+    /** The liveness verdict against the incumbent's recorded identity,
+     *  present for `incumbent_alive`/`incumbent_indeterminate`. */
+    readonly verdict?: RecordedPidLiveness;
+};
+/** Attempt to claim exclusive daemon ownership for this process, using
+ *  `token` as the unpredictable per-invocation discriminator the caller
+ *  generated. Synchronous — every underlying operation (identity capture,
+ *  liveness probe, sqlite) is synchronous, and this must complete before the
+ *  caller does any other fallible startup work.
+ *
+ *  Only a `dead` incumbent is ever reclaimed, via a snapshot-conditioned
+ *  compare-and-set; `alive` and `indeterminate` incumbents cause an immediate
+ *  loss with no row mutation at all. A malformed incumbent also loses without
+ *  deletion or probing — this primitive never repairs or clears a bad row; a
+ *  future winning claimant's CAS naturally supersedes it once its OWN pid is
+ *  confirmed dead... except a malformed row can never be proven dead (no pid
+ *  to probe), so a malformed incumbent can only ever be lost against, never
+ *  reclaimed, by this primitive alone. That is intentional: this module never
+ *  guesses at repair. */
+export declare function claimDaemonOwnership(token: string): DaemonOwnerClaimResult;
+/** Release exclusive daemon ownership, iff the persisted row still equals
+ *  `claim` EXACTLY (key present and value byte-identical to this invocation's
+ *  own winning claim). This is a conditional delete, not an unconditional one:
+ *  a caller must never release a row a successor has since won (e.g. after
+ *  this invocation's claim was already reclaimed via the dead-incumbent CAS
+ *  path while this process lingered mid-teardown). */
+export declare function releaseDaemonOwnership(claim: DaemonOwnerClaim): {
+    readonly released: boolean;
+};