@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/core/canvas/canvas.js

@@ -0,0 +1,210 @@
+// The canvas data-access layer. The one place that reads/writes the node+edge
+// model. Later phases (spawn, push, lifecycle, daemon) call only this.
+//
+// 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, writeFileSync, renameSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { openDb } from './db.js';
+import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from './paths.js';
+// ---------------------------------------------------------------------------
+// meta.json (source of truth)
+// ---------------------------------------------------------------------------
+function readMeta(nodeId) {
+    const p = nodeMetaPath(nodeId);
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function writeMeta(meta) {
+    const p = nodeMetaPath(meta.node_id);
+    const tmp = `${p}.tmp`;
+    writeFileSync(tmp, JSON.stringify(meta, null, 2));
+    renameSync(tmp, p);
+}
+// ---------------------------------------------------------------------------
+// row index (derived from meta)
+// ---------------------------------------------------------------------------
+function upsertRow(meta) {
+    openDb()
+        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, parent, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         lifecycle=excluded.lifecycle, status=excluded.status, cwd=excluded.cwd,
+         parent=excluded.parent`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.status, meta.cwd, meta.parent ?? null, meta.created);
+}
+function rowFrom(r) {
+    return {
+        node_id: r['node_id'],
+        name: r['name'],
+        kind: r['kind'],
+        mode: r['mode'],
+        lifecycle: r['lifecycle'],
+        status: r['status'],
+        cwd: r['cwd'],
+        parent: r['parent'] ?? null,
+        created: r['created'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Nodes
+// ---------------------------------------------------------------------------
+/** Create a node: scaffold its dirs, write meta.json, index the row. */
+export function createNode(meta) {
+    ensureHome();
+    ensureNodeDirs(meta.node_id);
+    writeMeta(meta);
+    upsertRow(meta);
+    return meta;
+}
+/** The canonical node record (from meta.json), or null if unknown. */
+export function getNode(nodeId) {
+    return readMeta(nodeId);
+}
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export function getRow(nodeId) {
+    const r = openDb()
+        .prepare('SELECT * FROM nodes WHERE node_id = ?')
+        .get(nodeId);
+    return r ? rowFrom(r) : null;
+}
+/** Merge a patch into a node's meta.json and re-index its row. */
+export function updateNode(nodeId, patch) {
+    const cur = readMeta(nodeId);
+    if (!cur)
+        throw new Error(`unknown node: ${nodeId}`);
+    const next = { ...cur, ...patch, node_id: cur.node_id };
+    writeMeta(next);
+    upsertRow(next);
+    return next;
+}
+/** Convenience for the most common mutation. */
+export function setStatus(nodeId, status) {
+    updateNode(nodeId, { status });
+}
+/** All rows, optionally filtered by status. */
+export function listNodes(filter) {
+    const db = openDb();
+    let rows;
+    if (filter?.status !== undefined) {
+        const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+        const placeholders = statuses.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM nodes WHERE status IN (${placeholders}) ORDER BY created`)
+            .all(...statuses);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM nodes ORDER BY created').all();
+    }
+    return rows.map(rowFrom);
+}
+// ---------------------------------------------------------------------------
+// Edges
+// ---------------------------------------------------------------------------
+function addEdge(type, from, to, active) {
+    openDb()
+        .prepare(`INSERT INTO edges (type, from_id, to_id, active, created)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(type, from_id, to_id) DO UPDATE SET active=excluded.active`)
+        .run(type, from, to, active ? 1 : 0, new Date().toISOString());
+}
+/** Record `A subscribes_to B` — A receives B's output. active=true wakes A on
+ *  emit; passive accumulates pointers without a wake. Mutable; callable by anyone. */
+export function subscribe(subscriber, publisher, active = true) {
+    addEdge('subscribes_to', subscriber, publisher, active);
+}
+/** Drop a subscription edge. */
+export function unsubscribe(subscriber, publisher) {
+    openDb()
+        .prepare('DELETE FROM edges WHERE type = ? AND from_id = ? AND to_id = ?')
+        .run('subscribes_to', subscriber, publisher);
+}
+/** Flip an existing subscription's wake behavior. */
+export function setSubscriptionActive(subscriber, publisher, active) {
+    openDb()
+        .prepare('UPDATE edges SET active = ? WHERE type = ? AND from_id = ? AND to_id = ?')
+        .run(active ? 1 : 0, 'subscribes_to', subscriber, publisher);
+}
+/** Record the audit-only `child spawned_by parent` edge. */
+export function recordSpawn(child, parent) {
+    addEdge('spawned_by', child, parent, true);
+}
+/** Who subscribes to `publisher` — the targets a push fans out to. */
+export function subscribersOf(publisher) {
+    return openDb()
+        .prepare(`SELECT from_id AS node_id, active, created FROM edges
+         WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`)
+        .all(publisher).map((r) => ({
+        node_id: r['node_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+/** Who `subscriber` subscribes to — its reports / the nodes feeding it. */
+export function subscriptionsOf(subscriber) {
+    return openDb()
+        .prepare(`SELECT to_id AS node_id, active, created FROM edges
+         WHERE type = 'subscribes_to' AND from_id = ? ORDER BY created`)
+        .all(subscriber).map((r) => ({
+        node_id: r['node_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+// ---------------------------------------------------------------------------
+// Graph queries
+// ---------------------------------------------------------------------------
+/** A "view": every node whose output cascades up to `root` via subscriptions —
+ *  the subscription sub-DAG reachable downward (root → its reports → theirs …).
+ *  Returns ids excluding root, in BFS order. Cycle-safe. */
+export function view(root) {
+    const seen = new Set([root]);
+    const out = [];
+    const queue = subscriptionsOf(root).map((s) => s.node_id);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+        for (const s of subscriptionsOf(id)) {
+            if (!seen.has(s.node_id))
+                queue.push(s.node_id);
+        }
+    }
+    return out;
+}
+/** Stop-guard primitive: does this node hold an *active* subscription to a node
+ *  that's still live (active|idle) — i.e. something that can actually wake it?
+ *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
+export function hasActiveLiveSubscription(nodeId) {
+    const r = openDb()
+        .prepare(`SELECT 1 FROM edges e JOIN nodes n ON n.node_id = e.to_id
+       WHERE e.type = 'subscribes_to' AND e.from_id = ? AND e.active = 1
+         AND n.status IN ('active', 'idle') LIMIT 1`)
+        .get(nodeId);
+    return r !== undefined;
+}
+// ---------------------------------------------------------------------------
+// Index rebuild
+// ---------------------------------------------------------------------------
+/** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
+ *  re-derived from each meta's `parent`. */
+export function rebuildIndex() {
+    if (!existsSync(nodesRoot()))
+        return;
+    for (const id of readdirSync(nodesRoot())) {
+        if (!existsSync(join(nodeDir(id), 'meta.json')))
+            continue;
+        const meta = readMeta(id);
+        if (!meta)
+            continue;
+        upsertRow(meta);
+        if (meta.parent)
+            recordSpawn(meta.node_id, meta.parent);
+    }
+}

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

@@ -0,0 +1,7 @@
+import { DatabaseSync } from 'node:sqlite';
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
+ *  schema and WAL on first open. Keyed by path so tests with distinct homes get
+ *  independent handles. */
+export declare function openDb(): DatabaseSync;
+/** 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,61 @@
+// canvas.db — the topology skeleton. sqlite in WAL mode so the many concurrent
+// writers a sisyphus-grade swarm produces don't contend on a single locked JSON.
+//
+// Node rows are a rebuildable index over each node's meta.json (the source of
+// truth). The `subscribes_to` edges are the one genuinely-mutable part no meta
+// owns, so the db is authoritative for them.
+import { DatabaseSync } from 'node:sqlite';
+import { canvasDbPath, ensureHome } from './paths.js';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id    TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  kind       TEXT NOT NULL,
+  mode       TEXT NOT NULL DEFAULT 'base',
+  lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+  status     TEXT NOT NULL DEFAULT 'active',
+  cwd        TEXT NOT NULL,
+  parent     TEXT,
+  created    TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  type     TEXT NOT NULL,           -- 'subscribes_to' | 'spawned_by'
+  from_id  TEXT NOT NULL,
+  to_id    TEXT NOT NULL,
+  active   INTEGER NOT NULL DEFAULT 1,
+  created  TEXT NOT NULL,
+  PRIMARY KEY (type, from_id, to_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status);
+`;
+const handles = new Map();
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
+ *  schema and WAL on first open. Keyed by path so tests with distinct homes get
+ *  independent handles. */
+export function openDb() {
+    const path = canvasDbPath();
+    const existing = handles.get(path);
+    if (existing)
+        return existing;
+    ensureHome();
+    const db = new DatabaseSync(path);
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    db.exec('PRAGMA busy_timeout = 5000;');
+    db.exec(SCHEMA);
+    handles.set(path, db);
+    return db;
+}
+/** Close and forget the handle for the current home. Mainly for tests. */
+export function closeDb() {
+    const path = canvasDbPath();
+    const db = handles.get(path);
+    if (db) {
+        db.close();
+        handles.delete(path);
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './paths.js';
+export * from './canvas.js';
+export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

@@ -0,0 +1,6 @@
+// The canvas: one global graph of nodes + edges. Phase 0 of the pi-native
+// agent runtime. Topology in sqlite (WAL), node flesh on disk.
+export * from './types.js';
+export * from './paths.js';
+export * from './canvas.js';
+export { openDb, closeDb } from './db.js';

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

@@ -0,0 +1,16 @@
+/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+export declare function crtrHome(): string;
+export declare function canvasDbPath(): string;
+export declare function nodesRoot(): string;
+export declare function nodeDir(nodeId: string): string;
+export declare function contextDir(nodeId: string): string;
+export declare function jobDir(nodeId: string): string;
+export declare function reportsDir(nodeId: string): string;
+export declare function nodeMetaPath(nodeId: string): string;
+export declare function inboxPath(nodeId: string): string;
+export declare function transcriptPath(nodeId: string): string;
+export declare function sessionPtrPath(nodeId: string): string;
+/** Create the full directory skeleton for a node. Idempotent. */
+export declare function ensureNodeDirs(nodeId: string): void;
+/** Ensure the canvas home exists. Idempotent. */
+export declare function ensureHome(): void;

package/dist/core/canvas/paths.js

@@ -0,0 +1,62 @@
+// The `~/.crtr/` layout. One global, cwd-agnostic home for the whole canvas.
+//
+//   ~/.crtr/
+//     canvas.db                 sqlite (WAL) — topology only (nodes + edges)
+//     nodes/<node_id>/
+//       meta.json               source of truth for the node's row
+//       context/                roadmap.md, initial-prompt.md, explore-*.md, artifacts
+//       job/                    log.jsonl, telemetry.json
+//       reports/                append-only push history (<ts>-<kind>.md)
+//       inbox.jsonl             messages + coalesced subscription feed
+//       transcript.jsonl        mirror/pointer of the pi session
+//       session.ptr             pi session id/path
+//
+// `CRTR_HOME` overrides the root (used by tests and isolated runs).
+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). */
+export function crtrHome() {
+    const override = process.env['CRTR_HOME'];
+    return override !== undefined && override !== '' ? override : join(homedir(), '.crtr');
+}
+export function canvasDbPath() {
+    return join(crtrHome(), 'canvas.db');
+}
+export function nodesRoot() {
+    return join(crtrHome(), 'nodes');
+}
+export function nodeDir(nodeId) {
+    return join(nodesRoot(), nodeId);
+}
+export function contextDir(nodeId) {
+    return join(nodeDir(nodeId), 'context');
+}
+export function jobDir(nodeId) {
+    return join(nodeDir(nodeId), 'job');
+}
+export function reportsDir(nodeId) {
+    return join(nodeDir(nodeId), 'reports');
+}
+export function nodeMetaPath(nodeId) {
+    return join(nodeDir(nodeId), 'meta.json');
+}
+export function inboxPath(nodeId) {
+    return join(nodeDir(nodeId), 'inbox.jsonl');
+}
+export function transcriptPath(nodeId) {
+    return join(nodeDir(nodeId), 'transcript.jsonl');
+}
+export function sessionPtrPath(nodeId) {
+    return join(nodeDir(nodeId), 'session.ptr');
+}
+/** Create the full directory skeleton for a node. Idempotent. */
+export function ensureNodeDirs(nodeId) {
+    for (const d of [contextDir(nodeId), jobDir(nodeId), reportsDir(nodeId)]) {
+        mkdirSync(d, { recursive: true });
+    }
+}
+/** Ensure the canvas home exists. Idempotent. */
+export function ensureHome() {
+    mkdirSync(nodesRoot(), { recursive: true });
+}

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

@@ -0,0 +1,30 @@
+import type { NodeStatus } 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.
+ *
+ * Each line: `<glyph> <name> [<kind>/<mode>] ctx <Nk>[ ⚑<asks>]`
+ *
+ * Returns a multi-line string (no trailing newline).
+ */
+export declare function renderTree(rootId: string): string;
+/**
+ * Render all canvas roots as a forest. A root is a node with no subscribers
+ * (no one subscribes to it = it has no managers in the org chart).
+ *
+ * If there are no roots on the canvas, returns a placeholder string.
+ */
+export declare function renderForest(): string;
+export interface DashboardRow {
+    node_id: string;
+    name: string;
+    status: NodeStatus;
+    kind: string;
+    mode: string;
+    ctx_tokens: number;
+    asks: number;
+}
+/** One row per node visible in the sub-DAG of `rootId` (including root). */
+export declare function dashboardRows(rootId: string): DashboardRow[];
+/** One row per node across the entire canvas. */
+export declare function dashboardRowsAll(): DashboardRow[];

package/dist/core/canvas/render.js

@@ -0,0 +1,186 @@
+// render.ts — ASCII tree rendering of the canvas subscription sub-DAG.
+//
+// `subscriptionsOf(nodeId)` returns the nodes a node subscribes to, which in
+// the crtr model are its *reports* / *children*: a parent auto-subscribes to
+// each child it spawns so it wakes on the child's output. Walking subscriptionsOf
+// recursively therefore walks DOWN the org chart.
+//
+// Telemetry is read directly from <crtrHome>/nodes/<id>/job/telemetry.json
+// (the node-local job dir written by canvas-stophook on every turn_end).
+// Missing or corrupt telemetry → ctx 0k (best-effort, never throws).
+//
+// Cycle guard: the subscription graph is declared acyclic (a node cannot
+// subscribe to its own ancestor), but we track visited ids defensively because
+// the db is mutable and bugs happen.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
+import { jobDir } from './paths.js';
+import { countAsks } from './attention.js';
+// ---------------------------------------------------------------------------
+// Glyphs
+// ---------------------------------------------------------------------------
+const STATUS_GLYPH = {
+    active: '●',
+    idle: '○',
+    done: '✓',
+    dead: '✗',
+};
+function readNodeTelemetry(nodeId) {
+    const path = join(jobDir(nodeId), 'telemetry.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Format a token count as `Nk` (rounded down to nearest 1 k). */
+function fmtCtx(tokensIn) {
+    if (tokensIn === undefined || tokensIn === 0)
+        return '0k';
+    return `${Math.floor(tokensIn / 1000)}k`;
+}
+// ---------------------------------------------------------------------------
+// Tree builder
+// ---------------------------------------------------------------------------
+/** Build one line of the ASCII tree. */
+function nodeLine(nodeId, indent, connector) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        // Node id is in the db but meta.json is gone — paranoid guard.
+        return `${indent}${connector}? <missing meta: ${nodeId}>`;
+    }
+    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    const tel = readNodeTelemetry(nodeId);
+    const ctx = fmtCtx(tel.tokens_in);
+    const asks = countAsks(nodeId);
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    return `${indent}${connector}${glyph} ${node.name} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`;
+}
+/**
+ * Recursively walk the subscription sub-DAG rooted at `nodeId`, appending
+ * rendered lines to `out`. Cycle-safe via `visited`.
+ */
+function walkTree(nodeId, indent, isLast, visited, out) {
+    // Guard: if we have already rendered this node in this traversal, emit a
+    // back-ref marker instead of recursing (prevents infinite loops in graphs
+    // with cycles introduced by manual edge manipulation).
+    if (visited.has(nodeId)) {
+        // The line for this node was already emitted by the caller; just return.
+        return;
+    }
+    visited.add(nodeId);
+    const connector = isLast ? '└─ ' : '├─ ';
+    out.push(nodeLine(nodeId, indent, connector));
+    const children = subscriptionsOf(nodeId);
+    const childIndent = indent + (isLast ? '   ' : '│  ');
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childIsLast = i === children.length - 1;
+        if (visited.has(child.node_id)) {
+            // Cycle reference — show the back-edge without recursing.
+            const cycleConnector = childIsLast ? '└─ ' : '├─ ';
+            out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
+            continue;
+        }
+        walkTree(child.node_id, childIndent, childIsLast, visited, out);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Render the subscription sub-DAG rooted at `rootId` as an ASCII tree.
+ * The root is the first line (no connector prefix); children are indented.
+ *
+ * Each line: `<glyph> <name> [<kind>/<mode>] ctx <Nk>[ ⚑<asks>]`
+ *
+ * Returns a multi-line string (no trailing newline).
+ */
+export function renderTree(rootId) {
+    const node = getNode(rootId);
+    if (node === null)
+        return `? <missing node: ${rootId}>`;
+    const tel = readNodeTelemetry(rootId);
+    const ctx = fmtCtx(tel.tokens_in);
+    const asks = countAsks(rootId);
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    const out = [];
+    out.push(`${glyph} ${node.name} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`);
+    // visited starts with root already rendered (walkTree doesn't re-emit root).
+    const visited = new Set([rootId]);
+    const children = subscriptionsOf(rootId);
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const isLast = i === children.length - 1;
+        walkTree(child.node_id, '', isLast, visited, out);
+    }
+    return out.join('\n');
+}
+/**
+ * Render all canvas roots as a forest. A root is a node with no subscribers
+ * (no one subscribes to it = it has no managers in the org chart).
+ *
+ * If there are no roots on the canvas, returns a placeholder string.
+ */
+export function renderForest() {
+    const all = listNodes();
+    if (all.length === 0)
+        return '(canvas is empty)';
+    // A root has no subscribers (nobody is watching it). We discover this by
+    // looking for nodes whose node_id never appears as a "to" side of a
+    // subscribes_to edge — equivalently, nodes with parent === null are the
+    // authoritative roots per the spawn contract (spawn sets parent and records
+    // a spawned_by edge + subscribe). Fall back to parent===null because querying
+    // the full edge table would require opening the db here.
+    //
+    // Fine to use parent===null: roots are created by `node session` / `node new`
+    // without a parent; non-roots always have a parent.
+    const roots = all.filter((n) => n.parent === null);
+    // If for some reason we have no parent===null nodes (unusual: e.g., all nodes
+    // were created by hand with a parent), fall back to all nodes.
+    const renderRoots = roots.length > 0 ? roots : all;
+    const parts = [];
+    for (const r of renderRoots) {
+        parts.push(renderTree(r.node_id));
+    }
+    return parts.join('\n\n');
+}
+/** One row per node visible in the sub-DAG of `rootId` (including root). */
+export function dashboardRows(rootId) {
+    const ids = [rootId, ...view(rootId)];
+    return ids.flatMap((id) => {
+        const node = getNode(id);
+        if (node === null)
+            return [];
+        const tel = readNodeTelemetry(id);
+        return [{
+                node_id: id,
+                name: node.name,
+                status: node.status,
+                kind: node.kind,
+                mode: node.mode,
+                ctx_tokens: tel.tokens_in ?? 0,
+                asks: countAsks(id),
+            }];
+    });
+}
+/** One row per node across the entire canvas. */
+export function dashboardRowsAll() {
+    return listNodes().flatMap((row) => {
+        const tel = readNodeTelemetry(row.node_id);
+        return [{
+                node_id: row.node_id,
+                name: row.name,
+                status: row.status,
+                kind: row.kind,
+                mode: row.mode,
+                ctx_tokens: tel.tokens_in ?? 0,
+                asks: countAsks(row.node_id),
+            }];
+    });
+}

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

@@ -0,0 +1,87 @@
+/** What a node is doing right now. UI shows active+idle; `done` is hidden but
+ *  revivable; only `dead` is a fault. */
+export type NodeStatus = 'active' | 'idle' | 'done' | 'dead';
+/** Does stopping finalize the node? terminal = worker (finalizes on push --final);
+ *  resident = manager/orchestrator (stays dormant, woken by inbox). */
+export type Lifecycle = 'terminal' | 'resident';
+/** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
+export type Mode = 'base' | 'orchestrator';
+/** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
+export type ExitIntent = 'done' | 'refresh' | 'idle-release' | null;
+/** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
+ *  org chart, views, completion routing). `spawned_by` is audit only. */
+export type EdgeType = 'subscribes_to' | 'spawned_by';
+/** The pi launch recipe, persisted so the daemon can faithfully revive a node
+ *  as its *current* self. Rewritten on every polymorph (base→orchestrator). */
+export interface LaunchSpec {
+    /** Model id/pattern passed to pi `--model`. */
+    model?: string;
+    /** pi `--tools` allow-list. */
+    tools?: string[];
+    /** pi `-e` extension paths, loaded once; they self-gate on live {kind,mode}. */
+    extensions: string[];
+    /** Resolved system prompt text (passed via --append-system-prompt / --system-prompt). */
+    systemPrompt?: string;
+    /** Extra env injected into the pi process. */
+    env: Record<string, string>;
+}
+/** A node's `meta.json` — source of truth for its canvas row. Files for flesh,
+ *  sqlite for skeleton: the db indexes the queryable subset of these fields. */
+export interface NodeMeta {
+    node_id: string;
+    name: string;
+    created: string;
+    /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
+    cwd: string;
+    /** Role the node was born as: explore | developer | plan | review | general… */
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    /** spawned_by target — who created me. Audit only; null for user-opened roots. */
+    parent?: string | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passive_default?: boolean;
+    /** Why the node last stopped (done | refresh). Drives reap-vs-revive. */
+    intent?: ExitIntent;
+    /** The pi session id for `--resume`. */
+    pi_session_id?: string | null;
+    /** Full pi launch recipe; rewritten on every polymorph. */
+    launch?: LaunchSpec;
+    /** Presence: the tmux session (its root's home) and window this node renders
+     *  in while active. Cleared when the node goes done/dead and its window closes.
+     *  (Phase 5 promotes this to a dedicated presence registry.) */
+    tmux_session?: string | null;
+    window?: string | null;
+}
+/** The queryable projection of a NodeMeta stored as a canvas.db row. */
+export interface NodeRow {
+    node_id: string;
+    name: string;
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    cwd: string;
+    parent: string | null;
+    created: string;
+}
+/** An edge as stored. For `subscribes_to`, `from` is the subscriber and `to`
+ *  is the publisher (A subscribes_to B ⇒ A receives B's output). For
+ *  `spawned_by`, `from` is the child and `to` is the parent. */
+export interface Edge {
+    type: EdgeType;
+    from: string;
+    to: string;
+    /** Only meaningful for subscribes_to: active = wake the subscriber on emit;
+     *  passive = accumulate pointers, no wake. */
+    active: boolean;
+    created: string;
+}
+/** A subscription as seen from one endpoint. */
+export interface SubscriptionRef {
+    /** The node id at the other end of the edge. */
+    node_id: string;
+    active: boolean;
+    created: string;
+}