@north-light/api 0.3.580 → 0.3.587

package/dist/core/canvas/remote-canvas-source.d.ts

@@ -0,0 +1,71 @@
+import type { CanvasSource } from './source.js';
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+/** The exact JSON shape `crtr --json node inspect show <id>` emits (see
+ *  `nodeShow` in `src/commands/node/inspect.ts`) — mirrored here, not imported,
+ *  to avoid a commands→canvas value dependency. */
+export interface RemoteShowResponse {
+    node: NodeMeta;
+    reports: {
+        node_id: string;
+        name: string;
+        kind: string;
+        status: string;
+        active: boolean;
+    }[];
+    managers: {
+        node_id: string;
+        name: string;
+        kind: string;
+        status: string;
+        active: boolean;
+    }[];
+    artifacts: {
+        report: number;
+        doc: number;
+        roadmap: number;
+    };
+    pending_crons: number;
+    paths: {
+        context_dir: string;
+        session_file?: string | null;
+    };
+    follow_up: string;
+    fault?: {
+        link: string;
+        kind: string;
+        retry: {
+            disposition: string;
+        };
+        since: string;
+    } | null;
+}
+export declare class RemoteCanvasSource implements CanvasSource {
+    private readonly previewEndpoint;
+    private readonly relayToken;
+    private readonly exec;
+    private nodeCache;
+    private rosterCache;
+    private topologyCache;
+    private viewCache;
+    constructor(previewEndpoint: string, relayToken: string);
+    private execJson;
+    private fetchShow;
+    private topology;
+    private loadTopology;
+    /** The full passthrough object `node inspect show` produces — used by
+     *  `nodeShow`'s remote branch (`src/commands/node/inspect.ts`) to return the exact
+     *  same shape a local read would, without re-deriving it. */
+    rawShow(id: string): Promise<RemoteShowResponse | null>;
+    getNode(id: string): Promise<NodeMeta | null>;
+    getRow(id: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+        under?: string;
+    }): Promise<NodeRow[]>;
+    subscriptionsOf(id: string): Promise<SubscriptionRef[]>;
+    subscribersOf(id: string): Promise<SubscriptionRef[]>;
+    view(root: string): Promise<string[]>;
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
+    hasActiveLiveSubscription(id: string): Promise<boolean>;
+}

package/dist/core/canvas/remote-canvas-source.js

@@ -0,0 +1,290 @@
+// remote-canvas-source.ts — a CanvasSource backed by a remote canvas over the
+// relay-token-authed `/__crtr/source` transport (see `remote-transport.ts`).
+// Every method shells out to an EXISTING `crtr --json <subcommand>` in-guest —
+// no new in-guest command, no remote SQLite read, no drive-plane verb. A
+// short-TTL cache coalesces the repeated reads a single remote inspection or
+// dashboard render would otherwise make for the same node.
+//
+// P2 DEFERRAL (Stage-C, plan C-1/C-5): this remote path still targets the
+// `/__crtr/source` in-guest fulfillment endpoint on a preview host, NOT the
+// crtrd `/v1` API. Repointing remote canvases at a crtrd proxy shell is a P2
+// item; until then this subsystem is a settled, intentional exception to the
+// "every process is a /v1 client" architecture (which governs LOCAL access).
+import { createRemoteExec } from './remote-transport.js';
+const CACHE_TTL_MS = 1000;
+// Remote JSON shape validation.
+//
+// `execJson<T>` parses stdout and casts it to T with NO structural check — a
+// remote subprocess that exits 0 with a wrong shape (e.g. `{}`, `{node:null}`)
+// would otherwise pass through as a "valid" T. `fetchShow`/`listNodes`/
+// `ticketCountsForView` validate before caching/returning; on a shape mismatch
+// they degrade exactly like the existing network-failure path (null/[]/{}),
+// never a malformed object a caller might dereference.
+function isPlainObject(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+function isValidShowResponse(x) {
+    if (!isPlainObject(x))
+        return false;
+    const node = x['node'];
+    if (!isPlainObject(node) || typeof node['node_id'] !== 'string')
+        return false;
+    if (!Array.isArray(x['reports']) || !Array.isArray(x['managers']))
+        return false;
+    const artifacts = x['artifacts'];
+    if (!isPlainObject(artifacts) ||
+        typeof artifacts['report'] !== 'number' ||
+        typeof artifacts['doc'] !== 'number' ||
+        typeof artifacts['roadmap'] !== 'number')
+        return false;
+    if (typeof x['pending_crons'] !== 'number')
+        return false;
+    const paths = x['paths'];
+    if (!isPlainObject(paths) ||
+        typeof paths['context_dir'] !== 'string' ||
+        ('session_file' in paths && paths['session_file'] !== null && typeof paths['session_file'] !== 'string'))
+        return false;
+    if (typeof x['follow_up'] !== 'string')
+        return false;
+    const fault = x['fault'];
+    if (fault !== undefined && fault !== null) {
+        if (!isPlainObject(fault) || typeof fault['link'] !== 'string' || typeof fault['kind'] !== 'string' || typeof fault['since'] !== 'string')
+            return false;
+        const retry = fault['retry'];
+        if (!isPlainObject(retry) || typeof retry['disposition'] !== 'string')
+            return false;
+    }
+    return true;
+}
+/** A `reports`/`managers` entry (`RemoteShowResponse`) — validated per-element
+ *  because `isValidShowResponse` only checks the array wrapper. Without this,
+ *  a malformed neighbor (`null`, `{}`) survives into `subscriptionsOf`/
+ *  `subscribersOf`'s `.map()` and `node/inspect.ts`'s remote `show` passthrough render,
+ *  both of which dereference `.node_id`/`.active` unguarded. */
+function isValidNeighborEntry(x) {
+    return (isPlainObject(x) &&
+        typeof x['node_id'] === 'string' &&
+        typeof x['name'] === 'string' &&
+        typeof x['kind'] === 'string' &&
+        typeof x['status'] === 'string' &&
+        typeof x['active'] === 'boolean');
+}
+/** A `NodeRow` element from `node inspect list`'s `nodes` array — validated
+ *  per-element because a remote success payload can be `{nodes:[null]}` (the
+ *  outer array check alone lets that through). Requires the string identity/
+ *  lifecycle fields local/API-backed row renderers dereference unguarded;
+ *  the remaining nullable runtime
+ *  fields (host_kind, parent, pi_pid, ...) are left to cast through as-is. */
+function isValidRosterEdge(x) {
+    return (isPlainObject(x) &&
+        typeof x['from_id'] === 'string' &&
+        typeof x['to_id'] === 'string' &&
+        typeof x['active'] === 'boolean' &&
+        typeof x['created'] === 'string');
+}
+function isValidNodeRow(x) {
+    if (!isPlainObject(x))
+        return false;
+    return (typeof x['node_id'] === 'string' &&
+        typeof x['name'] === 'string' &&
+        typeof x['kind'] === 'string' &&
+        typeof x['mode'] === 'string' &&
+        typeof x['lifecycle'] === 'string' &&
+        typeof x['status'] === 'string' &&
+        typeof x['cwd'] === 'string' &&
+        typeof x['created'] === 'string');
+}
+export class RemoteCanvasSource {
+    previewEndpoint;
+    relayToken;
+    exec;
+    nodeCache = new Map();
+    rosterCache = new Map();
+    topologyCache = null;
+    viewCache = new Map();
+    constructor(previewEndpoint, relayToken) {
+        this.previewEndpoint = previewEndpoint;
+        this.relayToken = relayToken;
+        this.exec = createRemoteExec(previewEndpoint, relayToken);
+    }
+    async execJson(args) {
+        let raw;
+        try {
+            raw = await this.exec('crtr', ['--json', ...args]);
+        }
+        catch {
+            return null;
+        }
+        if (!raw.ok)
+            return null;
+        if (raw.exitCode !== undefined && raw.exitCode !== 0)
+            return null;
+        try {
+            return JSON.parse(raw.stdout.trim());
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchShow(id) {
+        const cached = this.nodeCache.get(id);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached.value;
+        const raw = await this.execJson(['node', 'inspect', 'show', id]);
+        // Sanitize reports/managers elements here (not just the outer array shape)
+        // so both consumers — subscriptionsOf/subscribersOf's `.map()` below AND
+        // node/inspect.ts's remote `show` passthrough render — see only well-formed
+        // neighbor entries, never a malformed one they'd dereference unguarded.
+        const res = isValidShowResponse(raw)
+            ? { ...raw, fault: raw.fault ?? null, reports: raw.reports.filter(isValidNeighborEntry), managers: raw.managers.filter(isValidNeighborEntry) }
+            : null;
+        this.nodeCache.set(id, { value: res, at: Date.now() });
+        return res;
+    }
+    topology() {
+        if (this.topologyCache !== null && Date.now() - this.topologyCache.at < CACHE_TTL_MS)
+            return this.topologyCache.value;
+        const request = this.loadTopology();
+        this.topologyCache = { value: request, at: Date.now() };
+        return request;
+    }
+    async loadTopology() {
+        const response = await this.exec('crtr', ['--json', 'canvas', 'roster']);
+        if (!response.ok || (response.exitCode !== undefined && response.exitCode !== 0)) {
+            throw new Error('remote canvas topology is unavailable');
+        }
+        let raw;
+        try {
+            raw = JSON.parse(response.stdout.trim());
+        }
+        catch {
+            throw new Error('remote canvas topology is invalid');
+        }
+        if (!isPlainObject(raw) || !Array.isArray(raw['edges']) || !raw['edges'].every(isValidRosterEdge)) {
+            throw new Error('remote canvas topology is invalid');
+        }
+        const edges = raw['edges'];
+        const topology = { subscriptions: new Map(), subscribers: new Map() };
+        for (const edge of edges) {
+            const subscription = { node_id: edge.to_id, active: edge.active, created: edge.created };
+            const subscriber = { node_id: edge.from_id, active: edge.active, created: edge.created };
+            const subscriptions = topology.subscriptions.get(edge.from_id);
+            if (subscriptions === undefined)
+                topology.subscriptions.set(edge.from_id, [subscription]);
+            else
+                subscriptions.push(subscription);
+            const subscribers = topology.subscribers.get(edge.to_id);
+            if (subscribers === undefined)
+                topology.subscribers.set(edge.to_id, [subscriber]);
+            else
+                subscribers.push(subscriber);
+        }
+        return topology;
+    }
+    /** The full passthrough object `node inspect show` produces — used by
+     *  `nodeShow`'s remote branch (`src/commands/node/inspect.ts`) to return the exact
+     *  same shape a local read would, without re-deriving it. */
+    async rawShow(id) {
+        return this.fetchShow(id);
+    }
+    async getNode(id) {
+        return (await this.fetchShow(id))?.node ?? null;
+    }
+    async getRow(id) {
+        const n = (await this.fetchShow(id))?.node;
+        if (!n)
+            return null;
+        return {
+            node_id: n.node_id,
+            name: n.name,
+            kind: n.kind,
+            mode: n.mode,
+            lifecycle: n.lifecycle,
+            status: n.status,
+            cwd: n.cwd,
+            host_kind: n.host_kind ?? null,
+            profile_id: n.profile_id ?? null,
+            scopes: n.scopes ?? null,
+            isolated: n.isolated === true,
+            parent: n.parent ?? null,
+            created: n.created,
+            intent: n.intent ?? null,
+            frozen_at: n.frozen_at ?? null,
+            terminal_reason: n.terminal_reason ?? null,
+            pi_pid: n.pi_pid ?? null,
+            pi_pid_identity: n.pi_pid_identity ?? null,
+            window: n.window ?? null,
+            tmux_session: n.tmux_session ?? null,
+            pane: n.pane ?? null,
+            // Recovery state projected by the REMOTE canvas's own daemon (stale-provider
+            // overlay already applied there), never a read of this host's files.
+            fault: n.fault ?? null,
+            streaming: n.streaming === true,
+        };
+    }
+    async listNodes(filter) {
+        const key = JSON.stringify([filter?.status ?? null, filter?.under ?? null]);
+        const cached = this.rosterCache.get(key);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached.value;
+        const args = ['node', 'inspect', 'list'];
+        if (filter?.status) {
+            args.push('--status', (Array.isArray(filter.status) ? filter.status : [filter.status]).join(','));
+        }
+        if (filter?.under)
+            args.push('--under', filter.under);
+        const res = await this.execJson(args);
+        const rawNodes = isPlainObject(res) && Array.isArray(res['nodes']) ? res['nodes'] : [];
+        const nodes = rawNodes.filter(isValidNodeRow).map((node) => ({ ...node, isolated: node.isolated === true }));
+        this.rosterCache.set(key, { value: nodes, at: Date.now() });
+        return nodes;
+    }
+    async subscriptionsOf(id) {
+        return (await this.topology()).subscriptions.get(id) ?? [];
+    }
+    async subscribersOf(id) {
+        return (await this.topology()).subscribers.get(id) ?? [];
+    }
+    async view(root) {
+        const cached = this.viewCache.get(root);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+            return cached.value;
+        const seen = new Set([root]);
+        const out = [];
+        const queue = (await this.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 await this.subscriptionsOf(id)) {
+                if (!seen.has(s.node_id))
+                    queue.push(s.node_id);
+            }
+        }
+        this.viewCache.set(root, { value: out, at: Date.now() });
+        return out;
+    }
+    async ticketCountsForNodes(nodeIds) {
+        // The `canvas attention map` transport's `counts` values mean all pending
+        // human tickets (page/review), not just asks.
+        if (nodeIds.length === 0)
+            return {};
+        const res = await this.execJson(['canvas', 'attention', 'map', '--nodes', nodeIds.join(',')]);
+        return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
+    }
+    async ticketCountsForView(root) {
+        const res = await this.execJson(['canvas', 'attention', 'map', '--view', root]);
+        return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
+    }
+    async hasActiveLiveSubscription(id) {
+        const subs = (await this.subscriptionsOf(id)).filter((s) => s.active);
+        for (const s of subs) {
+            const row = await this.getRow(s.node_id);
+            if (row && (row.status === 'active' || row.status === 'idle'))
+                return true;
+        }
+        return false;
+    }
+}

package/dist/core/canvas/remote-transport.d.ts

@@ -0,0 +1,7 @@
+export interface RemoteExecResponse {
+    ok: boolean;
+    exitCode?: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function createRemoteExec(previewEndpoint: string, relayToken: string, timeoutMs?: number): (bin: string, args: string[]) => Promise<RemoteExecResponse>;

package/dist/core/canvas/remote-transport.js

@@ -0,0 +1,57 @@
+// remote-transport.ts — the Node-side remote exec transport for a
+// RemoteCanvasSource. POSTs an exec request to a Blaxel preview endpoint's
+// `/__crtr/source` route, bearer-authed with the relay token.
+//
+// This is the ONLY way RemoteCanvasSource reaches the remote canvas: it never
+// reads a remote SQLite file, and it never invokes an in-guest command that
+// doesn't already exist. Every argv it sends is `crtr --json <existing
+// subcommand>` — read-only.
+//
+// P2 DEFERRAL (Stage-C, plan C-1/C-5): `/__crtr/source` on a preview host is
+// the REMOTE transport, deliberately outside the local crtrd `/v1` boundary.
+// Repointing remote hosts at a crtrd proxy shell is a P2 hand-off; this file is
+// a settled exception, not a P1 defect.
+/** The remote read plane crosses a network boundary — a stalled TCP connection
+ *  or a hung `/__crtr/source` handler must fail closed, not wedge `node
+ *  inspect`/`canvas browse`/attach forever. Low enough that a genuinely hung
+ *  endpoint surfaces as a failed read within one interactive frame, not a
+ *  silent hang. */
+const DEFAULT_TIMEOUT_MS = 5_000;
+export function createRemoteExec(previewEndpoint, relayToken, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    // A malformed stored token (control chars / non-Latin1 bytes) would throw
+    // from the Headers constructor with the invalid value IN the thrown
+    // message — validate up front so that never happens, and fail with a
+    // GENERIC message instead: no token bytes may ever reach returned stderr.
+    // HTTP header values are ISO-8859-1; reject
+    // anything outside `/^[\x20-\x7e]+$/` (printable ASCII, no CR/LF/control).
+    const tokenValid = /^[\x20-\x7e]+$/.test(relayToken);
+    return async function exec(bin, args) {
+        if (!tokenValid) {
+            return { ok: false, stdout: '', stderr: 'remote source: invalid stored relay token' };
+        }
+        const req = { kind: 'exec', bin, args };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(new URL('/__crtr/source', previewEndpoint), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${relayToken}` },
+                body: JSON.stringify(req),
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            if (controller.signal.aborted) {
+                return { ok: false, stdout: '', stderr: `remote source: timeout after ${timeoutMs}ms` };
+            }
+            return { ok: false, stdout: '', stderr: 'remote source: network error' };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return { ok: false, stdout: '', stderr: `remote source: HTTP ${res.status} ${res.statusText}` };
+        return (await res.json());
+    };
+}

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

@@ -0,0 +1,193 @@
+import type { CanvasSource } from './source.js';
+import { type NodeRecap } from './node-recap.js';
+import type { Fault } from '../runtime/fault.js';
+import type { NodeStatus, Lifecycle, NodeRow, TerminalReason } from './types.js';
+/** Format a token count as `Nk` (rounded down to nearest 1 k). */
+export declare function fmtCtx(tokensIn: number | undefined): string;
+export declare function renderTreeFromSource(source: CanvasSource, rootId: string, snapshot?: readonly NodeRow[], ticketSnapshot?: Record<string, number>, ticketUnavailable?: string): Promise<string>;
+export declare function renderForestFromSource(source: CanvasSource, snapshot?: readonly NodeRow[], ticketSnapshot?: Record<string, number>, ticketUnavailable?: string): Promise<string>;
+export interface DashboardRow {
+    node_id: string;
+    /** Full display label: explicit handle plus generated description. */
+    name: string;
+    /** Explicit node handle, kept separate so search does not treat generated text
+     *  as part of the higher-weight name field. */
+    handle?: string;
+    /** Generated first-task description. Searchable below user-authored prompts. */
+    description?: string;
+    status: NodeStatus;
+    frozen_at?: string | null;
+    terminal_reason?: TerminalReason | null;
+    kind: string;
+    mode: string;
+    ctx_tokens: number;
+    asks: number;
+    /** The dir the node is pinned to (its cwd). Drives the browser's cwd-scope
+     *  filter + the All-dirs basename cue. */
+    cwd: string;
+    /** The stable profile identity the node runs under. Drives canvas browse's
+     *  default profile filter; null only for historical no-profile nodes. */
+    profile_id?: string | null;
+    /** 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;
+    /** True when the node pushed a final report. With `lifecycle` this separates
+     *  work that FINISHED from a resident agent that merely stopped, which the
+     *  status alone cannot (see `isFinishedWork` in node-order.ts). Only populated
+     *  by dashboardRowsAll (the browser snapshot). */
+    finalized?: boolean;
+    /** "Most recent activity" sort key — epoch ms from the daemon's telemetry
+     *  projection, falling back to `created` when a node never reported telemetry.
+     *  This is the cheap proxy for last-message recency the attention sort tie-breaks
+     *  on. Always set by dashboardRowsAll; optional only so synthetic test rows + the
+     *  scoped dashboardRows can omit it. */
+    mtimeMs?: number;
+    /** The node's spawn prompt (context/initial-prompt.md), trimmed + capped. Populated
+     *  LAZILY by loadPreview (selected-row preview) — NOT on the cheap boot path.
+     *  Indexed by super-search and shown in the preview panel when there is no query. */
+    goal?: string;
+    /** The user prompts from the session's opening and closing 64 KB, joined + capped.
+     *  Populated LAZILY by loadSearchText once a search opens; undefined for
+     *  never-revived nodes (no session file). Powers super-search + the windowed
+     *  preview snippet under a query. */
+    prompts?: string;
+    /** The node's LAST assistant message (text only), trimmed + capped. Populated LAZILY
+     *  by loadPreview (the same tail read as `transcript`); undefined for a node whose
+     *  session has no assistant reply yet. Shown in the preview's reply block. */
+    lastAssistant?: string;
+    /** The node's last persisted Goal/State briefing (`job/recap.json`, written by the
+     *  broker's recap extension). Populated LAZILY by loadPreview; undefined for a node
+     *  that never generated one. The preview's fastest "what is this / where is it" line. */
+    recap?: NodeRecap;
+    /** The newest report the node pushed (`reports/<ts>-<id>-<kind>.md`). Populated
+     *  LAZILY by loadPreview; undefined when the node has pushed nothing. Residents push
+     *  updates as they work, so this is the last thing the node deliberately DELIVERED —
+     *  usually crisper than its last assistant message. */
+    report?: NodeReportPreview;
+    /** True when the node is GENUINELY mid-turn right now — the projected row's
+     *  `streaming` (its live execution has an open turn AND its broker pid is alive),
+     *  not merely an `active`, between-turns node. The live "is it generating?" cue,
+     *  carried for LIVE nodes only (dormant rows are always false). */
+    streaming?: boolean;
+    /** Set when the node is parked on an active fault. The otherwise-invisible
+     *  "stuck, awaiting recovery" window. Mutually exclusive with `streaming`
+     *  (hanging means the turn ended, so no turn is open); when set,
+     *  dashboardRowsAll forces `streaming:false`. The projected row field, already
+     *  overlaid by the owning daemon (stale daemon-owned provider faults whose
+     *  broker pid is gone are suppressed there). */
+    hanging?: Fault | null;
+    /** True when a viewer (focus row) is attached to the node — i.e. someone has it
+     *  open on screen. Set on the cheap boot path from one listFocuses() query. The
+     *  focus registry is local viewer state, so callers pass it separately from the
+     *  canvas source and remote snapshots always suppress it. */
+    viewed?: boolean;
+    /** Lazy-enrichment guard (internal): true once enrichRow/enrichRows has folded in
+     *  the full label (meta), ctx tokens (telemetry), and ⚑ asks. Idempotency marker so
+     *  progressive paint can re-call enrich for a viewport every keystroke for free. */
+    enriched?: boolean;
+    /** Lazy-enrichment guard (internal): true once loadPreview has read goal, recap,
+     *  report and lastAssistant. Idempotency marker for the selected row. */
+    previewLoaded?: boolean;
+    /** Lazy guard (internal): true once loadSearchText has read goal + `prompts`. */
+    promptsLoaded?: boolean;
+    /** The node's conversation as ORDERED user/assistant turns — what the preview panel
+     *  paints as a chat transcript. Populated LAZILY by loadPreview({transcript}) for the SELECTED
+     *  row only (never on the background warm pass): one transcript per row is a few KB,
+     *  and holding one for every node on a multi-thousand-node canvas is what `prompts`
+     *  and `lastAssistant` exist to avoid. Undefined until asked for; an empty array
+     *  means "read, and the node has no session turns". */
+    transcript?: TranscriptTurn[];
+    /** Lazy guard (internal): true once loadPreview({transcript}) has read the session for this row. */
+    transcriptLoaded?: boolean;
+    /** The source `NodeRow` this row was built from (dashboardRowFromNodeRow only).
+     *  Carries every column listNodes already fetched — the runtime fields
+     *  (host_kind/parent/final_report/finalized_at/pi_pid) plus the
+     *  mirrored identity fields (description/cycles) — so the snapshot handler
+     *  reads them here instead of opening meta.json.
+     *  Undefined for rows built by other paths (dashboardRowsFromSource). */
+    srcRow?: NodeRow;
+}
+export declare function readGoalText(contextPath: string): string | undefined;
+/** The newest pushed report, reduced to what a preview panel can use. */
+export interface NodeReportPreview {
+    /** final | update | urgent. */
+    kind: string;
+    /** ISO 8601 push time. */
+    ts: string;
+    /** The report's first markdown heading, or its first non-empty line. */
+    heading: string;
+    /** The body after that heading, whitespace-normalized + capped. */
+    body: string;
+}
+/** The node's newest report document, reduced to a preview. Never throws;
+ *  undefined when the node pushed nothing. */
+export declare function reportPreview(report: {
+    tier: string;
+    created: string;
+    body: string;
+} | null | undefined): NodeReportPreview | undefined;
+export declare function readSessionPrompts(sessionFile: string | null | undefined): Promise<string | undefined>;
+/** One conversation turn as the preview panel paints it. */
+export interface TranscriptTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+/** The session's recent end in ONE tail read: the conversation as ordered
+ *  user/assistant turns, newest-last and capped to the last TRANSCRIPT_TURNS, and
+ *  the newest assistant message with text (`lastAssistant`). Generated context cards
+ *  are dropped (runtime scaffolding, not something the user or the agent said) and
+ *  so are tool-only assistant turns, so the result reads as a chat rather than a
+ *  log. The read starts at 256 KB and widens only when that window held no reply —
+ *  a tail that landed inside one giant tool result. Never throws on a missing
+ *  session; empty for a node that was never revived. */
+export interface SessionTail {
+    transcript: TranscriptTurn[];
+    lastAssistant?: string;
+}
+export declare function readSessionTail(sessionFile: string | null | undefined): Promise<SessionTail>;
+/** Did this node's engine ever PRODUCE something — an assistant message with real
+ *  text, a tool call, or non-empty reasoning? The signal that a node did work and
+ *  is not an empty shell. A never-revived node (no session file) is trivially
+ *  false; an assistant turn that is only an empty/aborted `thinking` stub does NOT
+ *  count (that's a node started and killed before it did anything). CONSERVATIVE
+ *  by design: ANY substance keeps the node, so the reap never deletes real work
+ *  — a tool-call-only turn (no final text) still counts. Drives reap-on-close/
+ *  detach. One file read with an early exit on the first substantive turn. */
+export declare function nodeHasAssistantMessage(sessionFile: string | null | undefined): Promise<boolean>;
+/** "Most recent activity" sort key from the daemon's telemetry projection. It
+ * falls back to `created` when the broker has never reported telemetry. */
+export declare function sessionMtime(created: string, telemetryUpdatedAt: string | null | undefined, remote?: boolean): number;
+/** Build one cheap-boot row from a raw db/source row. `fault`/`streaming` are
+ *  projected row fields, so they hold for a remote row too; `remote` suppresses the
+ *  LOCAL disk reads (telemetry-mtime/viewers) that are meaningless for a truly
+ *  remote canvas. A local row is viewed when either its tmux focus row exists or
+ *  its live broker reports a terminal/web viewer. */
+export declare function dashboardRowFromNodeRow(row: NodeRow, focusedNodeIds: ReadonlySet<string>, remote: boolean): DashboardRow;
+/** One row per node visible in the sub-DAG of `rootId` (including root), read
+ *  entirely through the source — the openDb-free sibling of `dashboardRows`.
+ *  Ticket counts come from ONE `source.ticketCountsForView(rootId)` call (the
+ *  API/remote attention projection), never `countTickets` (openDb). */
+export declare function dashboardRowsFromSource(source: CanvasSource, rootId: string, snapshot?: readonly NodeRow[], ticketSnapshot?: Record<string, number>): Promise<DashboardRow[]>;
+/** CHEAP boot builder over a source — one row per node across the whole canvas,
+ *  fields that need no per-node meta/session read. Local API callers may supply
+ *  the node ids from one `listFocuses()` query so `viewed` remains visible without
+ *  coupling the canvas source to local viewer state. Remote sources ignore that
+ *  set. Local disk telemetry is likewise suppressed remotely. */
+export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>, liveOnly?: boolean, snapshot?: readonly NodeRow[]): Promise<DashboardRow[]>;
+export declare function enrichRowsFromSource(_source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
+/** The selected row's preview: goal, recap, newest report and the session's recent
+ *  end (`lastAssistant`), from one small tail read. `transcript: true` also folds the
+ *  ordered chat turns from that same read — ask for it for the SELECTED row only,
+ *  never across the canvas, where one transcript per node is exactly the memory cost
+ *  the capped fields avoid. goal, recap and session are local disk reads, suppressed
+ *  for a remote source (its transcript stays empty). */
+export declare function loadPreviewFromSource(source: CanvasSource, row: DashboardRow, opts?: {
+    transcript?: boolean;
+}): Promise<DashboardRow>;
+/** The text super-search matches: the spawn prompt (`goal`) and the session's user
+ *  prompts (`prompts`). Read for every row once a search opens, so it is only the
+ *  small prompt window — never the preview's recap, report or transcript. Local only. */
+export declare function loadSearchTextFromSource(source: CanvasSource, row: DashboardRow): Promise<DashboardRow>;