@north-light/api 0.3.580 → 0.3.588

package/dist/core/canvas/install-id.js

@@ -0,0 +1,64 @@
+// install-id.ts — the canvas-install id: a stable identity for the canvas
+// home itself, get-or-created once and stamped onto every node id minted
+// after (see the unified-chat/addressing design's "ID scheme"). Stored in the
+// `canvas_meta` k/v table (migration v10, see db.ts) alongside the boot
+// marker (boot.ts), written under `withCanvasWrite`.
+//
+// Resolution order: the stored value always wins; else `CRTR_INSTALL_ID` env
+// (format-validated, then persisted); else a fresh self-minted 8-char
+// lowercase base36 random id (persisted). A stored value that CONFLICTS with
+// a DIFFERENT injected env value is a loud hard failure at daemon boot — that
+// combination means this process is pointed at the wrong canvas
+// volume/home, and silently trusting the stored value would mask the bug.
+// The same env value as already stored is a no-op (expected: a redeploy
+// re-passes the same env on every recreate).
+import { randomBytes } from 'node:crypto';
+import { withCanvasWrite } from './db.js';
+const INSTALL_ID_KEY = 'install_id';
+const INSTALL_ID_SHAPE = /^[a-z0-9]{4,16}$/;
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+/** 4-16 lowercase [a-z0-9] characters — the shape both an env-supplied and a
+ *  self-minted install id must satisfy. */
+export function isValidInstallId(id) {
+    return INSTALL_ID_SHAPE.test(id);
+}
+function mintInstallId() {
+    const bytes = randomBytes(8);
+    let out = '';
+    for (let i = 0; i < 8; i++)
+        out += ALPHABET[bytes[i] % ALPHABET.length];
+    return out;
+}
+async function readInstallId(db) {
+    const row = await db.prepare('SELECT value FROM canvas_meta WHERE key = ?').get(INSTALL_ID_KEY);
+    return row?.value ?? null;
+}
+async function writeInstallId(db, id) {
+    await db.prepare('INSERT INTO canvas_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(INSTALL_ID_KEY, id);
+}
+/** Get-or-create the canvas-install id every minted node id embeds. Called
+ *  once at daemon boot (`crtrd.ts`) — a thrown error there fails boot loudly,
+ *  which is the intended behavior for both an invalid env value and a
+ *  stored/env mismatch. Runs in the caller's canvas write transaction when
+ *  one is open, else its own. `env` is injectable for tests. */
+export async function resolveInstallId(env = process.env) {
+    return await withCanvasWrite(async (db) => {
+        const stored = await readInstallId(db);
+        const injectedRaw = env['CRTR_INSTALL_ID'];
+        const injected = injectedRaw !== undefined && injectedRaw !== '' ? injectedRaw : null;
+        if (stored !== null) {
+            if (injected !== null && injected !== stored) {
+                throw new Error(`CRTR_INSTALL_ID='${injected}' conflicts with the install id already persisted in this canvas home ` +
+                    `('${stored}'). This canvas home was minted under a different install id — refusing to boot rather ` +
+                    `than silently mask what is usually a provisioning bug (this process pointed at the wrong volume/home).`);
+            }
+            return stored;
+        }
+        if (injected !== null && !isValidInstallId(injected)) {
+            throw new Error(`CRTR_INSTALL_ID='${injected}' is not a valid install id — expected 4-16 lowercase [a-z0-9] characters.`);
+        }
+        const resolved = injected ?? mintInstallId();
+        await writeInstallId(db, resolved);
+        return resolved;
+    });
+}

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

@@ -0,0 +1,30 @@
+import type { Mode, NodeMeta } from './types.js';
+/** Nerd Font glyph for a node's mode in its persona badge. A base worker reads
+ *  as a single figure (nf-fa-user, U+F007); an orchestrator reads as a fan-out
+ *  hierarchy (nf-fa-sitemap, U+F0E8). */
+export declare function modeIcon(mode: Mode): string;
+/** The minimal shape `fullName` needs — satisfied by NodeMeta, by NodeRow, and
+ *  by anything else carrying name + kind (description optional). */
+export interface NamedNode {
+    name: string;
+    kind: string;
+    description?: string;
+    icon?: string;
+}
+/** A node's human label: its explicit handle plus the pi-generated description
+ *  of its first task, e.g. `fix-auth refactor-login-flow`. The handle is
+ *  dropped when it's just the kind default (non-informative, and the kind is
+ *  surfaced elsewhere), so a default-named node reads as its description alone
+ *  (`refactor-login-flow`). Falls back to the bare name when no description
+ *  exists yet (a node not yet named, e.g. a bare root before its first
+ *  message). Never empty. */
+export declare function fullName(node: NamedNode): string;
+/** The node's persona label, rendered in the attach editor's bottom-right
+ *  badge. */
+export declare function personaLabel(meta: Pick<NodeMeta, 'kind' | 'mode'>): string;
+/** The pi session display name — the editor label in the top-left. It carries
+ *  ONE name: a person's explicit handle when present, otherwise the generated
+ *  description of the node's first task. Unlike `fullName` it never prints
+ *  both, so the chip doesn't read as two names side by side. Persona lives in
+ *  the editor's bottom-right badge. Recomputed from meta on every revive. */
+export declare function editorLabel(meta: NodeMeta): string;

package/dist/core/canvas/labels.js

@@ -0,0 +1,43 @@
+// labels.ts — human-facing node labels derived from a node's meta.
+//
+// One source of truth for "what do we call this node on screen". `fullName`
+// combines the node's explicit handle (meta.name) with the pi-generated
+// description of its first task (meta.description) for canvas and tmux surfaces.
+// `editorLabel` keeps the editor chip compact by choosing the explicit handle
+// when a person supplied one, otherwise the generated description.
+/** Nerd Font glyph for a node's mode in its persona badge. A base worker reads
+ *  as a single figure (nf-fa-user, U+F007); an orchestrator reads as a fan-out
+ *  hierarchy (nf-fa-sitemap, U+F0E8). */
+export function modeIcon(mode) {
+    return mode === 'orchestrator' ? '\uf0e8' : '\uf007';
+}
+/** A node's human label: its explicit handle plus the pi-generated description
+ *  of its first task, e.g. `fix-auth refactor-login-flow`. The handle is
+ *  dropped when it's just the kind default (non-informative, and the kind is
+ *  surfaced elsewhere), so a default-named node reads as its description alone
+ *  (`refactor-login-flow`). Falls back to the bare name when no description
+ *  exists yet (a node not yet named, e.g. a bare root before its first
+ *  message). Never empty. */
+export function fullName(node) {
+    const desc = (node.description ?? '').trim();
+    const handle = node.name && node.name !== node.kind ? node.name : '';
+    const combined = [handle, desc].filter((s) => s !== '').join(' ');
+    return combined !== '' ? combined : node.name;
+}
+/** The node's persona label, rendered in the attach editor's bottom-right
+ *  badge. */
+export function personaLabel(meta) {
+    return `${modeIcon(meta.mode)} ${meta.kind}`;
+}
+/** The pi session display name — the editor label in the top-left. It carries
+ *  ONE name: a person's explicit handle when present, otherwise the generated
+ *  description of the node's first task. Unlike `fullName` it never prints
+ *  both, so the chip doesn't read as two names side by side. Persona lives in
+ *  the editor's bottom-right badge. Recomputed from meta on every revive. */
+export function editorLabel(meta) {
+    const icon = (meta.icon ?? '').trim();
+    const handle = meta.name && meta.name !== meta.kind ? meta.name.trim() : '';
+    const desc = (meta.description ?? '').trim();
+    const name = handle !== '' ? handle : desc !== '' ? desc : meta.name;
+    return icon !== '' ? `${icon} ${name}` : name;
+}

package/dist/core/canvas/legacy-person.d.ts

@@ -0,0 +1,4 @@
+/** The person principal every install carried before it minted its own: read only by the one-shot that retires it and by the legacy SQLite/layout importers. Pure so CLI-reachable modules can import it. */
+export declare const LEGACY_LOCAL_PERSON = "user:local";
+/** The id of the local terminal grant an install carried before its grant became `terminal:<install id>`; nodes, tokens, crons and queued births may still reference it. */
+export declare const LEGACY_LOCAL_TERMINAL_GRANT = "local:terminal";

package/dist/core/canvas/legacy-person.js

@@ -0,0 +1,4 @@
+/** The person principal every install carried before it minted its own: read only by the one-shot that retires it and by the legacy SQLite/layout importers. Pure so CLI-reachable modules can import it. */
+export const LEGACY_LOCAL_PERSON = 'user:local';
+/** The id of the local terminal grant an install carried before its grant became `terminal:<install id>`; nodes, tokens, crons and queued births may still reference it. */
+export const LEGACY_LOCAL_TERMINAL_GRANT = 'local:terminal';

package/dist/core/canvas/memory-reads.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryReadEventDTO } from '../../api/dto/analytics.js';
+import { type CanvasDb } from './db.js';
+/** Entries older than this are deleted by the hourly storage-maintenance pass. */
+export declare const MEMORY_READS_RETENTION_MS: number;
+export interface MemoryReadRow {
+    node_id: string;
+    name: string;
+    scope: string;
+    at: string;
+    type: 'read' | 'loaded';
+}
+/** Insert every event for one node in one transaction. `at` must already be a
+ *  canonical ISO UTC string (`Date#toISOString`) so range reads compare as text. */
+export declare function insertMemoryReads(nodeId: string, events: MemoryReadEventDTO[]): Promise<void>;
+/** Record events inside the caller's write transaction: the canvas-model
+ *  delivery (`loaded`) and explicit document read (`read`) sites call this so
+ *  the log lands with the exposures and watches it describes. */
+export declare function recordMemoryReadsIn(db: CanvasDb, nodeId: string, events: readonly MemoryReadEventDTO[]): Promise<void>;
+/** Entries with `fromIso <= at < toIso`, oldest first. */
+export declare function listMemoryReads(fromIso: string, toIso: string): Promise<MemoryReadRow[]>;
+/** Delete entries older than the retention window; returns the count deleted. */
+export declare function pruneMemoryReads(nowMs: number): Promise<number>;
+/** When recording began: the time the memory_reads migration ran. */
+export declare function memoryReadsStartedAt(): Promise<string | null>;

package/dist/core/canvas/memory-reads.js

@@ -0,0 +1,36 @@
+import { withCanvasWrite, openDb } from './db.js';
+/** Entries older than this are deleted by the hourly storage-maintenance pass. */
+export const MEMORY_READS_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Insert every event for one node in one transaction. `at` must already be a
+ *  canonical ISO UTC string (`Date#toISOString`) so range reads compare as text. */
+export async function insertMemoryReads(nodeId, events) {
+    await withCanvasWrite(async (db) => {
+        const insert = db.prepare('INSERT INTO memory_reads (node_id, name, scope, at, type) VALUES (?, ?, ?, ?, ?)');
+        for (const e of events)
+            await insert.run(nodeId, e.name, e.scope, e.at, e.type);
+    });
+}
+/** Record events inside the caller's write transaction: the canvas-model
+ *  delivery (`loaded`) and explicit document read (`read`) sites call this so
+ *  the log lands with the exposures and watches it describes. */
+export async function recordMemoryReadsIn(db, nodeId, events) {
+    if (events.length === 0)
+        return;
+    const insert = db.prepare('INSERT INTO memory_reads (node_id, name, scope, at, type) VALUES (?, ?, ?, ?, ?)');
+    for (const e of events)
+        await insert.run(nodeId, e.name, e.scope, e.at, e.type);
+}
+/** Entries with `fromIso <= at < toIso`, oldest first. */
+export async function listMemoryReads(fromIso, toIso) {
+    return await (await openDb()).prepare('SELECT node_id, name, scope, at, type FROM memory_reads WHERE at >= ? AND at < ? ORDER BY at')
+        .all(fromIso, toIso);
+}
+/** Delete entries older than the retention window; returns the count deleted. */
+export async function pruneMemoryReads(nowMs) {
+    return Number((await (await openDb()).prepare('DELETE FROM memory_reads WHERE at < ?').run(new Date(nowMs - MEMORY_READS_RETENTION_MS).toISOString())).changes);
+}
+/** When recording began: the time the memory_reads migration ran. */
+export async function memoryReadsStartedAt() {
+    const row = await (await openDb()).prepare("SELECT value FROM canvas_meta WHERE key = 'memory_reads.started_at'").get();
+    return row?.value ?? null;
+}

package/dist/core/canvas/meta-file.d.ts

@@ -0,0 +1,20 @@
+/** Read a metadata object, tolerating a missing/empty/corrupt file as `null`
+ *  (never throws). Callers that reindex/revive the whole canvas must not crash on
+ *  one damaged node. Read only while holding {@link withMetaLock} for any
+ *  read-modify-write that races other writers. */
+export declare function readMetaObject(path: string): Record<string, unknown> | null;
+/** Serialize every read-modify-write to one node's meta.json behind a single
+ *  cross-process lock, so a migration and a normal identity update can never
+ *  interleave into a lost write or a restored-legacy-prefix. The lock is NOT
+ *  re-entrant — the operation must use {@link writeMetaObjectLocked}, never the
+ *  lock-taking {@link writeJsonFileDurably}. */
+export declare function withMetaLock<T>(path: string, operation: () => T): T;
+/** Collision-free durable write (fsync file + parent dir), assuming the caller
+ *  already holds {@link withMetaLock} for `path`. */
+export declare function writeMetaObjectLocked(path: string, value: unknown): void;
+/** Serialize a normal identity write with migrations and use a collision-free durable temp file. */
+export declare function writeJsonFileDurably(path: string, value: unknown): void;
+/** Transform one metadata object in place while holding the same lock normal
+ *  writes honor. The transform MUTATES the passed object and returns whether it
+ *  changed anything; only a `true` return persists the mutated object. */
+export declare function updateJsonFileDurably(path: string, transform: (value: Record<string, unknown>) => boolean): boolean;

package/dist/core/canvas/meta-file.js

@@ -0,0 +1,89 @@
+// Durable node-meta file primitives shared by normal canvas writes and forward migrations.
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
+function parseObject(path, strict) {
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '') {
+        if (strict)
+            throw new Error(`cannot migrate unreadable node metadata: ${path}`);
+        return null;
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new Error('metadata must be an object');
+        return value;
+    }
+    catch (error) {
+        if (strict)
+            throw new Error(`cannot migrate unreadable node metadata: ${path} — ${error.message}`);
+        return null;
+    }
+}
+/** Read a metadata object, tolerating a missing/empty/corrupt file as `null`
+ *  (never throws). Callers that reindex/revive the whole canvas must not crash on
+ *  one damaged node. Read only while holding {@link withMetaLock} for any
+ *  read-modify-write that races other writers. */
+export function readMetaObject(path) {
+    return parseObject(path, false);
+}
+/** Serialize every read-modify-write to one node's meta.json behind a single
+ *  cross-process lock, so a migration and a normal identity update can never
+ *  interleave into a lost write or a restored-legacy-prefix. The lock is NOT
+ *  re-entrant — the operation must use {@link writeMetaObjectLocked}, never the
+ *  lock-taking {@link writeJsonFileDurably}. */
+export function withMetaLock(path, operation) {
+    return withExclusiveDirectoryLock(`${path}.lock`, operation, {
+        timeoutMs: 5_000,
+        timeoutError: () => new Error(`timed out waiting to write node metadata: ${path}`),
+    });
+}
+/** Collision-free durable write (fsync file + parent dir), assuming the caller
+ *  already holds {@link withMetaLock} for `path`. */
+export function writeMetaObjectLocked(path, value) {
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        const fd = openSync(tmp, 'w');
+        try {
+            writeSync(fd, JSON.stringify(value, null, 2));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+    const dirFd = openSync(dirname(path), 'r');
+    try {
+        fsyncSync(dirFd);
+    }
+    finally {
+        closeSync(dirFd);
+    }
+}
+/** Serialize a normal identity write with migrations and use a collision-free durable temp file. */
+export function writeJsonFileDurably(path, value) {
+    withMetaLock(path, () => writeMetaObjectLocked(path, value));
+}
+/** Transform one metadata object in place while holding the same lock normal
+ *  writes honor. The transform MUTATES the passed object and returns whether it
+ *  changed anything; only a `true` return persists the mutated object. */
+export function updateJsonFileDurably(path, transform) {
+    return withMetaLock(path, () => {
+        // Canvas-wide migrations must preserve rebuildIndex's corrupt-node isolation:
+        // one unreadable meta file is skipped rather than bricking every openDb().
+        const value = parseObject(path, false);
+        if (value === null || !transform(value))
+            return false;
+        writeMetaObjectLocked(path, value);
+        return true;
+    });
+}

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

@@ -0,0 +1,136 @@
+import type { Fault } from '../fault-classifier.js';
+import type { NodeStatus } from './types.js';
+/** The node fields these helpers display — satisfied by `NodeMeta`, by
+ *  `NodeRow`, and by the lean `GET /v1/canvas/graph` row the attach graph reads.
+ *  Declared narrow so a caller holding only the display projection needs no full
+ *  node record. */
+export interface NavNode {
+    node_id: string;
+    name: string;
+    kind: string;
+    description?: string;
+    cycles?: number;
+    status: NodeStatus;
+    frozen_at?: string | null;
+    pi_pid?: number | null;
+    streaming?: boolean;
+    telemetry_context_tokens?: number | null;
+    telemetry_last_activity?: string | null;
+    fault?: Fault | null;
+}
+/** pi's InteractiveMode.MAX_WIDGET_LINES — the hard cap on lines in a string
+ *  array widget; anything beyond it pi truncates with its own "... (widget
+ *  truncated)". Our GRAPH viewport stays at/under this and scrolls internally. */
+export declare const PI_MAX_WIDGET_LINES = 10;
+export declare const VIEWPORT_FALLBACK_ROWS = 30;
+export declare const ESC = "\u001B[";
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const REVERSE = "\u001B[7m";
+/** Dark-green background bar marking an ATTACHED node (a human is currently
+ *  watching it) — distinct from the cursor's reverse-video bar; chosen so
+ *  default-fg text stays readable. */
+export declare const BG_ATTACHED = "\u001B[48;5;22m";
+export declare const GREEN = "\u001B[32m";
+export declare const RED = "\u001B[31m";
+export declare const YELLOW = "\u001B[33m";
+export declare const CYAN = "\u001B[36m";
+export declare const GRAY = "\u001B[90m";
+/** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
+ *  outranks the base status glyph. Every input is a projected row field — the
+ *  owning daemon computed `fault`/`streaming` — so this holds for a remote node
+ *  too, with no local read keyed on a node id that may collide. */
+export declare function nodeGlyph(node: NavNode | null): string;
+/** Drop every SGR sequence, keeping the visible text. The selection bar uses
+ *  this: reverse-video INVERTS a coloured cell into a coloured block, so a row
+ *  built from tinted spans highlights as a patchwork of background swatches
+ *  instead of one bar. Stripping colour first leaves a single clean bar — the
+ *  glyphs (●/○/✓/✗/⚙/◷) still carry the signal, exactly as under NO_COLOR. */
+export declare function stripSgr(s: string): string;
+/** Visible width, ignoring ANSI escapes. */
+export declare function visibleWidth(s: string): number;
+/** Truncate to `max` VISIBLE columns: escape sequences are copied through
+ *  verbatim (so a cut never lands mid-escape) and the result always ends in
+ *  RESET, so a clipped style can't bleed into the editor below. */
+export declare function truncate(s: string, max?: number): string;
+/** Visible columns available to ONE widget line — the cap for every line we
+ *  emit, and the width a full-width reverse-video SELF bar fills to.
+ *
+ *  pi does NOT clip widget lines; it WRAPS them. Each string line is wrapped in
+ *  a `Text(paddingX = 1)` inside a full-terminal-width container, so the usable
+ *  content width is `columns - 2` (a 1-col margin on each side). A line wider
+ *  than that wraps, and the overflow spills onto a second row as a stray
+ *  reverse-video block (the bug this guards against). Clamp to `columns - 2`. */
+export declare function fillWidth(): number;
+/** Wrap `content` in a full-width background bar opened by `open` (REVERSE for
+ *  the cursor, BG_ATTACHED for a human-watched node). `open` is re-asserted after every
+ *  embedded RESET so a coloured cell (the status dot) can't punch a hole in the
+ *  bar; the visible width is padded out to `width`; the line closes with a real
+ *  RESET so the style never bleeds into the editor below. */
+export declare function fillBar(content: string, width: number, open: string): string;
+export declare function fmtTokens(n: number): string;
+/** The context-window cell — live window fill rounded to the nearest 1k (the same
+ * figure pi's footer shows), NOT a per-turn delta. Remote canvases retain the
+ * existing safe 0 display rather than treating a local node id as remote state. */
+export declare function tokensCell(node: NavNode | null, remote?: boolean): string;
+/** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
+ * Empty for non-active rows and when none is recorded. */
+export declare function activityCell(node: NavNode | null, remote?: boolean): string;
+/** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
+export declare function cycleBadge(node: NavNode | null): string;
+/** Short on-screen label: the explicit handle when set, else the pi-generated
+ *  description, else the bare name. fullName joins BOTH (`handle description`);
+ *  the nav chrome shows just the first so rows stay compact. */
+export declare function navLabel(node: NavNode | null, id: string): string;
+export declare function shortId(id: string): string;
+/** True when a human is watching `id` right now via the broker viewer count
+ *  (attach.json). The tmux-focus axis (a `focuses` row) is a canvas-db read and
+ *  stays in nav-model's `isAttached`, which ORs this signal with the focus set.
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export declare function hasBrokerViewers(id: string, node: NavNode | null, remote?: boolean): boolean;
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `focused` is the tmux-focus set (a canvas-db read the caller supplies). The
+ *  broker-viewer half is a pure `attach.json` read. `remote` skips the local read
+ *  entirely and reports false (a remote node id may collide with a local one). */
+export declare function isAttached(id: string, node: NavNode | null, focused: ReadonlySet<string>, remote?: boolean): boolean;
+/** ⚑K pending-asks badge for a node, read from the supplied per-node ask map. */
+export declare function askBadge(id: string, asks: Record<string, number>): string;
+/** "Live work below" badge — green ⇣N when this node is NOT itself active but has
+ *  N active descendants. The one signal that an idle/parked node isn't dead: real
+ *  work is still running beneath it. Count comes from the single subtree-activity
+ *  pass (no per-row walk). Suppressed on active rows (their own ● already says so). */
+export declare function liveBelowBadge(node: NavNode | null, activeBelow: ReadonlyMap<string, number>): string;
+export declare function fetchAsksMap(rootId: string): Record<string, number>;
+export interface FlatRow {
+    id: string;
+    hasKids: boolean;
+    isSelf: boolean;
+    branch: string;
+    cycle: boolean;
+    collapsed: boolean;
+}
+/** Manual fold OVERRIDES, keyed by id. `userCollapsed` forces a fold, `userExpanded`
+ *  forces an unfold; both override the default activity-driven policy. Held by the
+ *  consumer (the extension / viewer) and threaded into buildGraphModel so this layer
+ *  carries no mutable singletons. */
+export interface FoldState {
+    userExpanded: ReadonlySet<string>;
+    userCollapsed: ReadonlySet<string>;
+}
+/** One bottom-up O(N) pass result over the local graph (see computeSubtreeActivity
+ *  in nav-model.ts):
+ *   - `expand`: which nodes auto-UNFOLD — a node expands when a child subtree holds
+ *     a running ('active') agent or self.
+ *   - `activeBelow`: per node, the count of ACTIVE descendants (excluding itself). */
+export interface SubtreeActivity {
+    expand: Set<string>;
+    activeBelow: Map<string, number>;
+}
+/** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
+ *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own
+ *  scroll chrome — so never exceed it (and shrink on a very short terminal).
+ *  The viewport scrolls WITHIN this cap as the cursor moves. */
+export declare function graphWidgetBudget(): number;
+export declare const GRAPH_HINT = "\u001B[2mjk move \u00B7 hl fold \u00B7 \u21B5 focus \u00B7 e expand \u00B7 x kill \u00B7 m mgr \u00B7 esc\u001B[0m";