@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/core/canvas/canvas.js

@@ -7,6 +7,7 @@
 import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync, rmSync, } from 'node:fs';
 import { join } from 'node:path';
 import { openDb } from './db.js';
+import { isPidAlive } from './pid.js';
 import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from './paths.js';
 // ---------------------------------------------------------------------------
 // meta.json (durable identity — the source of truth for what PERSISTS)
@@ -19,8 +20,8 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from '.
 /** The identity keys meta.json persists. Listed explicitly so no runtime field
  *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
 const IDENTITY_KEYS = [
-    'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'kind', 'mode',
-    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'passive_default',
+    'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'host_kind', 'kind', 'mode',
+    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'passive_default',
     'home_session', 'pi_session_id', 'pi_session_file', 'launch',
 ];
 /** Project any node object down to its durable-identity subset. */
@@ -60,12 +61,13 @@ function writeMeta(meta) {
  *  state. A fresh insert takes the schema defaults for runtime. */
 function upsertRow(meta) {
     openDb()
-        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, parent, created)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, host_kind, parent, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
          name=excluded.name, kind=excluded.kind, mode=excluded.mode,
-         lifecycle=excluded.lifecycle, cwd=excluded.cwd, parent=excluded.parent`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.parent ?? null, meta.created);
+         lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
+         parent=excluded.parent`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.parent ?? null, meta.created);
 }
 /** Seed a node's row at BIRTH: identity columns + runtime columns taken from the
  *  incoming meta (defaults: status='active', the rest null). The only writer
@@ -74,16 +76,17 @@ function upsertRow(meta) {
 function seedRow(meta) {
     openDb()
         .prepare(`INSERT INTO nodes
-         (node_id, name, kind, mode, lifecycle, cwd, parent, created,
+         (node_id, name, kind, mode, lifecycle, cwd, host_kind, parent, created,
           status, intent, pi_pid, "window", tmux_session, pane)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
          name=excluded.name, kind=excluded.kind, mode=excluded.mode,
-         lifecycle=excluded.lifecycle, cwd=excluded.cwd, parent=excluded.parent,
+         lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
+         parent=excluded.parent,
          status=excluded.status, intent=excluded.intent, pi_pid=excluded.pi_pid,
          "window"=excluded."window", tmux_session=excluded.tmux_session,
          pane=excluded.pane`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.parent ?? null, meta.created, meta.status ?? 'active', meta.intent ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.parent ?? null, meta.created, meta.status ?? 'active', meta.intent ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
 }
 function rowFrom(r) {
     return {
@@ -94,6 +97,7 @@ function rowFrom(r) {
         lifecycle: r['lifecycle'],
         status: r['status'],
         cwd: r['cwd'],
+        host_kind: r['host_kind'] ?? null,
         parent: r['parent'] ?? null,
         created: r['created'],
         intent: r['intent'] ?? null,
@@ -352,17 +356,6 @@ export function rebuildIndex() {
             recordSpawn(meta.node_id, prov);
     }
 }
-/** Is `pid` a live process? `kill(pid, 0)` sends no signal — it only probes
- *  existence/permission. ESRCH ⇒ gone; EPERM ⇒ alive but not ours (still alive). */
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e.code === 'EPERM';
-    }
-}
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
@@ -406,7 +399,7 @@ export function pruneNodes(opts) {
         if (r['node_id'] === selfId)
             return false;
         const pid = r['pi_pid'];
-        return pid === null || !pidAlive(pid);
+        return !isPidAlive(pid);
     })
         .map((r) => ({
         node_id: r['node_id'],

package/dist/core/canvas/db.js

@@ -208,6 +208,50 @@ CREATE TABLE IF NOT EXISTS focuses (
 );
 `);
 }
+/** v7 — the `wakeups` table: durable store for scheduled wake-ups (the
+ *  scheduled-wakeups feature). One row per armed wake. `node_id` is the TARGET
+ *  and the node-anchored cancel anchor — it carries a `ON DELETE CASCADE` FK to
+ *  `nodes(node_id)` so a pruned/deleted node's node-anchored wakes are reaped in
+ *  the same transaction (mirroring the edges v4 cascade; works because
+ *  `PRAGMA foreign_keys = ON` is set at every open). NULL `node_id` = a
+ *  canvas-detached wake (deferred spawn / spawn-cron) that survives.
+ *
+ *  `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.
+ *
+ *  `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
+ *  `idx_wakeups_deadline` enforces ≤1 deadline per node. Additive, forward-only. */
+function appendWakeupsTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS wakeups (
+  wakeup_id  TEXT PRIMARY KEY,
+  node_id    TEXT,                       -- TARGET + node-anchored cancel anchor; NULL = canvas-detached
+  owner_id   TEXT NOT NULL,              -- ARMER; set on EVERY row. PLAIN column, NO FK (design D1/D2)
+  fire_at    TEXT NOT NULL,              -- ISO 8601 UTC; NEXT occurrence; lexicographic <=
+  kind       TEXT NOT NULL,              -- 'bare' | 'noted' | 'deadline' | 'spawn'
+  recur      TEXT,                       -- NULL = one-shot; else the pinned recur JSON
+  payload    TEXT,                       -- JSON per kind (shared contracts)
+  created    TEXT NOT NULL,
+  FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_wakeups_fire  ON wakeups(fire_at);                 -- per-tick due query
+CREATE INDEX IF NOT EXISTS idx_wakeups_node  ON wakeups(node_id);                 -- by-node cancel / list
+CREATE INDEX IF NOT EXISTS idx_wakeups_owner ON wakeups(owner_id);               -- by-owner reap (ruling A)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_wakeups_deadline ON wakeups(node_id) WHERE kind = 'deadline';
+`);
+}
+/** 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`),
+ *  so it survives an index rebuild via the `IDENTITY_KEYS`/`upsertRow` path.
+ *  Defaults NULL ⇒ `'tmux'` (every existing node is tmux-hosted); no data
+ *  backfill. Additive, forward-only. */
+function addHostKindColumn(db) {
+    db.exec(`ALTER TABLE nodes ADD COLUMN host_kind TEXT;`);
+}
 /** 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 = [
@@ -217,6 +261,8 @@ export const MIGRATIONS = [
     /* v4 */ edgesForeignKeyCascade,
     /* v5 */ addPaneColumn,
     /* v6 */ addFocusesTable,
+    /* v7 */ appendWakeupsTable,
+    /* v8 */ addHostKindColumn,
 ];
 /** 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

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

package/dist/core/canvas/index.js

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

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

@@ -1,4 +1,7 @@
-/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
 export declare function crtrHome(): string;
 export declare function canvasDbPath(): string;
 export declare function nodesRoot(): string;

package/dist/core/canvas/paths.js

@@ -1,6 +1,6 @@
-// The `~/.crtr/` layout. One global, cwd-agnostic home for the whole canvas.
+// The `~/.crouter/canvas/` layout. One global, cwd-agnostic home for the whole canvas.
 //
-//   ~/.crtr/
+//   ~/.crouter/canvas/
 //     canvas.db                 sqlite (WAL) — topology only (nodes + edges)
 //     nodes/<node_id>/
 //       meta.json               source of truth for the node's row
@@ -15,10 +15,16 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { mkdirSync } from 'node:fs';
-/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+import { CRTR_DIR_NAME } from '../../types.js';
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
 export function crtrHome() {
     const override = process.env['CRTR_HOME'];
-    return override !== undefined && override !== '' ? override : join(homedir(), '.crtr');
+    return override !== undefined && override !== ''
+        ? override
+        : join(homedir(), CRTR_DIR_NAME, 'canvas');
 }
 export function canvasDbPath() {
     return join(crtrHome(), 'canvas.db');

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

@@ -0,0 +1,4 @@
+/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
+ *  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;

package/dist/core/canvas/pid.js

@@ -0,0 +1,23 @@
+// src/core/canvas/pid.ts
+//
+// The ONE shared signal-0 liveness probe. It lives at the canvas/ layer — the
+// LOWEST shared layer — so canvas/, runtime/, AND daemon/ can all import it
+// "down" without a reverse-layer violation (runtime/ sits above canvas/, daemon/
+// above runtime/). It is a pure process-existence utility, NOT data-model access,
+// so it is exempt from the "only canvas.ts touches the db" rule. Collapses the
+// four near-identical copies that used to live in canvas.ts, revive.ts,
+// placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
+/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
+ *  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 function isPidAlive(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { NodeStatus } from './types.js';
+import type { NodeStatus, Lifecycle } from './types.js';
 /**
  * Render the subscription sub-DAG rooted at `rootId` as an ASCII tree.
  * The root is the first line (no connector prefix); children are indented.
@@ -28,11 +28,20 @@ export interface DashboardRow {
     cwd: string;
     /** ISO 8601 birth timestamp — drives the recency sort + the relative-age cue. */
     created: string;
+    /** terminal = one-shot worker (finalizes on push --final); resident = persistent
+     *  agent you come back to. Drives the browser's resident-only lifecycle filter.
+     *  Only populated by dashboardRowsAll (the browser snapshot). */
+    lifecycle?: Lifecycle;
     /** The node's spawn prompt (context/initial-prompt.md), trimmed + capped. Only
      *  populated by dashboardRowsAll (the browser snapshot) — the dashboard leaf
      *  leaves it undefined to avoid a file read per node. Indexed by super-search
-     *  and shown in the preview panel. */
+     *  and shown in the preview panel when there is no live query. */
     goal?: string;
+    /** EVERY user prompt across the node's pi session — the whole conversation, not
+     *  just the spawn prompt — joined + capped. Populated by dashboardRowsAll, undefined
+     *  for never-revived nodes (no session file). Powers whole-conversation super-search
+     *  + the windowed match snippet in the preview. */
+    prompts?: string;
 }
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export declare function dashboardRows(rootId: string): DashboardRow[];

package/dist/core/canvas/render.js

@@ -181,6 +181,73 @@ function readGoalText(nodeId) {
         return undefined;
     }
 }
+/** EVERY user prompt across a node's pi session — the whole conversation, not just
+ *  the spawn prompt. Streams the session jsonl off disk, prefiltering to user-role
+ *  lines so the big assistant/toolResult lines are never JSON-parsed, extracts each
+ *  user message's text, joins newline-separated, and caps total + per-message so a
+ *  long session can't bloat the snapshot. Never throws; returns undefined when there
+ *  is no session file yet (a node that was never revived). */
+const CONVO_CAP = 8192;
+const CONVO_MSG_CAP = 2048;
+function readConversationPrompts(sessionFile) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return undefined;
+    try {
+        if (!existsSync(sessionFile))
+            return undefined;
+        const raw = readFileSync(sessionFile, 'utf8');
+        const parts = [];
+        let total = 0;
+        for (const line of raw.split('\n')) {
+            // Cheap prefilter: skip every line that isn't a user-role message before the
+            // (relatively costly) JSON.parse. Pi writes compact JSON (no spaces), but
+            // tolerate the spaced form too.
+            if (line === '' || (line.indexOf('"role":"user"') === -1 && line.indexOf('"role": "user"') === -1))
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (rec.type !== 'message' || rec.message?.role !== 'user')
+                continue;
+            const text = extractUserText(rec.message.content);
+            if (text === '')
+                continue;
+            const capped = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+            parts.push(capped);
+            total += capped.length + 1;
+            if (total >= CONVO_CAP)
+                break;
+        }
+        if (parts.length === 0)
+            return undefined;
+        const joined = parts.join('\n');
+        return joined.length > CONVO_CAP ? joined.slice(0, CONVO_CAP) : joined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Concatenate the `text` blocks of one pi user message's content. Content is
+ *  usually an array of `{type,text}` blocks but may be a bare string. */
+function extractUserText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    const out = [];
+    for (const block of content) {
+        if (block !== null && typeof block === 'object') {
+            const b = block;
+            if (b.type === 'text' && typeof b.text === 'string')
+                out.push(b.text);
+        }
+    }
+    return out.join(' ').trim();
+}
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export function dashboardRows(rootId) {
     const ids = [rootId, ...view(rootId)];
@@ -219,7 +286,9 @@ export function dashboardRowsAll() {
                 asks: countAsks(row.node_id),
                 cwd: row.cwd,
                 created: row.created,
+                lifecycle: row.lifecycle,
                 goal: readGoalText(row.node_id),
+                prompts: readConversationPrompts(meta?.pi_session_file),
             }];
     });
 }

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

@@ -1,6 +1,10 @@
-/** What a node is doing right now. UI shows active+idle; `done` is hidden but
- *  revivable; `canceled` is a user-closed node (also hidden, also revivable —
- *  not a fault); only `dead` is a fault. */
+import type { SpawnChildOpts } from '../runtime/spawn.js';
+/** What a node is doing right now. `active` means the engine process is live on
+ *  its host — a tmux pane OR a headless broker (`host_kind`) — NOT that it holds
+ *  a window or that anyone is watching it (attachment is a separate axis: the
+ *  `focuses` table for tmux, the broker's viewer set for headless). UI shows
+ *  active+idle; `done` is hidden but revivable; `canceled` is a user-closed node
+ *  (also hidden, also revivable — not a fault); only `dead` is a fault. */
 export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
 /** Does stopping finalize the node? terminal = worker (finalizes on push --final);
  *  resident = manager/orchestrator (stays dormant, woken by inbox). */
@@ -44,6 +48,11 @@ export interface NodeIdentity {
     created: string;
     /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
     cwd: string;
+    /** Which HOST launches + supervises this node: 'tmux' (a pane) or 'broker' (the
+     *  headless in-process engine). Durable IDENTITY (mirrored to the row like
+     *  `cwd`, re-derived on index rebuild), NOT live runtime like `pane`.
+     *  NULL ⇒ 'tmux' (every pre-broker node). */
+    host_kind?: 'tmux' | 'broker' | null;
     /** Role the node was born as: explore | developer | plan | review | general… */
     kind: string;
     mode: Mode;
@@ -65,6 +74,14 @@ export interface NodeIdentity {
      *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
      *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
     spawned_by?: string | null;
+    /** Fork provenance — the `--fork-from` source this node was forked from at
+     *  spawn (the node id / session path / pi session uuid the caller passed). pi
+     *  COPIED that conversation into this node's first session, so the node boots
+     *  carrying the SOURCE's first-person history. Persisted here so the boot
+     *  intro can assert this node's OWN identity over that inherited narrative
+     *  (without it a fork impersonates its source). Undefined for a fresh node;
+     *  identity/audit only. */
+    fork_from?: string | null;
     /** New subscriptions this node opens default to passive when true. */
     passive_default?: boolean;
     /** REVIVE-HOME — the tmux session a node is (re)opened into when it must
@@ -143,6 +160,8 @@ export interface NodeRow {
     lifecycle: Lifecycle;
     status: NodeStatus;
     cwd: string;
+    /** Which HOST launches + supervises this node; see NodeIdentity.host_kind. */
+    host_kind: 'tmux' | 'broker' | null;
     parent: string | null;
     created: string;
     /** Authoritative runtime columns (see NodeRuntime). */
@@ -188,3 +207,66 @@ export interface SubscriptionRef {
     active: boolean;
     created: string;
 }
+/** The four firing actions a wakeup can carry (design §4):
+ *  - bare     → revive the target node directly (resume:false), no inbox entry.
+ *  - noted    → deliver a note to the target's inbox (normal tier).
+ *  - deadline → deliver a timeout note to the target's inbox (urgent tier); ≤1 per node.
+ *  - spawn    → spawnChild a fresh node from a stored recipe (detached, node_id NULL). */
+export type WakeKind = 'bare' | 'noted' | 'deadline' | 'spawn';
+/** payload for a `bare` wake — `null`, or a label carried only for list rendering. */
+export interface BareWakePayload {
+    label?: string;
+}
+/** payload for a `noted` wake — a non-empty note body + a ≤120-char first-line label. */
+export interface NotedWakePayload {
+    body: string;
+    label: string;
+}
+/** payload for a `deadline` wake — a non-empty timeout note + the machine-readable
+ *  `timeout` mirror. The VISIBLE timeout signal rides the RENDERED label/body, not
+ *  this flag (inbox digests never surface arbitrary data keys). ≤1 per node. */
+export interface DeadlineWakePayload {
+    body: string;
+    timeout: true;
+    label: string;
+}
+/** The parsed per-kind payload union (Maj-1): the data-access layer JSON.stringifies
+ *  this on write and JSON.parses it back on read, so callers consume `payload.body`
+ *  / `payload as SpawnChildOpts` directly with no re-parse. A `spawn` payload is a
+ *  SpawnChildOpts recipe with `parent` resolved to a NON-NULL armer id at arm time. */
+export type WakePayload = null | BareWakePayload | NotedWakePayload | DeadlineWakePayload | SpawnChildOpts;
+/** A wakeup row as stored in the `wakeups` table (canvas.db, migration v7). One row =
+ *  "do <kind> at fire_at [every recur]". `node_id` is the revive TARGET + node-anchored
+ *  cancel anchor (NULL = canvas-detached); `owner_id` is the ARMER (set on every row).
+ *  `payload` is the PARSED per-kind union, never the raw JSON string (Maj-1). */
+export interface Wakeup {
+    /** Stable id (caller-supplied at arm time, minted as `wk-${newNodeId()}`). */
+    wakeup_id: string;
+    /** Revive target + node-anchored cancel anchor; NULL = canvas-detached (spawn). */
+    node_id: string | null;
+    /** The node that armed this wake; set on EVERY row. == node_id for a self-alarm. */
+    owner_id: string;
+    /** Next absolute fire time, ISO 8601 UTC; lexicographic <= compare. */
+    fire_at: string;
+    kind: WakeKind;
+    /** NULL = one-shot/adaptive; else the recur JSON the daemon advances. */
+    recur: string | null;
+    /** Parsed per-kind payload (NULL for a bare one-shot with no label). */
+    payload: WakePayload;
+    /** ISO 8601, audit/order. */
+    created: string;
+}
+/** The arm-a-wake spec (the pinned shared contract). `wakeup_id` is CALLER-SUPPLIED —
+ *  the canvas layer never mints ids (importing newNodeId from runtime/nodes.ts would
+ *  force a canvas → runtime → canvas cycle, Min-1); the command surface mints
+ *  `wk-${newNodeId()}` and passes it in. `owner_id` is required on every row;
+ *  `node_id` is NULL for a detached wake (deferred spawn / spawn-cron). */
+export interface ArmWakeSpec {
+    wakeup_id: string;
+    node_id?: string | null;
+    owner_id: string;
+    fire_at: string;
+    kind: WakeKind;
+    recur?: string | null;
+    payload?: WakePayload;
+}

package/dist/core/canvas/types.js

@@ -1,7 +1,7 @@
 // The canvas vocabulary — the node + edge model the whole runtime hangs on.
 //
-// One global canvas (`~/.crtr/canvas.db`) holds the topology (nodes + edges);
-// each node's flesh lives on disk under `~/.crtr/nodes/<id>/`. A node's
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the topology (nodes +
+// edges); each node's flesh lives on disk under `~/.crouter/canvas/nodes/<id>/`. A node's
 // `meta.json` is the source of truth for its own row; the db is a queryable
 // index over those metas, plus the authoritative store for the mutable
 // `subscribes_to` edges (which no single meta owns).

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

@@ -0,0 +1,76 @@
+import type { ArmWakeSpec, Wakeup } from './types.js';
+/** A thrown integrity-backstop error from armWake. `code` is the AC-N3 code the
+ *  command surface (the ONLY sanctioned caller of armWake) maps to a rendered
+ *  error block — armWake carries integrity backstops only (empty body / recur-on-
+ *  deadline / unknown kind); target-resolvability + recoverable-state + the
+ *  per-owner cap live in the surface (Min-6), so a non-surface armer could insert
+ *  a dangling wake — every armer MUST route through the surface. */
+export declare class WakeArmError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Which wakes a listWakes call returns. Distinguished by which key is present
+ *  (mirrors listNodes' filter shape):
+ *   - { node }    — wakes anchored to this node (node_id = ?).
+ *   - { owner }   — wakes this node ARMED (owner_id = ?); the per-owner cap count.
+ *   - { subtree } — wakes anchored to any node in this id set (node_id IN (…)).
+ *   - { due }     — wakes whose fire_at <= this ISO instant.
+ *   - { canvas }  — every wake on the canvas. */
+export type WakeScope = {
+    node: string;
+} | {
+    owner: string;
+} | {
+    subtree: string[];
+} | {
+    due: string;
+} | {
+    canvas: true;
+};
+/** INSERT one wakeup row from the pinned spec, returning its (caller-supplied)
+ *  `wakeup_id`. JSON.stringifies the typed `payload` union into the TEXT column
+ *  and stamps `created`.
+ *
+ *  Deadline upsert (design Q3, "≤1 deadline per node"): for `kind === 'deadline'`
+ *  the node's existing deadline is canceled first, then the new one inserted — the
+ *  partial unique index `idx_wakeups_deadline` is the schema-level backstop.
+ *
+ *  Integrity backstops (throw WakeArmError; the surface maps the code to AC-N3):
+ *   - empty/whitespace note `body` for `noted`/`deadline` → `empty_note`.
+ *   - non-NULL `recur` on a `deadline`                    → `deadline_cannot_recur`.
+ *   - unknown `kind`                                      → `bad_kind`.
+ *  NO target-resolvability / recoverable-state / cap backstop here (Min-6). */
+export declare function armWake(spec: ArmWakeSpec): string;
+/** UPDATE the next fire time — recurrence advancement (the daemon settles a
+ *  recurring row to its next slot BEFORE enacting, crash-safe; design D4). */
+export declare function advanceWake(wakeup_id: string, nextFireIso: string): void;
+/** DELETE one wakeup by id — one-shot consumption (the daemon settles a one-shot
+ *  row BEFORE enacting, crash-safe; design D4). */
+export declare function consumeWake(wakeup_id: string): void;
+/** DELETE one wakeup by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error (AC-C2). */
+export declare function cancelWake(wakeup_id: string): void;
+/** DELETE every wake anchored to this node AND every detached wake it ARMED —
+ *  deliberate close/reap (ruling A). Hooked at transition('cancel'). */
+export declare function cancelWakesFor(node_id: string): void;
+/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored crons
+ *  SURVIVE — finalize is the instance finishing, not a teardown of standing
+ *  schedules (design Q1). Hooked at transition('finalize'). */
+export declare function cancelSelfAlarms(node_id: string): void;
+/** DELETE this node's pending deadline(s) — cancel-on-wake (design §6.4).
+ *  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: every row whose fire_at has arrived, in
+ *  fire_at order, with `payload` parsed into the typed union. Returns exactly ONE
+ *  row per recurring wake regardless of missed slots — coalescing is structural
+ *  (AC-E2). */
+export declare function dueWakes(nowIso: string): Wakeup[];
+/** List wakes for a scope (node / owner / subtree / due / canvas), `payload`
+ *  parsed as in dueWakes. The subtree variant binds the id set with `?`
+ *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN spot);
+ *  ids are NEVER string-concatenated (Min-10). */
+export declare function listWakes(scope: WakeScope): Wakeup[];
+/** True if the node has ANY pending self-anchored wake (of any kind). Consumed by
+ *  the stop-guard self-wake seam so a no-child poll node releases dormant after
+ *  arming instead of being nagged to finish (AC-X3/AC-R1). */
+export declare function hasPendingSelfWake(node_id: string): boolean;