@crouton-kit/crouter 0.3.18 → 0.3.19

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/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;

package/dist/core/canvas/wakeups.js

@@ -0,0 +1,185 @@
+// wakeups.ts — the WAKEUPS table data-access layer (canvas.db, migration v7).
+//
+// One-module-per-table (the focuses.ts precedent): ALL SQL that touches the
+// `wakeups` table lives HERE and nowhere else — never appended to canvas.ts,
+// which keeps the node/edge model. A WAKEUP is one durable row = "do <kind> at
+// fire_at [every recur]", carrying a fire time, a kind, an optional payload, an
+// optional recurrence cadence, a nullable TARGET node_id, and the owner_id of
+// the node that ARMED it.
+//
+// Two anchors, two reap rules (design D1/D2):
+//   - node_id  → the revive target AND the node-anchored cancel anchor; it
+//     carries the `ON DELETE CASCADE` FK, so a pruned node's node-anchored wakes
+//     are reaped FOR FREE in pruneNodes' same `DELETE FROM nodes` (canvas.ts is
+//     UNTOUCHED — the cascade does it; there is no pruneNodes wakeups code).
+//     NULL = canvas-detached (a deferred spawn / spawn-cron).
+//   - owner_id → the armer; a PLAIN indexed column with NO FK, so a crashed-
+//     then-pruned armer's detached cron is NOT cascade-dropped (Invariant E).
+//     Reaped only by the explicit cancelWakesFor DELETE on deliberate close.
+//
+// Each function is a single-statement query mirroring the canvas.ts atomic-setter
+// pattern (setStatus/setIntent/setPresence) — no read-modify-write, serialized by
+// WAL. The data-access layer OWNS payload serialization: armWake JSON.stringifies
+// the typed per-kind union on write; dueWakes/listWakes JSON.parse it back on read
+// (Maj-1), so callers consume `payload.body` / `payload as SpawnChildOpts` directly.
+//
+// `wakeup_id` is CALLER-SUPPLIED (the command surface mints `wk-${newNodeId()}`):
+// the canvas layer never imports newNodeId from runtime/nodes.ts — that would
+// force a canvas → runtime → canvas import cycle (Min-1).
+import { openDb } from './db.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 class WakeArmError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WakeArmError';
+    }
+}
+/** Hydrate a raw row into a Wakeup, JSON.parsing `payload` back into the typed
+ *  per-kind union (NULL column → null). */
+function wakeupFrom(r) {
+    const raw = r['payload'];
+    return {
+        wakeup_id: r['wakeup_id'],
+        node_id: r['node_id'] ?? null,
+        owner_id: r['owner_id'],
+        fire_at: r['fire_at'],
+        kind: r['kind'],
+        recur: r['recur'] ?? null,
+        payload: raw == null ? null : JSON.parse(raw),
+        created: r['created'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Writes — each a single-statement INSERT/UPDATE/DELETE.
+// ---------------------------------------------------------------------------
+/** 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 function armWake(spec) {
+    const { kind } = spec;
+    if (kind !== 'bare' && kind !== 'noted' && kind !== 'deadline' && kind !== 'spawn') {
+        throw new WakeArmError('bad_kind', `unknown wake kind: ${String(kind)}`);
+    }
+    if (kind === 'noted' || kind === 'deadline') {
+        const body = spec.payload?.body;
+        if (typeof body !== 'string' || body.trim() === '') {
+            throw new WakeArmError('empty_note', `a ${kind} wake requires a non-empty note body.`);
+        }
+    }
+    if (kind === 'deadline' && spec.recur != null) {
+        throw new WakeArmError('deadline_cannot_recur', 'a deadline wake cannot recur.');
+    }
+    // Deadline upsert: clear the node's existing deadline before inserting the new one.
+    if (kind === 'deadline' && spec.node_id != null) {
+        cancelDeadlinesFor(spec.node_id);
+    }
+    const payloadText = spec.payload == null ? null : JSON.stringify(spec.payload);
+    openDb()
+        .prepare(`INSERT INTO wakeups (wakeup_id, node_id, owner_id, fire_at, kind, recur, payload, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.wakeup_id, spec.node_id ?? null, spec.owner_id, spec.fire_at, kind, spec.recur ?? null, payloadText, new Date().toISOString());
+    return spec.wakeup_id;
+}
+/** UPDATE the next fire time — recurrence advancement (the daemon settles a
+ *  recurring row to its next slot BEFORE enacting, crash-safe; design D4). */
+export function advanceWake(wakeup_id, nextFireIso) {
+    openDb().prepare('UPDATE wakeups SET fire_at = ? WHERE wakeup_id = ?').run(nextFireIso, wakeup_id);
+}
+/** DELETE one wakeup by id — one-shot consumption (the daemon settles a one-shot
+ *  row BEFORE enacting, crash-safe; design D4). */
+export function consumeWake(wakeup_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE wakeup_id = ?').run(wakeup_id);
+}
+/** DELETE one wakeup by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error (AC-C2). */
+export function cancelWake(wakeup_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE wakeup_id = ?').run(wakeup_id);
+}
+/** DELETE every wake anchored to this node AND every detached wake it ARMED —
+ *  deliberate close/reap (ruling A). Hooked at transition('cancel'). */
+export function cancelWakesFor(node_id) {
+    openDb()
+        .prepare('DELETE FROM wakeups WHERE node_id = ? OR owner_id = ?')
+        .run(node_id, node_id);
+}
+/** 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 function cancelSelfAlarms(node_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE node_id = ? AND recur IS NULL').run(node_id);
+}
+/** 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 function cancelDeadlinesFor(node_id) {
+    openDb().prepare("DELETE FROM wakeups WHERE node_id = ? AND kind = 'deadline'").run(node_id);
+}
+// ---------------------------------------------------------------------------
+// Reads.
+// ---------------------------------------------------------------------------
+/** 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 function dueWakes(nowIso) {
+    return openDb()
+        .prepare('SELECT * FROM wakeups WHERE fire_at <= ? ORDER BY fire_at')
+        .all(nowIso).map(wakeupFrom);
+}
+/** 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 function listWakes(scope) {
+    const db = openDb();
+    let rows;
+    if ('node' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE node_id = ? ORDER BY fire_at')
+            .all(scope.node);
+    }
+    else if ('owner' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE owner_id = ? ORDER BY fire_at')
+            .all(scope.owner);
+    }
+    else if ('subtree' in scope) {
+        if (scope.subtree.length === 0)
+            return [];
+        const placeholders = scope.subtree.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM wakeups WHERE node_id IN (${placeholders}) ORDER BY fire_at`)
+            .all(...scope.subtree);
+    }
+    else if ('due' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE fire_at <= ? ORDER BY fire_at')
+            .all(scope.due);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM wakeups ORDER BY fire_at').all();
+    }
+    return rows.map(wakeupFrom);
+}
+/** 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 function hasPendingSelfWake(node_id) {
+    return (openDb().prepare('SELECT 1 FROM wakeups WHERE node_id = ? LIMIT 1').get(node_id) !== undefined);
+}

package/dist/core/config.js

@@ -137,7 +137,10 @@ function mergeConfig(partial) {
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
-    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav };
+    // The merge drops unknown keys, so `headless` must be carried explicitly or it
+    // is lost on every read-modify-write of config.json.
+    const headless = typeof partial.headless === 'boolean' ? partial.headless : defaults.headless;
+    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav, headless };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);