@north-light/cli 0.0.0 → 0.3.414

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

@@ -0,0 +1,298 @@
+import { openDb } from './db.js';
+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';
+/** The decoded delivery target of a stored cron sink. */
+export type ParsedCronSink = {
+    kind: 'node';
+    node: string;
+} | {
+    kind: 'spawn';
+    spawn: string;
+} | {
+    kind: 'human';
+} | null;
+/** A hydrated `crons` row. */
+export interface Cron {
+    cron_id: string;
+    name: string;
+    created_by: string | null;
+    grantee: string;
+    /** Frozen from the creating node; never recomputed from a later node state. */
+    isolated: boolean;
+    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;
+    /** True while the row is PARKED by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A poke re-dues the row now; otherwise a
+     *  recurring row re-checks at its already-advanced natural slot and a held
+     *  one-shot waits at its backstop `fire_at` (expires_at, else far future).
+     *  Deliberately NOT part of the due query — a held row is non-due by
+     *  `fire_at`, not by a new predicate. */
+    held: boolean;
+    /** UTC ISO of the last `POST /v1/crons/poke` receipt, written to EVERY row
+     *  on poke. Settlement compares a 75-exiting run's start against it: a poke
+     *  that arrived mid-run re-dues instead of parking (the in-flight gate check
+     *  could not have seen the eligibility change). */
+    last_poke_at: 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;
+    grantee?: string;
+    isolated?: boolean;
+    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;
+/** Decode the stored cron sink JSON. A malformed or unrecognised value has no sink. */
+export declare function parseCronSink(sinkJson: string): ParsedCronSink;
+/** Render a stored cron sink as the arm-time CLI spec, or null when it has no destination. */
+export declare function cronSinkDisplay(sinkJson: string): string | null;
+/** 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 declare function stopLeasedCronRun(c: Cron, signal?: 'SIGTERM' | 'SIGKILL'): Promise<boolean>;
+/** 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 declare function killLeasedCronRun(c: Cron, signal?: 'SIGTERM' | 'SIGKILL'): 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 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 declare function cancelCron(cron_id: string, options?: {
+    preserveRunningProcess?: boolean;
+}): boolean;
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export declare function cronIdsForProfileDeletion(profileId: string, anchorNodeIds: readonly string[]): string[];
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export declare function deleteCronsForProfile(profileId: string, anchorNodeIds: readonly string[]): string[];
+/** Cron ids whose snapshotted profile will be detached. */
+export declare function cronIdsForProfileDetach(profileId: string): string[];
+/** Preserve matching crons while removing their deleted profile dependency. */
+export declare function globalizeCronsForProfile(profileId: string): string[];
+/** 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 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 declare function hasPendingCronWake(nodeId: string): boolean;
+/** 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 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, startedAtIso: string, outOfBand: boolean): boolean;
+/** Attach the launcher's pid only to the run that claimed this lease. */
+export declare function attachCronRunPid(cron_id: string, leaseOwner: string, startedAtIso: string, pid: number): boolean;
+/** What a settling run does with the row's `held` state, applied in the SAME
+ *  UPDATE that releases the lease — one write boundary, so no tick can observe
+ *  `run_state='idle'` with the held transition not yet applied.
+ *    clear — an ordinary scheduled disposition settlement (success, real
+ *            failure): the gate resolved, so a parked row unparks.
+ *    park  — the exit-75 owed-gate disposition: held=1. A one-shot also moves
+ *            `fire_at` to its backstop (`fireAt`); a recurring row keeps its
+ *            pre-run-advanced natural slot.
+ *    redue — a poke arrived while this gate check was in flight (start <
+ *            last_poke_at): fire_at=now, held=0 — re-check next tick.
+ *  Omitted entirely = leave `held` untouched (a replaced run, an out-of-band
+ *  run, an unobserved crashed run — the gate is still unresolved). */
+export type HeldSettle = {
+    kind: 'clear';
+} | {
+    kind: 'park';
+    fireAt?: string;
+} | {
+    kind: 'redue';
+    nowIso: string;
+};
+/** Release the run lease back to idle (run settled, or stale-lease recovery
+ *  for a dead pid), applying the settlement's `held` disposition in the same
+ *  statement. */
+export declare function releaseCronRunLease(cron_id: string, held?: HeldSettle): void;
+/** 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 declare function pokeHeldCrons(nowIso: string, grantee?: string | null): number;
+/** 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 recordCronRunLocked(db: ReturnType<typeof openDb>, run: CronRunRecord): boolean;
+export declare function recordCronRun(run: CronRunRecord): boolean;

package/dist/core/canvas/crons.js

@@ -0,0 +1,36 @@
+var R=Object.defineProperty;var o=(n,r)=>R(n,"name",{value:r,configurable:!0});import{prepared as i}from"../sqlite-statements.js";import{openDb as u,withCanvasWrite as _}from"./db.js";import{capturePidIdentities as E,identitiesMatch as m,killProcessGroup as D}from"./pid.js";import{isProfilePaused as S}from"../profiles/manifest.js";import{stopAppProcess as h}from"../spaces/process.js";import{emitEvent as N}from"../events/emit.js";const O=20;function s(n){return{cron_id:n.cron_id,name:n.name,created_by:n.created_by??null,grantee:n.grantee,isolated:Number(n.isolated)!==0,command:n.command,fire_at:n.fire_at,recur:n.recur??null,tz:n.tz??null,expires_at:n.expires_at??null,anchor_node:n.anchor_node??null,cancel_on_wake:Number(n.cancel_on_wake)!==0,cwd:n.cwd,env_json:n.env_json??null,profile:n.profile??null,scope:n.scope,run_timeout_s:Number(n.run_timeout_s),overlap:n.overlap,on_output:n.on_output,sink:n.sink,tier:n.tier,last_output_hash:n.last_output_hash??null,held:Number(n.held)!==0,last_poke_at:n.last_poke_at??null,state:n.state,run_state:n.run_state,run_pid:n.run_pid??null,run_pid_identity:n.run_pid_identity??null,run_started_at:n.run_started_at??null,run_lease_owner:n.run_lease_owner??null,run_out_of_band:Number(n.run_out_of_band)!==0,created:n.created,updated:n.updated}}o(s,"cronFrom");function p(n){try{const r=JSON.parse(n);if(typeof r.node=="string")return{kind:"node",node:r.node};if(typeof r.spawn=="string")return{kind:"spawn",spawn:r.spawn};if(r.human===!0)return{kind:"human"}}catch{}return null}o(p,"parseCronSink");function F(n){const r=p(n);if(r===null)return null;switch(r.kind){case"node":return`node:${r.node}`;case"spawn":return`spawn:${r.spawn}`;case"human":return"human"}}o(F,"cronSinkDisplay");async function L(n,r="SIGTERM"){if(!l(n))return!1;if(process.platform!=="linux")return D(n.run_pid,r),!0;try{return await h(n.run_pid,r,n.anchor_node??void 0),!0}catch(e){if(!l(n))return!1;throw e}}o(L,"stopLeasedCronRun");function c(n,r="SIGTERM"){return l(n)?(L(n,r).catch(e=>{N({level:"error",event:"cron.run.stop_failed",error:e,fields:{cron_id:n.cron_id,pid:n.run_pid}})}),!0):!1}o(c,"killLeasedCronRun");function l(n){const r=n.run_pid;if(r==null||n.run_pid_identity==null)return!1;const e=E([r]);if(e===null)return!1;const t=e.get(r);return t===void 0?!1:m(t,n.run_pid_identity)}o(l,"verifyLeasedCronRun");function M(n){return _(r=>{const e=[];if(n.cancel_on_wake&&n.anchor_node!==null){const t=i(r,"SELECT * FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1").all(n.anchor_node).map(s);for(const a of t)a.run_state==="running"&&c(a),i(r,"DELETE FROM crons WHERE cron_id = ?").run(a.cron_id),e.push(a.cron_id)}return C(r,n),{cron_id:n.cron_id,replaced:e}})}o(M,"armCron");function C(n,r){const e=new Date().toISOString();i(n,`INSERT INTO crons (
+         cron_id, name, created_by, grantee, 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
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(r.cron_id,r.name,r.created_by,r.grantee??"app:terminal",r.isolated?1:0,r.command,r.fire_at,r.recur,r.tz,r.expires_at,r.anchor_node,r.cancel_on_wake?1:0,r.cwd,r.env_json,r.profile,r.scope,r.run_timeout_s,r.overlap,r.on_output,r.sink,r.tier,e,e)}o(C,"insertCron");function v(n){const r=i(u(),"SELECT * FROM crons WHERE cron_id = ?").get(n);return r===void 0?null:s(r)}o(v,"getCron");function I(n){const r=u();let e;return"profile"in n?e=i(r,"SELECT * FROM crons WHERE scope = 'profile' AND profile = ? ORDER BY fire_at").all(n.profile):"global"in n?e=i(r,"SELECT * FROM crons WHERE scope = 'global' ORDER BY fire_at").all():e=i(r,"SELECT * FROM crons ORDER BY fire_at").all(),e.map(s)}o(I,"listCrons");function U(n,r){return _(e=>{const t=i(e,"SELECT * FROM crons WHERE cron_id = ?").get(n);if(t===void 0)return!1;const a=s(t);return a.run_state==="running"&&r?.preserveRunningProcess!==!0&&c(a),i(e,"DELETE FROM crons WHERE cron_id = ?").run(n),!0})}o(U,"cancelCron");function f(n,r){const e=[...new Set(r)];return e.length===0?{sql:"profile = ?",params:[n]}:{sql:`profile = ? OR anchor_node IN (${e.map(()=>"?").join(",")})`,params:[n,...e]}}o(f,"profileCronWhere");function P(n,r){const e=f(n,r);return u().prepare(`SELECT cron_id FROM crons WHERE ${e.sql} ORDER BY created, cron_id`).all(...e.params).map(({cron_id:t})=>t)}o(P,"cronIdsForProfileDeletion");function y(n,r){return _(e=>{const t=f(n,r),a=e.prepare(`SELECT * FROM crons WHERE ${t.sql} ORDER BY created, cron_id`).all(...t.params).map(s);for(const d of a)d.run_state==="running"&&c(d);return e.prepare(`DELETE FROM crons WHERE ${t.sql}`).run(...t.params),a.map(({cron_id:d})=>d)})}o(y,"deleteCronsForProfile");function b(n){return i(u(),"SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id").all(n).map(({cron_id:r})=>r)}o(b,"cronIdsForProfileDetach");function B(n){return _(r=>{const e=i(r,"SELECT cron_id FROM crons WHERE profile = ? ORDER BY created, cron_id").all(n).map(({cron_id:t})=>t);return e.length>0&&i(r,"UPDATE crons SET profile = NULL, scope = 'global', updated = ? WHERE profile = ?").run(new Date().toISOString(),n),e})}o(B,"globalizeCronsForProfile");function Y(n){return i(u(),"DELETE FROM crons WHERE cron_id = ?").run(n).changes>0}o(Y,"consumeCron");function $(n,r){return i(u(),"UPDATE crons SET state = ?, updated = ? WHERE cron_id = ?").run(r,new Date().toISOString(),n).changes>0}o($,"setCronState");function q(n,r){i(u(),"UPDATE crons SET last_output_hash = ?, updated = ? WHERE cron_id = ?").run(r,new Date().toISOString(),n)}o(q,"setCronLastOutputHash");function j(n){const r=i(u(),`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(n,new Date().toISOString());for(const e of r){if(e.anchor_node===n&&Number(e.cancel_on_wake)!==0)return!0;const t=p(e.sink);if(t?.kind==="node"&&t.node===n)return!0}return!1}o(j,"hasPendingCronWake");function z(n){return _(r=>{const e=i(r,"SELECT * FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1").all(n).map(s);for(const t of e)t.run_state==="running"&&c(t),i(r,"DELETE FROM crons WHERE cron_id = ?").run(t.cron_id);return e.map(t=>t.cron_id)})}o(z,"cancelCronsOnWake");function G(n,r){i(u(),"UPDATE crons SET fire_at = ?, updated = ? WHERE cron_id = ?").run(r,new Date().toISOString(),n)}o(G,"advanceCron");function V(n){return i(u(),`SELECT * FROM crons
+         WHERE state = 'active' AND run_state = 'idle' AND fire_at <= ?
+         ORDER BY fire_at, created, cron_id`).all(n).map(s).filter(r=>!S(r.profile))}o(V,"dueClockCrons");function J(n,r,e,t){const a=i(u(),`UPDATE crons
+       SET run_state = 'running', run_started_at = ?, run_pid = NULL, run_pid_identity = NULL,
+           run_lease_owner = ?, run_out_of_band = ?, updated = ?
+       WHERE cron_id = ? AND run_state = 'idle'`).run(e,r,t?1:0,new Date().toISOString(),n);return Number(a.changes)>0}o(J,"acquireCronRunLease");function K(n,r,e,t){const a=E([t])?.get(t)??null,d=i(u(),`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(t,a,new Date().toISOString(),n,r,e);return Number(d.changes)>0}o(K,"attachCronRunPid");function Q(n,r){let e="";const t=[];r!==void 0&&(r.kind==="clear"?e=", held = 0":r.kind==="park"?(e=r.fireAt!==void 0?", held = 1, fire_at = ?":", held = 1",r.fireAt!==void 0&&t.push(r.fireAt)):(e=", held = 0, fire_at = ?",t.push(r.nowIso))),u().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 = ?${e}
+       WHERE cron_id = ?`).run(new Date().toISOString(),...t,n)}o(Q,"releaseCronRunLease");function X(n,r=null){return _(e=>{const t=r===null?"":" AND grantee = ?",a=r===null?[]:[r];e.prepare(`UPDATE crons SET last_poke_at = ? WHERE 1 = 1${t}`).run(n,...a);const d=e.prepare(`UPDATE crons SET fire_at = ?, held = 0, updated = ? WHERE held = 1 AND state = 'active' AND run_state = 'idle'${t}`).run(n,n,...a);return Number(d.changes)})}o(X,"pokeHeldCrons");function Z(n){return i(u(),`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(n).map(s)}o(Z,"dueOverlapCrons");function nn(n){return i(u(),`SELECT * FROM crons
+         WHERE expires_at IS NOT NULL AND expires_at <= ? AND run_state = 'idle'
+         ORDER BY expires_at`).all(n).map(s)}o(nn,"expiredIdleCrons");function rn(n){return i(u(),"SELECT * FROM cron_runs WHERE cron_id = ? ORDER BY started DESC, run_id DESC").all(n).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}))}o(rn,"listCronRuns");function en(){return i(u(),"SELECT * FROM crons WHERE run_state = 'running'").all().map(s)}o(en,"runningCrons");function w(n,r){return i(n,"SELECT 1 FROM crons WHERE cron_id = ?").get(r.cron_id)===void 0?!1:(i(n,`INSERT INTO cron_runs (
+       run_id, cron_id, started, finished, duration_ms, exit_code,
+       stdout_head, stderr_head, delivered
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(r.run_id,r.cron_id,r.started,r.finished,r.duration_ms,r.exit_code,r.stdout_head,r.stderr_head,r.delivered),i(n,`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(r.cron_id,r.cron_id,O),!0)}o(w,"recordCronRunLocked");function tn(n){return _(r=>w(r,n))}o(tn,"recordCronRun");export{O as CRON_RUN_RING,J as acquireCronRunLease,G as advanceCron,M as armCron,K as attachCronRunPid,U as cancelCron,z as cancelCronsOnWake,Y as consumeCron,P as cronIdsForProfileDeletion,b as cronIdsForProfileDetach,F as cronSinkDisplay,y as deleteCronsForProfile,V as dueClockCrons,Z as dueOverlapCrons,nn as expiredIdleCrons,v as getCron,B as globalizeCronsForProfile,j as hasPendingCronWake,c as killLeasedCronRun,rn as listCronRuns,I as listCrons,p as parseCronSink,X as pokeHeldCrons,tn as recordCronRun,w as recordCronRunLocked,Q as releaseCronRunLease,en as runningCrons,q as setCronLastOutputHash,$ as setCronState,L as stopLeasedCronRun,l as verifyLeasedCronRun};

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

@@ -0,0 +1,45 @@
+import type { DatabaseSync } from 'node:sqlite';
+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;
+}
+/** The table DDL. Shared by the migration that creates it; idempotent. */
+export declare function createDaemonActionsTable(db: DatabaseSync): void;
+/** Insert one frozen daemon action, due now. A duplicate idempotency key returns the original action id. */
+export declare function enqueueDaemonAction(input: DaemonActionInput): string;
+export declare function readDaemonAction(idempotencyKey: string): DaemonActionRecord | null;
+export declare function readDaemonActionById(actionId: string): DaemonActionRecord | null;
+export declare function dueDaemonActions(now: number): DaemonActionRecord[];
+export declare function claimDaemonAction(actionId: string, now: number, claimOwner: string): 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): 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): boolean;
+/** Daemon startup: an action a previous daemon handed off is due again now. */
+export declare function resetHandedOffDaemonActions(now: number): number;

package/dist/core/canvas/daemon-actions.js

@@ -0,0 +1,28 @@
+var f=Object.defineProperty;var a=(t,e)=>f(t,"name",{value:e,configurable:!0});import{prepared as n}from"../sqlite-statements.js";import{randomBytes as T}from"node:crypto";import{openDb as l,withCanvasWrite as _}from"./db.js";import{normalizedSettlement as A}from"./deliveries.js";import{withRetryBudget as L}from"./delivery-contract.js";import{emitEvent as y}from"../events/emit.js";function h(t){t.exec(`CREATE TABLE IF NOT EXISTS daemon_actions (
+    action_id TEXT PRIMARY KEY,
+    adapter_json TEXT NOT NULL,
+    body_json TEXT,
+    idempotency_key TEXT NOT NULL UNIQUE,
+    state TEXT NOT NULL CHECK (state IN ('pending', 'handed_off', 'acknowledged', 'permanent_failed')),
+    attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+    next_attempt_at INTEGER,
+    claimed_at INTEGER,
+    claim_owner TEXT,
+    acknowledged_at INTEGER,
+    failed_at INTEGER,
+    last_failure_json TEXT,
+    canceled_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS daemon_actions_due ON daemon_actions(state, next_attempt_at, created_at, action_id) WHERE canceled_at IS NULL;`)}a(h,"createDaemonActionsTable");function m(t){return{actionId:t.action_id,adapter:JSON.parse(t.adapter_json),body:t.body_json===null?null:JSON.parse(t.body_json),idempotencyKey:t.idempotency_key,state:t.state,attempts:t.attempts,nextAttemptAt:t.next_attempt_at,claimedAt:t.claimed_at,claimOwner:t.claim_owner,acknowledgedAt:t.acknowledged_at,failedAt:t.failed_at,lastFailure:t.last_failure_json===null?null:JSON.parse(t.last_failure_json),canceledAt:t.canceled_at,createdAt:t.created_at,updatedAt:t.updated_at}}a(m,"actionFrom");function g(){return T(16).toString("hex")}a(g,"newId");function b(t){return _(e=>{const i=n(e,"SELECT action_id FROM daemon_actions WHERE idempotency_key = ?").get(t.idempotencyKey);if(i!==void 0)return i.action_id;const c=Date.now(),d=g(),r=t.bodyJson===void 0?null:JSON.stringify(t.bodyJson);return n(e,`INSERT INTO daemon_actions (action_id, adapter_json, body_json, idempotency_key, state, attempts, next_attempt_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, 'pending', 0, ?, ?, ?)`).run(d,JSON.stringify(t.adapter),r,t.idempotencyKey,c,c,c),d})}a(b,"enqueueDaemonAction");function H(t){const e=n(l(),"SELECT * FROM daemon_actions WHERE idempotency_key = ?").get(t);return e===void 0?null:m(e)}a(H,"readDaemonAction");function j(t){const e=n(l(),"SELECT * FROM daemon_actions WHERE action_id = ?").get(t);return e===void 0?null:m(e)}a(j,"readDaemonActionById");function C(t){return n(l(),`SELECT * FROM daemon_actions
+      WHERE state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?
+      ORDER BY next_attempt_at, created_at, action_id`).all(t).map(m)}a(C,"dueDaemonActions");function k(t,e,i){return _(c=>{const d=n(c,`UPDATE daemon_actions SET state = 'handed_off', attempts = attempts + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+        WHERE action_id = ? AND state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?`).run(e,i,e,t,e);return Number(d.changes)===0?null:m(n(c,"SELECT * FROM daemon_actions WHERE action_id = ?").get(t))})}a(k,"claimDaemonAction");function F(t,e,i,c,d=Date.now()){const r=L(A(c),e),o=r.settlement,p=o.state==="pending"||o.state==="permanent_failed"?JSON.stringify(o.failure):null,s=o.state==="released"?"pending":o.state,u=o.state==="pending"?o.nextAttemptAt:s==="pending"?d:null,E=_(N=>Number(n(N,`UPDATE daemon_actions
+        SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+            acknowledged_at = ?, failed_at = ?, last_failure_json = ?, updated_at = ?
+      WHERE action_id = ? AND state = 'handed_off' AND attempts = ? AND claim_owner = ?`).run(s,u,s==="acknowledged"?d:null,s==="permanent_failed"?d:null,p,d,t,e,i).changes)===1);return E&&r.exhausted&&o.state==="permanent_failed"&&y({level:"error",event:"daemon_action.exhausted",outcome:"failed",attempt:e,fields:{action_id:t,failure:o.failure,retry:`crtr sys retry-delivery ${t}`}}),E}a(F,"settleDaemonAction");function W(t,e=Date.now()){return _(i=>Number(n(i,`UPDATE daemon_actions
+        SET state = 'pending', attempts = 0, next_attempt_at = ?, failed_at = NULL, updated_at = ?
+      WHERE action_id = ? AND state = 'permanent_failed' AND canceled_at IS NULL AND last_failure_json IS NOT NULL`).run(e,e,t).changes)===1)}a(W,"retryFailedDaemonAction");function X(t){return _(e=>Number(n(e,`UPDATE daemon_actions SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+      WHERE state = 'handed_off'`).run(t,t).changes))}a(X,"resetHandedOffDaemonActions");export{k as claimDaemonAction,h as createDaemonActionsTable,C as dueDaemonActions,b as enqueueDaemonAction,H as readDaemonAction,j as readDaemonActionById,X as resetHandedOffDaemonActions,W as retryFailedDaemonAction,F as settleDaemonAction};

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;
+};

package/dist/core/canvas/daemon-owner.js

@@ -0,0 +1,6 @@
+var T=Object.defineProperty;var r=(e,n)=>T(e,"name",{value:n,configurable:!0});import{prepared as u}from"../sqlite-statements.js";import{openDb as m,withCanvasWrite as l}from"./db.js";import{capturePidIdentities as _,recordedPidLiveness as v}from"./pid.js";const s="daemon_owner";function E(e){return JSON.stringify({pid:e.pid,pid_identity:e.pid_identity,token:e.token})}r(E,"serializeClaim");function h(e){let n;try{n=JSON.parse(e)}catch{return null}if(typeof n!="object"||n===null)return null;const{pid:t,pid_identity:i,token:a}=n;return!Number.isInteger(t)||t<=0||typeof i!="string"||i.length===0||typeof a!="string"||a.length===0?null:{pid:t,pid_identity:i,token:a}}r(h,"parseClaim");function y(){m().exec(`
+    CREATE TABLE IF NOT EXISTS canvas_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `)}r(y,"ensureOwnerTable");function g(){const e=m();return u(e,"SELECT value FROM canvas_meta WHERE key = ?").get(s)?.value}r(g,"readSnapshot");function w(e){const n=_([process.pid]),t=n?.get(process.pid);if(n===null||t===void 0)return{claimed:!1,reason:"own_identity_indeterminate"};const i={pid:process.pid,pid_identity:t,token:e},a=E(i);for(y();;){const d=g();if(d===void 0){if(l(f=>u(f,"INSERT INTO canvas_meta (key, value) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM canvas_meta WHERE key = ?)").run(s,a,s).changes)===1)return{claimed:!0,claim:i};continue}const c=h(d);if(c===null)return{claimed:!1,reason:"incumbent_malformed"};const o=v(c.pid,c.pid_identity);if(o==="alive"||o==="indeterminate")return{claimed:!1,reason:o==="alive"?"incumbent_alive":"incumbent_indeterminate",incumbentPid:c.pid,verdict:o};if(l(p=>u(p,"UPDATE canvas_meta SET value = ? WHERE key = ? AND value = ?").run(a,s,d).changes)===1)return{claimed:!0,claim:i}}}r(w,"claimDaemonOwnership");function I(e){return{released:l(t=>u(t,"DELETE FROM canvas_meta WHERE key = ? AND value = ?").run(s,E(e)).changes)===1}}r(I,"releaseDaemonOwnership");export{s as DAEMON_OWNER_META_KEY,w as claimDaemonOwnership,I as releaseDaemonOwnership};

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

@@ -0,0 +1,33 @@
+import { DatabaseSync } from 'node:sqlite';
+export { MIGRATIONS } from './migrations.js';
+export { prepared } from '../sqlite-statements.js';
+/** A schema change invalidates statements compiled against the old schema. */
+export declare function migrate(db: DatabaseSync): void;
+/** Only the daemon (and its API-server test host) registers this process-local hook.
+ * Register after migration: TEMP triggers need the real tables to exist. */
+export declare function bindDaemonCanvasOpenHook(hook: (db: DatabaseSync) => void): void;
+export declare function clearDaemonCanvasOpenHook(): void;
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, configuring WAL
+ *  but never changing its schema. Keyed by path so tests with distinct homes get
+ *  independent handles.
+ *
+ *  A cache hit trusts the cached handle outright: `crtrd` is this process's
+ *  sole canvas-db owner (see `crtrd-sole-state-owner`), and nothing outside
+ *  `openDb`/`closeDb` ever touches `handles` — there is no other actor in this
+ *  process that could invalidate a live handle out from under it. (A
+ *  2026-06-25 revision added a `PRAGMA database_list` liveness probe here that
+ *  silently closed and reopened the handle on any throw; it shipped alongside
+ *  an unrelated guest-relay `PATH` fix for the now-removed `hearth` guest
+ *  bootstrap, named no concrete failure mode in its commit or a test, and that
+ *  guest-relay path no longer exists. Removed rather than kept-and-logged: a
+ *  silent boot-path reopen is worse than trusting a handle this process
+ *  already owns.) */
+export declare function openDb(): DatabaseSync;
+/** Run `body` under the canvas SQLite write lock, joining an outer transaction
+ *  when the shared connection already owns one. This is the common boundary for
+ *  multi-statement mutations whose reads and writes must linearize as one unit;
+ *  `node:sqlite` rejects nested BEGINs, so only the outermost call commits.
+ */
+export declare function withCanvasWrite<T>(body: (db: DatabaseSync) => T): T;
+/** Close and forget the handle for the current home. Mainly for tests. */
+export declare function closeDb(): void;

package/dist/core/canvas/db.js

@@ -0,0 +1,2 @@
+var m=Object.defineProperty;var n=(e,t)=>m(e,"name",{value:t,configurable:!0});import{DatabaseSync as f}from"node:sqlite";import{forgetPrepared as a}from"../sqlite-statements.js";import{appendFileSync as u}from"node:fs";import{canvasDbPath as i,ensureHome as d}from"./paths.js";import{initializeEmptyLayout as l}from"../layout.js";import{migrate as x}from"./migrations.js";import{MIGRATIONS as L}from"./migrations.js";import{prepared as S}from"../sqlite-statements.js";function R(e){try{x(e)}finally{a(e)}}n(R,"migrate");const o=new Map;let c;function w(e){const t=s();e(t),c=e}n(w,"bindDaemonCanvasOpenHook");function E(){c=void 0}n(E,"clearDaemonCanvasOpenHook");function g(){const e=process.env.CRTR_DB_OPEN_LEDGER;if(e)try{const t=`${new Date().toISOString()} ${process.pid} ${process.argv[1]??"<unknown>"}
+`;u(e,t)}catch{}}n(g,"recordOpenLedger");function s(){const e=i(),t=o.get(e);if(t)return t;l(),d(),g();const r=new f(e);r.exec("PRAGMA busy_timeout = 5000;"),r.exec("PRAGMA journal_mode = WAL;"),r.exec("PRAGMA foreign_keys = ON;");try{c?.(r)}catch(p){throw r.close(),p}return o.set(e,r),r}n(s,"openDb");function I(e){const t=s();if(t.isTransaction)return e(t);t.exec("BEGIN IMMEDIATE");try{const r=e(t);return t.exec("COMMIT"),r}catch(r){try{t.exec("ROLLBACK")}catch{}throw r}}n(I,"withCanvasWrite");function v(){const e=i(),t=o.get(e);t&&(a(t),t.close(),o.delete(e))}n(v,"closeDb");export{L as MIGRATIONS,w as bindDaemonCanvasOpenHook,E as clearDaemonCanvasOpenHook,v as closeDb,R as migrate,s as openDb,S as prepared,I as withCanvasWrite};