@crouton-kit/crouter 0.3.33 → 0.3.34

package/dist/core/canvas/boot.js

@@ -0,0 +1,157 @@
+// Detects a boot change (a host reboot, or — the case this exists for — a
+// Blaxel/Firecracker microVM destroy+recreate) so callers can stop trusting any
+// `pi_pid` recorded before it.
+//
+// canvas.db is durable — it survives a VM/sandbox destroy+recreate or a host
+// reboot on whatever volume it lives on (see paths.ts / the storage-tiers
+// doc) — but `pi_pid` is a raw OS pid: once the process table resets, a small
+// stale pid can coincidentally collide with an unrelated process that now
+// happens to hold that number, so `isPidAlive` reads it "alive" when the
+// broker it once named is long gone. Left unchecked this fools BOTH the
+// daemon's own liveness poll (crtrd.ts) and reviveNode's double-launch guard
+// (revive.ts) into believing a dead broker is still running — the node then
+// stays permanently unrevivable until a human runs `canvas revive --fresh`.
+//
+// The signal (primary): the Linux kernel's per-boot identity at
+// `/proc/sys/kernel/random/boot_id` — a fresh random UUID minted on every
+// kernel boot. A Firecracker microVM recreate (Blaxel's deployment shape) boots
+// a brand-new kernel, so `boot_id` changes; a plain daemon restart within the
+// same boot leaves it identical. This is an EXACT identity, so on Linux we need
+// no wall-clock window at all. NOTE this detects a *kernel boot*, not an
+// arbitrary container recreate: an ordinary container that shares the host
+// kernel keeps the host's `boot_id` across recreation, so this would NOT fire
+// there — that shape is out of scope (Hearth runs on Firecracker microVMs).
+//
+// The signal (fallback, non-Linux dev only): `os.uptime()` resets to ~0 on a
+// reboot and is otherwise monotonic, so `now - uptime` estimates the current
+// boot's wall-clock start (the "boot epoch"). Used only when `boot_id` is
+// unavailable (e.g. macOS dev), where a genuine reboot/recreate is not a
+// production concern; the epoch comparison keeps a generous tolerance there.
+//
+// The last-seen identity is persisted in canvas.db (the same durable tier the
+// pids live in) as a single `canvas_meta` row, and the compare+sweep runs in
+// ONE `BEGIN IMMEDIATE` transaction so concurrent callers (daemon startup and a
+// manual/direct revive in another process) are serialized: a second caller
+// blocks on the write lock, then reads the marker the first already updated and
+// no-ops, so it can never clear a pid the first just recorded (single-writer).
+import { readFileSync } from 'node:fs';
+import { uptime } from 'node:os';
+import { openDb } from './db.js';
+/** Wall-clock epoch drift (fallback signal only) beyond which two boot-start
+ *  estimates are called DIFFERENT boots. Absorbs clock-sync jitter (NTP, a VM's
+ *  first sync after boot) and `os.uptime()`'s ~1s resolution. Only consulted
+ *  when the exact kernel `boot_id` is unavailable on BOTH sides (non-Linux
+ *  dev). A false positive would clear a genuinely live pid and let reviveNode
+ *  double-spawn onto the same session; a false negative just falls back to the
+ *  manual `--fresh` status quo — so it is kept generous, biased against the
+ *  dangerous direction. The production target (Linux/Firecracker) never reaches
+ *  this branch; there `boot_id` is exact. */
+const BOOT_EPOCH_TOLERANCE_MS = 60_000;
+function readKernelBootId() {
+    try {
+        const id = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+        return id.length > 0 ? id : null;
+    }
+    catch {
+        return null; // non-Linux, or unreadable — fall back to the wall-clock epoch
+    }
+}
+/** Identity of the CURRENT OS boot. `now` is injectable for tests. */
+export function currentBootIdentity(now = Date.now()) {
+    return { bootId: readKernelBootId(), bootEpochMs: now - Math.round(uptime() * 1000) };
+}
+/** Pure decision core: does `current` belong to a DIFFERENT boot than the
+ *  persisted `known`? `known === null` (no history — a fresh install, or the
+ *  first run of a build that added this marker) is never a boot change: there
+ *  is nothing to contradict it, and treating "no history" as a change could
+ *  clear genuinely live pids that predate this feature.
+ *
+ *  When BOTH sides carry a kernel `boot_id`, that exact identity decides it — no
+ *  wall-clock window, so a real quick reboot/recreate (a short-lived prior boot
+ *  whose start is <60s away) is still detected. Only when a `boot_id` is missing
+ *  on either side (non-Linux dev) does it fall back to the epoch-drift window.
+ *  Unit-testable without real uptime/fs. */
+export function bootChanged(current, known) {
+    if (known === null)
+        return false;
+    if (current.bootId !== null && known.bootId !== null) {
+        return current.bootId !== known.bootId;
+    }
+    return Math.abs(current.bootEpochMs - known.bootEpochMs) > BOOT_EPOCH_TOLERANCE_MS;
+}
+const BOOT_MARKER_KEY = 'boot_identity';
+function readBootMarker(db) {
+    const row = db
+        .prepare('SELECT value FROM canvas_meta WHERE key = ?')
+        .get(BOOT_MARKER_KEY);
+    if (row === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(row.value);
+        if (typeof parsed.bootEpochMs !== 'number')
+            return null;
+        return {
+            bootId: typeof parsed.bootId === 'string' ? parsed.bootId : null,
+            bootEpochMs: parsed.bootEpochMs,
+        };
+    }
+    catch {
+        return null; // malformed — treat as "no history yet"
+    }
+}
+function writeBootMarker(db, identity) {
+    db.prepare('INSERT INTO canvas_meta (key, value) VALUES (?, ?) ' +
+        'ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(BOOT_MARKER_KEY, JSON.stringify(identity));
+}
+/** Idempotent and safe to call from every revive entry point (daemon startup,
+ *  reviveNode): compares the current boot's identity against the last one
+ *  recorded, and if they differ, clears `pi_pid` on every node that has one —
+ *  regardless of status, since reviveNode's double-launch guard reads `pi_pid`
+ *  unconditionally, not just on active/idle rows. The first caller after a
+ *  genuine boot change does the sweep and persists the new marker; every call
+ *  after that (in this process or another) reads a matching marker and no-ops.
+ *
+ *  SINGLE-WRITER: the whole read-marker + sweep + write-marker runs in one
+ *  `BEGIN IMMEDIATE` transaction. A concurrent caller (a manual revive racing
+ *  daemon startup, in a separate process) blocks on the SQLite write lock until
+ *  this commits, then reads the already-updated marker and no-ops — so it can
+ *  never `clearPid` a broker pid the first caller's revive just recorded, which
+ *  would otherwise hide a live broker behind `pi_pid=NULL` and risk a second
+ *  broker on the same session.
+ *
+ *  `current` defaults to the real identity; tests inject a synthetic one against
+ *  an isolated CRTR_HOME to simulate a boot change without a real reboot. */
+export function reconcileBootLiveness(current = currentBootIdentity()) {
+    const db = openDb();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const known = readBootMarker(db);
+        if (!bootChanged(current, known)) {
+            if (known === null)
+                writeBootMarker(db, current); // seed first-ever marker
+            db.exec('COMMIT');
+            return { changed: false, cleared: [] };
+        }
+        const rows = db
+            .prepare('SELECT node_id FROM nodes WHERE pi_pid IS NOT NULL')
+            .all();
+        const upd = db.prepare('UPDATE nodes SET pi_pid = NULL WHERE node_id = ?');
+        const cleared = [];
+        for (const row of rows) {
+            upd.run(row.node_id);
+            cleared.push(row.node_id);
+        }
+        writeBootMarker(db, current);
+        db.exec('COMMIT');
+        return { changed: true, cleared };
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            /* best-effort — nothing was committed */
+        }
+        throw err;
+    }
+}

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

@@ -87,7 +87,12 @@ export interface PruneResult {
  *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
  *  user closed or detached from. Pure persisted-state removal: the caller MUST
  *  have already torn down the broker engine + viewer (this does not signal any
- *  process). Best-effort dir removal after the row delete, mirroring pruneNodes. */
+ *  process). Reaps this node's triggers FIRST (spec §Deterministic removal,
+ *  criterion 15: target deletion kills any in-flight predicate process group and
+ *  consumes target-bound + owner-armed trigger rows, instead of leaving them to
+ *  the FK cascade alone with no kill and no notice) via the same
+ *  `cancelTriggersFor` seam `close`/`cancel` already use. Best-effort dir removal
+ *  after the row delete, mirroring pruneNodes. */
 export declare function deleteNode(nodeId: string): void;
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
@@ -111,3 +116,24 @@ export declare function pruneNodes(opts: {
     dryRun?: boolean;
     includeStale?: boolean;
 }): PruneResult;
+/** Count-based retention sweep: keep at most `maxNodes` of the MOST-RECENTLY-
+ *  ACTIVE nodes, but NEVER delete a live node — so the real retained floor is
+ *  `max(maxNodes, liveCount)`. Bounds the otherwise-unbounded growth the TTL
+ *  sweep can't (a canvas that never crosses the TTL still grows without limit).
+ *
+ *  Liveness (protected, always kept): status active|idle AND a live `pi_pid` —
+ *  the SAME signal `pruneNodes`'s `includeStale` and placement use (`isPidAlive`).
+ *  The caller ($CRTR_NODE_ID) is also always protected.
+ *
+ *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
+ *  to `created`); `target = max(maxNodes, liveCount)`; delete every node ranked
+ *  beyond `target` (0-indexed rank >= target) that is NOT live and NOT the caller.
+ *  Retained = all live + the newest terminal nodes up to `target`.
+ *
+ *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
+ *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export declare function pruneToLimit(opts: {
+    maxNodes: number;
+    dryRun?: boolean;
+}): PruneResult;

package/dist/core/canvas/canvas.js

@@ -4,11 +4,12 @@
 // Source-of-truth split: a node's meta.json is canonical for its own fields;
 // the db row is a queryable index re-derivable from it. The subscribes_to edges
 // are db-authoritative (mutable, many-writers — what WAL is for).
-import { existsSync, readFileSync, renameSync, readdirSync, rmSync, openSync, writeSync, fsyncSync, closeSync, } from 'node:fs';
+import { existsSync, readFileSync, renameSync, readdirSync, rmSync, openSync, writeSync, fsyncSync, closeSync, statSync, } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { openDb } from './db.js';
 import { isPidAlive } from './pid.js';
-import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from './paths.js';
+import { cancelTriggersFor } from './triggers.js';
+import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
 // ---------------------------------------------------------------------------
 // meta.json (durable identity — the source of truth for what PERSISTS)
 //
@@ -400,8 +401,14 @@ export function rebuildIndex() {
  *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
  *  user closed or detached from. Pure persisted-state removal: the caller MUST
  *  have already torn down the broker engine + viewer (this does not signal any
- *  process). Best-effort dir removal after the row delete, mirroring pruneNodes. */
+ *  process). Reaps this node's triggers FIRST (spec §Deterministic removal,
+ *  criterion 15: target deletion kills any in-flight predicate process group and
+ *  consumes target-bound + owner-armed trigger rows, instead of leaving them to
+ *  the FK cascade alone with no kill and no notice) via the same
+ *  `cancelTriggersFor` seam `close`/`cancel` already use. Best-effort dir removal
+ *  after the row delete, mirroring pruneNodes. */
 export function deleteNode(nodeId) {
+    cancelTriggersFor(nodeId);
     openDb().prepare('DELETE FROM nodes WHERE node_id = ?').run(nodeId);
     rmSync(nodeDir(nodeId), { recursive: true, force: true });
 }
@@ -458,7 +465,24 @@ export function pruneNodes(opts) {
     const candidates = [...terminal, ...stale];
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
-    // One transactioned sweep — delete the rows; the FK cascades their edges.
+    deletePrunedNodes(candidates);
+    return { pruned: candidates, dryRun };
+}
+/** Hard-delete a set of pruned nodes: reaps each node's triggers (killing any
+ *  in-flight predicate process group and consuming target-bound + owner-armed
+ *  rows — spec criterion 15, the same reap {@link deleteNode} does) BEFORE the
+ *  transactioned row sweep (the edges→nodes FK, ON DELETE CASCADE, GCs their
+ *  edges), followed by best-effort on-disk `nodes/<id>/` dir removal. Shared by
+ *  {@link pruneNodes} (TTL) and {@link pruneToLimit} (count) so the delete
+ *  semantics never drift. The fs isn't transactional, so dirs are removed AFTER
+ *  COMMIT — by then the rows are gone, so a re-run never re-finds a
+ *  half-deleted node. */
+function deletePrunedNodes(candidates) {
+    if (candidates.length === 0)
+        return;
+    for (const c of candidates)
+        cancelTriggersFor(c.node_id);
+    const db = openDb();
     db.exec('BEGIN');
     try {
         const del = db.prepare('DELETE FROM nodes WHERE node_id = ?');
@@ -470,9 +494,66 @@ export function pruneNodes(opts) {
         db.exec('ROLLBACK');
         throw e;
     }
-    // Remove each pruned node's on-disk dir (best-effort, after COMMIT).
     for (const c of candidates) {
         rmSync(nodeDir(c.node_id), { recursive: true, force: true });
     }
+}
+/** "Most recent activity" sort key (epoch ms) read CHEAPLY: a `statSync` (no file
+ *  read, no parse) of the node's `job/telemetry.json` — rewritten on every
+ *  turn_end at a deterministic path, so it tracks last-message recency without a
+ *  meta read. Falls back to `created`'s epoch when a node never ran a turn.
+ *  Mirrors render.ts's `sessionMtime` (the same key the snapshot roster surfaces
+ *  as `last_activity`). Never throws. */
+function recencyMs(nodeId, created) {
+    try {
+        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+        if (st !== undefined)
+            return st.mtimeMs;
+    }
+    catch {
+        /* fall through to created */
+    }
+    const t = Date.parse(created);
+    return Number.isNaN(t) ? 0 : t;
+}
+/** Count-based retention sweep: keep at most `maxNodes` of the MOST-RECENTLY-
+ *  ACTIVE nodes, but NEVER delete a live node — so the real retained floor is
+ *  `max(maxNodes, liveCount)`. Bounds the otherwise-unbounded growth the TTL
+ *  sweep can't (a canvas that never crosses the TTL still grows without limit).
+ *
+ *  Liveness (protected, always kept): status active|idle AND a live `pi_pid` —
+ *  the SAME signal `pruneNodes`'s `includeStale` and placement use (`isPidAlive`).
+ *  The caller ($CRTR_NODE_ID) is also always protected.
+ *
+ *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
+ *  to `created`); `target = max(maxNodes, liveCount)`; delete every node ranked
+ *  beyond `target` (0-indexed rank >= target) that is NOT live and NOT the caller.
+ *  Retained = all live + the newest terminal nodes up to `target`.
+ *
+ *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
+ *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export function pruneToLimit(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const rows = listNodes();
+    // Rank ALL nodes by recency DESC, tagging liveness as we go.
+    const ranked = rows
+        .map((r) => ({
+        node_id: r.node_id,
+        status: r.status,
+        created: r.created,
+        recency: recencyMs(r.node_id, r.created),
+        live: (r.status === 'active' || r.status === 'idle') && isPidAlive(r.pi_pid),
+    }))
+        .sort((a, b) => b.recency - a.recency);
+    const liveCount = ranked.filter((r) => r.live).length;
+    const target = Math.max(opts.maxNodes, liveCount);
+    const candidates = ranked
+        .filter((r, rank) => rank >= target && !r.live && r.node_id !== selfId)
+        .map((r) => ({ node_id: r.node_id, status: r.status, created: r.created }));
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    deletePrunedNodes(candidates);
     return { pruned: candidates, dryRun };
 }

package/dist/core/canvas/db.js

@@ -232,7 +232,7 @@ CREATE TABLE IF NOT EXISTS focuses (
  *  `owner_id` is the ARMER, set on EVERY row, and is deliberately a PLAIN indexed
  *  column with NO FK (design D1/D2): an FK on `owner_id` would cascade-drop a
  *  crashed-then-pruned armer's detached cron, violating Invariant E. A detached
- *  wake is reaped only by the explicit `cancelWakesFor` DELETE, never by cascade.
+ *  wake is reaped only by the explicit `cancelTriggersFor` DELETE, never by cascade.
  *
  *  `fire_at` is an ISO 8601 UTC string for the NEXT occurrence, so the per-tick
  *  due query is a lexicographic `<=` compare. The partial unique index
@@ -256,6 +256,76 @@ CREATE INDEX IF NOT EXISTS idx_wakeups_owner ON wakeups(owner_id);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_wakeups_deadline ON wakeups(node_id) WHERE kind = 'deadline';
 `);
 }
+/** v9 — generalize the `wakeups` table (v7) into the `triggers` table (the
+ *  unified node-trigger-grammar substrate). The old `kind` axis (bare/noted/
+ *  deadline/spawn) splits into three orthogonal axes: `action` (what enacts:
+ *  'msg'|'new') x `action_mode` (how: 'inbox_message'|'fresh_revive'|
+ *  'deadline_message'|'node_birth') x `trigger_type` (when: 'at'|'every'|
+ *  'when'|'until') — so a daemon-owned predicate (`--when`) trigger can live in
+ *  the same table as a clock trigger. Predicate-only columns (`when_script`
+ *  through `last_stderr`) are additive null/idle for every migrated clock row.
+ *
+ *  Migration mapping, preserving every existing `wakeup_id` as `trigger_id`
+ *  (so an old wake's id stays cancelable): bare→fresh_revive, noted→
+ *  inbox_message, deadline→deadline_message (trigger_type='until'), spawn→
+ *  node_birth. `payload` JSON carries over unchanged — the old per-kind
+ *  payload shapes (plus SpawnChildOpts) map 1:1 onto the new payload union at
+ *  the TS layer (triggers.ts), no JSON transform needed. The `wakeups` table
+ *  is then DROPPED — not kept as a parallel table. Additive, forward-only. */
+function migrateWakeupsToTriggers(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS triggers (
+  trigger_id        TEXT PRIMARY KEY,
+  owner_id          TEXT NOT NULL,
+  node_id           TEXT,                       -- TARGET + node-anchored cancel anchor; NULL = canvas-detached
+  action            TEXT NOT NULL,               -- 'msg' | 'new'
+  action_mode       TEXT NOT NULL,               -- 'inbox_message' | 'fresh_revive' | 'deadline_message' | 'node_birth'
+  trigger_type      TEXT NOT NULL,               -- 'at' | 'every' | 'when' | 'until'
+  fire_at           TEXT,                        -- clock triggers: NEXT occurrence, ISO 8601 UTC; lexicographic <=
+  recur             TEXT,                        -- NULL = one-shot; else the recur JSON the daemon advances
+  payload           TEXT,                        -- JSON action payload, discriminated by action_mode
+  when_script       TEXT,                        -- predicate triggers: the --when bash source
+  eval_every        TEXT,                        -- predicate triggers: evaluation cadence (recur-shaped JSON)
+  next_eval_at      TEXT,                        -- predicate triggers: next evaluation instant
+  timeout_at        TEXT,                        -- predicate triggers: wall-clock expiry
+  eval_state        TEXT NOT NULL DEFAULT 'idle', -- 'idle' | 'running'
+  eval_started_at   TEXT,
+  eval_pid          INTEGER,
+  eval_lease_owner  TEXT,
+  last_eval_at      TEXT,
+  last_exit         INTEGER,
+  last_stderr       TEXT,
+  created           TEXT NOT NULL,
+  FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_triggers_fire  ON triggers(fire_at);                  -- clock per-tick due query
+CREATE INDEX IF NOT EXISTS idx_triggers_node  ON triggers(node_id);                  -- by-node cancel / list
+CREATE INDEX IF NOT EXISTS idx_triggers_owner ON triggers(owner_id);                 -- by-owner reap
+CREATE INDEX IF NOT EXISTS idx_triggers_eval  ON triggers(eval_state, next_eval_at); -- predicate due query
+CREATE UNIQUE INDEX IF NOT EXISTS idx_triggers_deadline ON triggers(node_id) WHERE action_mode = 'deadline_message';
+
+INSERT INTO triggers (trigger_id, owner_id, node_id, action, action_mode, trigger_type, fire_at, recur, payload, created)
+SELECT
+  wakeup_id,
+  owner_id,
+  node_id,
+  CASE kind WHEN 'spawn' THEN 'new' ELSE 'msg' END,
+  CASE kind
+    WHEN 'bare' THEN 'fresh_revive'
+    WHEN 'noted' THEN 'inbox_message'
+    WHEN 'deadline' THEN 'deadline_message'
+    WHEN 'spawn' THEN 'node_birth'
+  END,
+  CASE WHEN kind = 'deadline' THEN 'until' WHEN recur IS NULL THEN 'at' ELSE 'every' END,
+  fire_at,
+  recur,
+  payload,
+  created
+FROM wakeups;
+
+DROP TABLE wakeups;
+`);
+}
 /** v8 — additive identity column `host_kind`: which HOST launches + supervises a
  *  node — `'tmux'` (a pane) or `'broker'` (the headless in-process engine). It is
  *  durable IDENTITY mirrored from meta.json like `cwd` (NOT runtime like `pane`),
@@ -266,6 +336,19 @@ function addHostKindColumn(db) {
     const columns = nodeColumns(db);
     addNodeColumnIfMissing(db, columns, 'host_kind', `ALTER TABLE nodes ADD COLUMN host_kind TEXT;`);
 }
+/** v10 — the `canvas_meta` key/value table: a single durable place for
+ *  small, cross-process canvas-wide scalars that aren't node rows. First user:
+ *  the boot marker (boot.ts), which records the last-seen kernel boot identity
+ *  so boot-liveness reconciliation is a single-writer SQLite transaction on
+ *  this row rather than a race-prone JSON file. Additive, forward-only. */
+function addCanvasMetaTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS canvas_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`);
+}
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
  *  `user_version` tracks how many have been applied. Append only. */
 export const MIGRATIONS = [
@@ -277,6 +360,8 @@ export const MIGRATIONS = [
     /* v6 */ addFocusesTable,
     /* v7 */ appendWakeupsTable,
     /* v8 */ addHostKindColumn,
+    /* v9 */ migrateWakeupsToTriggers,
+    /* v10 */ addCanvasMetaTable,
 ];
 /** Bring `db` up to the latest schema version. Reads `user_version`, runs each
  *  pending migration in order, and bumps `user_version` after each so the work

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

@@ -4,6 +4,6 @@ export * from './paths.js';
 export * from './canvas.js';
 export * from './history.js';
 export * from './focuses.js';
-export * from './wakeups.js';
+export * from './triggers.js';
 export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

@@ -6,6 +6,6 @@ export * from './paths.js';
 export * from './canvas.js';
 export * from './history.js';
 export * from './focuses.js';
-export * from './wakeups.js';
+export * from './triggers.js';
 export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

package/dist/core/canvas/nav-model.js

@@ -1,7 +1,7 @@
 // nav-model.ts — the pure model/render layer of the canvas graph-nav chrome.
 //
 // Extracted from src/pi-extensions/canvas-nav.ts so a SINGLE source feeds both
-// the legacy pi extension (canvas-nav) and the headless `crtr attach` viewer.
+// the legacy pi extension (canvas-nav) and the headless `crtr surface attach` viewer.
 // Everything here is pi-API-free: it reads the canvas (sqlite + meta.json + node
 // telemetry) and produces ANSI-styled strings + a flattened graph model. The
 // extension-host wiring (widgets, key taps, the ask-poll timer, run/focus

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

@@ -2,3 +2,9 @@
  *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
  *  ours — still alive. A null/undefined pid (legacy / never-booted) reads dead. */
 export declare function isPidAlive(pid: number | null | undefined): boolean;
+/** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
+ *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of
+ *  an in-flight predicate evaluation) and daemon/predicate-eval.ts (per-eval
+ *  timeout + stale-lease recovery kills). Lives beside isPidAlive: canvas/ is
+ *  the lowest shared layer every process-liveness/-teardown primitive sits at. */
+export declare function killProcessGroup(pid: number, signal?: NodeJS.Signals): void;

package/dist/core/canvas/pid.js

@@ -21,3 +21,16 @@ export function isPidAlive(pid) {
         return e.code === 'EPERM';
     }
 }
+/** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
+ *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of
+ *  an in-flight predicate evaluation) and daemon/predicate-eval.ts (per-eval
+ *  timeout + stale-lease recovery kills). Lives beside isPidAlive: canvas/ is
+ *  the lowest shared layer every process-liveness/-teardown primitive sits at. */
+export function killProcessGroup(pid, signal = 'SIGTERM') {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        /* already gone */
+    }
+}

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

@@ -0,0 +1,108 @@
+import type { ArmTriggerSpec, Trigger, TriggerScope } from './types.js';
+/** A thrown integrity-backstop error from armTrigger. `code` is mapped by the
+ *  command surface to a rendered error block — armTrigger carries integrity
+ *  backstops only (empty body / recur-on-deadline / unknown action_mode);
+ *  target-resolvability + recoverable-state + per-owner cap checks live in the
+ *  surface, so a non-surface armer could insert a dangling trigger — every
+ *  armer MUST route through the surface. */
+export declare class TriggerArmError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** INSERT one trigger row from the pinned spec, returning its (caller-supplied)
+ *  `trigger_id`. JSON.stringifies the typed `payload` union into the TEXT
+ *  column and stamps `created`.
+ *
+ *  Deadline upsert (≤1 deadline per node): for `action_mode === 'deadline_message'`
+ *  the node's existing deadline is canceled first, then the new one inserted —
+ *  the partial unique index `idx_triggers_deadline` is the schema-level
+ *  backstop.
+ *
+ *  Integrity backstops (throw TriggerArmError):
+ *   - empty/whitespace payload `body` for inbox_message/deadline_message → `empty_body`
+ *     (a `trigger_type='when'` inbox_message may omit body entirely instead —
+ *     that is the stdout-as-body case, not a violation).
+ *   - non-NULL `recur` on a deadline_message                              → `deadline_cannot_recur`.
+ *   - unknown `action_mode`                                               → `bad_action_mode`. */
+export declare function armTrigger(spec: ArmTriggerSpec): string;
+/** UPDATE the next fire time — clock recurrence advancement (the daemon settles
+ *  a recurring row to its next slot BEFORE enacting, crash-safe). */
+export declare function advanceTrigger(trigger_id: string, nextFireIso: string): void;
+/** DELETE one trigger by id — one-shot consumption (the daemon settles a
+ *  one-shot row BEFORE enacting, crash-safe). */
+/** Deletes the row and reports whether it actually removed a LIVE one (vs a
+ *  no-op on an already-gone trigger) — callers racing another consumer of the
+ *  same trigger (e.g. predicate-eval.ts's close handler racing a wall-clock
+ *  reaper's kill) use the return value to no-op instead of double-enacting. */
+export declare function consumeTrigger(trigger_id: string): boolean;
+/** DELETE one trigger by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error. Kills any in-flight predicate process group for this
+ *  trigger before deleting. */
+export declare function cancelTrigger(trigger_id: string): void;
+/** DELETE every trigger anchored to this node AND every detached trigger it
+ *  ARMED — deliberate close/reap. Hooked at transition('cancel'). */
+export declare function cancelTriggersFor(node_id: string): void;
+/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored
+ *  recurring triggers SURVIVE — finalize is the instance finishing, not a
+ *  teardown of standing schedules. Hooked at transition('finalize'). */
+export declare function cancelSelfAlarms(node_id: string): void;
+/** DELETE this node's pending deadline(s) — cancel-on-wake. Hooked at
+ *  reviveNode, so the deadline always belongs to the dormancy left. */
+export declare function cancelDeadlinesFor(node_id: string): void;
+/** The daemon's per-tick due query for CLOCK triggers only (`at`/`every`/
+ *  `until` — predicate `when` triggers fire via next_eval_at, see
+ *  duePredicateTriggers): every row whose fire_at has arrived, in fire_at
+ *  order, with `payload` parsed into the typed union. Returns exactly ONE row
+ *  per recurring trigger regardless of missed slots — coalescing is structural. */
+export declare function dueClockTriggers(nowIso: string): Trigger[];
+/** List triggers for a scope (node / owner / subtree / due / canvas), `payload`
+ *  parsed as in dueClockTriggers. The subtree variant binds the id set with `?`
+ *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN
+ *  spot); ids are NEVER string-concatenated. The `due` scope is clock-only,
+ *  matching dueClockTriggers' filter. */
+export declare function listTriggers(scope: TriggerScope): Trigger[];
+/** True if the node has ANY pending self-anchored trigger (of any type).
+ *  Consumed by the stop-guard self-wake seam so a no-child poll node releases
+ *  dormant after arming instead of being nagged to finish. */
+export declare function hasPendingSelfTrigger(node_id: string): boolean;
+/** Predicate triggers due for evaluation: idle, `next_eval_at` arrived,
+ *  deterministic order (`next_eval_at`, then `created`, then `trigger_id` —
+ *  spec §Daemon behavior step 3). Capacity enforcement (max concurrent
+ *  canvas-wide / per-owner) is the daemon's job, not this query's. */
+export declare function duePredicateTriggers(nowIso: string): Trigger[];
+/** Atomically acquire the idle lease for one predicate evaluation: flips
+ *  `eval_state` to 'running' and records lease/pid metadata, but ONLY if the
+ *  row is still idle (the `WHERE eval_state = 'idle'` guard is the atomicity —
+ *  two daemons racing the same row can't both win). Returns whether THIS call
+ *  acquired it. */
+export declare function acquirePredicateLease(trigger_id: string, leaseOwner: string, pid: number, startedAtIso: string): boolean;
+/** The settled outcome of one predicate evaluation, to be recorded by
+ *  recordPredicateEvalResult. `exitCode` null means the evaluation timed out
+ *  (no exit was observed). */
+export interface PredicateEvalResult {
+    completedAtIso: string;
+    /** When the row should next be checked (completed_at + eval_every). */
+    nextEvalAtIso: string;
+    exitCode: number | null;
+    stderrTail: string | null;
+}
+/** Record a non-firing predicate evaluation result (exit non-zero, or a
+ *  per-eval timeout): releases the lease back to idle and schedules the next
+ *  check. Exit-0 (fire) is NOT recorded here — the spec's settle-before-enact
+ *  rule means a firing predicate is consumed (consumeTrigger) then enacted,
+ *  never left as an idle row. */
+export declare function recordPredicateEvalResult(trigger_id: string, result: PredicateEvalResult): void;
+/** Every predicate trigger currently marked 'running' — the daemon's stale-
+ *  lease recovery scan on restart checks each recorded `eval_pid` for
+ *  liveness and calls resetPredicateLease for any that's gone. */
+export declare function runningPredicateTriggers(): Trigger[];
+/** Reset a predicate trigger's lease back to idle without recording a result —
+ *  stale-lease recovery for a row whose recorded eval_pid is no longer alive
+ *  (the prior daemon instance died mid-evaluation). */
+export declare function resetPredicateLease(trigger_id: string): void;
+/** Predicate triggers whose WALL-CLOCK timeout has arrived, regardless of
+ *  eval_state (an in-flight evaluation past its own trigger's timeout_at is
+ *  still reaped — the caller kills the process group itself since this is a
+ *  read, not a mutation). Spec §Predicate triggers: "Wall-clock timeout_at
+ *  reached: consume and notify owner." */
+export declare function duePredicateTimeouts(nowIso: string): Trigger[];