@north-light/api 0.3.580 → 0.3.587

package/dist/core/canvas/schema-version.d.ts

@@ -0,0 +1,30 @@
+/** The canvas schema version this build supports: the number of the highest delta in `schema-pg/` (the baseline
+ *  `schema-pg.sql` is version 1). `scripts/install-runtime.mjs` reads this module from a candidate generation to refuse
+ *  one below the live database's `schema_min_reader`. */
+export declare const CANVAS_SCHEMA_VERSION = 10;
+/** The Postgres schema holding the canvas tables: `CRTR_DATABASE_SCHEMA` (`crtr` in the cloud deploy). Unset or empty
+ *  means the role's own search_path (`public` on a Mac and on a VM). A name that is not a plain identifier is an error:
+ *  it is put in a `search_path` connection option. */
+export declare function canvasDatabaseSchema(env?: Record<string, string | undefined>): string | undefined;
+/** The direct, non-pooled connection the schema chain runs on when `CRTR_SCHEMA_DATABASE_URL` is set (its advisory lock
+ *  needs one session). Unset: the chain runs on the daemon's own connection. */
+export declare function canvasSchemaDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
+/** The pg `options` connection parameter that makes every connection resolve unqualified names in the canvas schema. */
+export declare function canvasSearchPathOptions(env?: Record<string, string | undefined>): string | undefined;
+interface Queryable {
+    query(text: string): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+export interface StoredVersions {
+    /** `canvas_meta.schema_version`: the number of the last committed step. */
+    version: number;
+    /** `canvas_meta.schema_min_reader`: the lowest build version that may open the database; absent means `version`. */
+    minReader: number;
+}
+/** The versions stored in `schema` (default: the session's search_path), or undefined when the database has no canvas schema yet. */
+export declare function readStoredVersions(client: Queryable, schema?: string): Promise<StoredVersions | undefined>;
+/** The installer's rollback gate: refuse a candidate whose version is below the live database's `schema_min_reader`. A
+ *  database with no canvas schema yet accepts any candidate. */
+export declare function assertCandidateMayOpen(client: Queryable, supported: number, schema?: string): Promise<void>;
+export {};

package/dist/core/canvas/schema-version.js

@@ -0,0 +1,58 @@
+// schema-version.ts — what a build and the installer need to know about the canvas schema, kept free of imports so
+// `scripts/install-runtime.mjs` can load it from a candidate generation with plain node. The version a build supports,
+// which Postgres schema holds the canvas tables (`CRTR_DATABASE_SCHEMA`), how to read the stored versions from that
+// schema, and the rollback gate the installer applies. The daemon (`schema-chain.ts`, `db.ts`) and the installer read the
+// same schema through the same functions below.
+/** The canvas schema version this build supports: the number of the highest delta in `schema-pg/` (the baseline
+ *  `schema-pg.sql` is version 1). `scripts/install-runtime.mjs` reads this module from a candidate generation to refuse
+ *  one below the live database's `schema_min_reader`. */
+export const CANVAS_SCHEMA_VERSION = 10;
+/** The Postgres schema holding the canvas tables: `CRTR_DATABASE_SCHEMA` (`crtr` in the cloud deploy). Unset or empty
+ *  means the role's own search_path (`public` on a Mac and on a VM). A name that is not a plain identifier is an error:
+ *  it is put in a `search_path` connection option. */
+export function canvasDatabaseSchema(env = process.env) {
+    const schema = env['CRTR_DATABASE_SCHEMA']?.trim();
+    if (!schema)
+        return undefined;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema))
+        throw new Error(`CRTR_DATABASE_SCHEMA must be a plain identifier (letters, digits, underscore); got ${JSON.stringify(schema)}`);
+    return schema;
+}
+/** The direct, non-pooled connection the schema chain runs on when `CRTR_SCHEMA_DATABASE_URL` is set (its advisory lock
+ *  needs one session). Unset: the chain runs on the daemon's own connection. */
+export function canvasSchemaDatabaseUrl(env = process.env) {
+    return env['CRTR_SCHEMA_DATABASE_URL']?.trim() || undefined;
+}
+/** The pg `options` connection parameter that makes every connection resolve unqualified names in the canvas schema. */
+export function canvasSearchPathOptions(env = process.env) {
+    const schema = canvasDatabaseSchema(env);
+    return schema === undefined ? undefined : `-c search_path=${schema}`;
+}
+/** The versions stored in `schema` (default: the session's search_path), or undefined when the database has no canvas schema yet. */
+export async function readStoredVersions(client, schema) {
+    const table = schema === undefined ? 'canvas_meta' : `"${schema.replace(/"/g, '""')}".canvas_meta`;
+    const exists = await client.query(`SELECT to_regclass('${table.replace(/'/g, "''")}') IS NOT NULL AS found`);
+    if (exists.rows[0]['found'] !== true)
+        return undefined;
+    const rows = (await client.query(`SELECT key, value FROM ${table} WHERE key IN ('schema_version', 'schema_min_reader')`)).rows;
+    const value = (key) => {
+        const row = rows.find(r => r['key'] === key);
+        if (row === undefined)
+            return undefined;
+        const parsed = Number(row['value']);
+        if (!Number.isSafeInteger(parsed))
+            throw new Error(`canvas_meta.${key} is not an integer: ${String(row['value'])}`);
+        return parsed;
+    };
+    const version = value('schema_version');
+    return version === undefined ? undefined : { version, minReader: value('schema_min_reader') ?? version };
+}
+/** The installer's rollback gate: refuse a candidate whose version is below the live database's `schema_min_reader`. A
+ *  database with no canvas schema yet accepts any candidate. */
+export async function assertCandidateMayOpen(client, supported, schema) {
+    const stored = await readStoredVersions(client, schema);
+    if (stored !== undefined && stored.minReader > supported) {
+        throw new Error(`refusing to select runtime with canvas schema ${supported}: ` +
+            `the live database requires readers at version ${stored.minReader} or above (it is at ${stored.version}); install a descendant build instead`);
+    }
+}

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

@@ -0,0 +1,54 @@
+import { type ConversationStore } from '../conversation-store/index.js';
+export interface SessionBinding {
+    bindingId: string;
+    sessionId: string | null;
+    nodeId: string;
+    transcriptPath: string | null;
+    sourceSessionId: string | null;
+    forkEntryId: string | null;
+    createdAt: string;
+    boundAt: string;
+    unboundAt: string | null;
+}
+export declare function readLiveSession(nodeId: string): Promise<SessionBinding | null>;
+export declare function findNodeBySessionFileSql(path: string): Promise<string | null>;
+export declare function bindSession(nodeId: string, input: {
+    executionId: string;
+    sessionId: string | null;
+    transcriptPath: string | null;
+    sourceSessionId?: string | null;
+}): Promise<'bound' | 'shutdown'>;
+export declare function resetSession(nodeId: string, input: {
+    sessionId: string;
+    transcriptPath: string | null;
+}): Promise<void>;
+export declare function transferSession(input: {
+    fromNodeId: string;
+    fromBindingId: string;
+    toNodeId: string;
+    executionId: string;
+    sessionId: string | null;
+    transcriptPath: string | null;
+}): Promise<'transferred' | 'shutdown' | 'changed'>;
+export declare function unbindSession(nodeId: string): Promise<void>;
+/** Rewrite the header `cwd` of every conversation this node owns from `oldCwd` to `newCwd`, keeping the sessions bound. Returns conversations rewritten. */
+export declare function relocateSessionCwd(nodeId: string, oldCwd: string, newCwd: string): Promise<number>;
+export declare function setCyclePending(nodeId: string, pending: boolean): Promise<void>;
+export declare function conversationOwner(conversationId: string): Promise<string | null>;
+/** Open the row store: durable tail rows plus immutable blob parts. `root` is unused; it stays so test callers keep one signature. */
+export declare function openCanvasConversationStore(_root?: string): ConversationStore & {
+    commit(id: string): Promise<number>;
+    importLegacy(runId?: string): Promise<void>;
+    recover(rows: Array<{
+        session_id: string;
+        node_id: string;
+        transcript_path: string | null;
+    }>): void;
+};
+/** Record each run conversation's existing transcript file as part 0 (first boot after the file store). */
+export declare function repairRunConversations(runId: string): Promise<void>;
+/** Install the row store in this process and import any transcript files not yet recorded as part 0.
+ *  Brokers reach it over the /v1 API; no socket is bound here. */
+export declare function serveCanvasConversationStore(): Promise<{
+    close(): Promise<void>;
+}>;

package/dist/core/canvas/sessions.js

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+import { openDb, withCanvasWrite } from './db.js';
+import { canonicalSessionFile } from './canvas.js';
+import { conversationStore, installConversationStore } from '../conversation-store/index.js';
+import { createRowStore, relocateConversationHeader } from '../conversation-store/row-store.js';
+function now() {
+    return new Date().toISOString();
+}
+async function liveExecution(db, nodeId, executionId) {
+    return await db.prepare("SELECT 1 FROM executions WHERE execution_id = ? AND node_id = ? AND state != 'exited'").get(executionId, nodeId) !== undefined;
+}
+function hydrate(row) {
+    return {
+        bindingId: row['binding_id'],
+        sessionId: row['session_id'] ?? null,
+        nodeId: row['node_id'],
+        transcriptPath: row['transcript_path'] ?? null,
+        sourceSessionId: row['source_session_id'] ?? null,
+        forkEntryId: row['fork_entry_id'] ?? null,
+        createdAt: row['created_at'],
+        boundAt: row['bound_at'],
+        unboundAt: row['unbound_at'] ?? null,
+    };
+}
+export async function readLiveSession(nodeId) {
+    const row = await (await openDb()).prepare('SELECT * FROM sessions WHERE node_id = ? AND unbound_at IS NULL').get(nodeId);
+    return row === undefined ? null : hydrate(row);
+}
+export async function findNodeBySessionFileSql(path) {
+    const row = await (await openDb()).prepare('SELECT node_id FROM sessions WHERE transcript_path = ? AND unbound_at IS NULL').get(canonicalSessionFile(path));
+    return row?.node_id ?? null;
+}
+export async function bindSession(nodeId, input) {
+    return await withCanvasWrite(async (db) => {
+        if (!await liveExecution(db, nodeId, input.executionId))
+            return 'shutdown';
+        // A session id names one conversation for its owner; only transferSession moves it to another node.
+        if (input.sessionId !== null && await db.prepare('SELECT 1 FROM sessions WHERE session_id = ? AND node_id <> ? LIMIT 1').get(input.sessionId, nodeId) !== undefined) {
+            throw new Error(`session ${input.sessionId} is bound to another node`);
+        }
+        const at = now();
+        const path = input.transcriptPath === null ? null : canonicalSessionFile(input.transcriptPath);
+        const current = await db.prepare('SELECT binding_id, session_id FROM sessions WHERE node_id = ? AND unbound_at IS NULL').get(nodeId);
+        if (current !== undefined && current.session_id === input.sessionId) {
+            await db.prepare('UPDATE sessions SET transcript_path = ?, source_session_id = ?, bound_at = ? WHERE binding_id = ?').run(path, input.sourceSessionId ?? null, at, current.binding_id);
+        }
+        else {
+            if (current !== undefined)
+                await db.prepare('UPDATE sessions SET unbound_at = ? WHERE binding_id = ?').run(at, current.binding_id);
+            const prepared = input.sessionId === null ? undefined : await db.prepare('SELECT binding_id FROM sessions WHERE node_id = ? AND session_id = ? ORDER BY created_at DESC LIMIT 1').get(nodeId, input.sessionId);
+            if (prepared) {
+                await db.prepare('UPDATE sessions SET transcript_path = ?, source_session_id = ?, bound_at = ?, unbound_at = NULL WHERE binding_id = ?').run(path, input.sourceSessionId ?? null, at, prepared.binding_id);
+            }
+            else {
+                await db.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at) VALUES (?, ?, ?, ?, ?, NULL, ?, ?)').run(randomUUID(), input.sessionId, nodeId, path, input.sourceSessionId ?? null, at, at);
+            }
+        }
+        await db.prepare('UPDATE nodes SET cycle_pending = 0 WHERE node_id = ?').run(nodeId);
+        return 'bound';
+    });
+}
+export async function resetSession(nodeId, input) {
+    await withCanvasWrite(async (db) => {
+        const at = now();
+        await db.prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(at, nodeId);
+        await db.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at) VALUES (?, ?, ?, ?, NULL, NULL, ?, ?)').run(randomUUID(), input.sessionId, nodeId, input.transcriptPath === null ? null : canonicalSessionFile(input.transcriptPath), at, at);
+        await db.prepare('UPDATE nodes SET cycle_pending = 0 WHERE node_id = ?').run(nodeId);
+    });
+}
+export async function transferSession(input) {
+    return await withCanvasWrite(async (db) => {
+        if (!await liveExecution(db, input.toNodeId, input.executionId))
+            return 'shutdown';
+        const source = await db.prepare('SELECT binding_id FROM sessions WHERE node_id = ? AND binding_id = ? AND unbound_at IS NULL').get(input.fromNodeId, input.fromBindingId);
+        if (source === undefined)
+            return 'changed';
+        const run = await db.prepare('SELECT run_id FROM nodes WHERE node_id IN (?, ?) AND run_id IS NOT NULL LIMIT 1').get(input.fromNodeId, input.toNodeId);
+        if (run)
+            throw new Error('run conversation transfer is not supported');
+        const at = now();
+        await db.prepare('UPDATE sessions SET unbound_at = ? WHERE binding_id = ?').run(at, input.fromBindingId);
+        await db.prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(at, input.toNodeId);
+        await db.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at) VALUES (?, ?, ?, ?, NULL, NULL, ?, ?)').run(randomUUID(), input.sessionId, input.toNodeId, input.transcriptPath === null ? null : canonicalSessionFile(input.transcriptPath), at, at);
+        await db.prepare('UPDATE nodes SET cycle_pending = 0 WHERE node_id = ?').run(input.toNodeId);
+        return 'transferred';
+    });
+}
+export async function unbindSession(nodeId) {
+    await (await openDb()).prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(now(), nodeId);
+}
+/** Rewrite the header `cwd` of every conversation this node owns from `oldCwd` to `newCwd`, keeping the sessions bound. Returns conversations rewritten. */
+export async function relocateSessionCwd(nodeId, oldCwd, newCwd) {
+    const rows = await (await openDb()).prepare('SELECT DISTINCT session_id FROM sessions WHERE node_id = ? AND session_id IS NOT NULL').all(nodeId);
+    let changed = 0;
+    for (const row of rows)
+        if (await relocateConversationHeader(row.session_id, oldCwd, newCwd))
+            changed++;
+    return changed;
+}
+export async function setCyclePending(nodeId, pending) {
+    await (await openDb()).prepare('UPDATE nodes SET cycle_pending = ? WHERE node_id = ?').run(pending ? 1 : 0, nodeId);
+}
+/** A conversation's owner is its bound row, else its latest row. */
+const OWNER_ORDER = 'unbound_at IS NULL DESC, created_at DESC, seq DESC';
+export async function conversationOwner(conversationId) {
+    const row = await (await openDb()).prepare(`SELECT node_id FROM sessions WHERE session_id = ? ORDER BY ${OWNER_ORDER} LIMIT 1`).get(conversationId);
+    return row?.node_id ?? null;
+}
+/** Open the row store: durable tail rows plus immutable blob parts. `root` is unused; it stays so test callers keep one signature. */
+export function openCanvasConversationStore(_root) {
+    return createRowStore();
+}
+/** Record each run conversation's existing transcript file as part 0 (first boot after the file store). */
+export async function repairRunConversations(runId) {
+    await conversationStore().importLegacy?.(runId);
+}
+/** Install the row store in this process and import any transcript files not yet recorded as part 0.
+ *  Brokers reach it over the /v1 API; no socket is bound here. */
+export async function serveCanvasConversationStore() {
+    const store = openCanvasConversationStore();
+    installConversationStore(store);
+    await store.importLegacy();
+    return {
+        async close() {
+            installConversationStore(undefined);
+        },
+    };
+}

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

@@ -0,0 +1,52 @@
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+import type { Scope } from '../../types.js';
+import type { RosterDTO } from '../../api/dto/canvas.js';
+export interface CanvasSource {
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    /** `under` restricts to the nodes below that node, excluding it. */
+    /** `under` scopes to that node plus every node below it (human ask nodes included), one query. */
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+        under?: string;
+    }): Promise<NodeRow[]>;
+    /** Optional one-request browse projection. Other listNodes callers keep their full rows. */
+    browseSnapshot?(): Promise<NodeRow[]>;
+    /** One topology snapshot for the attach relationship panel. */
+    panelRoster?(): Promise<RosterDTO>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    view(root: string): Promise<string[]>;
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+    /** The node's newest report document, or null. Only a source that reads through `/v1` offers it. */
+    newestReport?(nodeId: string): Promise<{
+        tier: string;
+        created: string;
+        body: string;
+    } | null>;
+}
+export declare class LocalCanvasSource implements CanvasSource {
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+        under?: string;
+    }): Promise<NodeRow[]>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    view(root: string): Promise<string[]>;
+    ticketCountsForNodes(nodeIds: readonly string[]): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+}
+export declare const localCanvasSource: CanvasSource;
+/** The active read source for a command: an explicit `--canvas <name>` wins,
+ *  else the durable `crtr canvas use` selection (`ScopeState.activeCanvas`),
+ *  else local — byte-for-byte the same `localCanvasSource` singleton so a
+ *  caller with neither set sees zero behavior change. */
+export declare function resolveCanvasSource(opts?: {
+    canvasName?: string;
+    scope?: Scope;
+}, sandboxed?: boolean): CanvasSource;

package/dist/core/canvas/source.js

@@ -0,0 +1,57 @@
+import { getNode, getRow, listNodes, subscriptionsOf, subscribersOf, view, hasActiveLiveSubscription, } from './canvas.js';
+import { ticketCountsForNodes } from './attention.js';
+import { readState } from '../config.js';
+import { resolveRemoteCanvasTarget } from '../remote-canvas-target.js';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
+import { isSandboxedNode } from '../../shared/env.js';
+import { ownerOnly } from '../errors.js';
+export class LocalCanvasSource {
+    async getNode(nodeId) {
+        return await getNode(nodeId);
+    }
+    async getRow(nodeId) {
+        return await getRow(nodeId);
+    }
+    async listNodes(filter) {
+        const { under, ...rest } = filter ?? {};
+        return await listNodes(under === undefined ? rest : { ...rest, under, underInclusive: true });
+    }
+    async subscriptionsOf(subscriber) {
+        return await subscriptionsOf(subscriber);
+    }
+    async subscribersOf(publisher) {
+        return await subscribersOf(publisher);
+    }
+    async view(root) {
+        return await view(root);
+    }
+    async ticketCountsForNodes(nodeIds) {
+        return await ticketCountsForNodes([...nodeIds]);
+    }
+    async ticketCountsForView(root) {
+        return this.ticketCountsForNodes([root, ...await view(root)]);
+    }
+    async hasActiveLiveSubscription(nodeId) {
+        return await hasActiveLiveSubscription(nodeId);
+    }
+}
+export const localCanvasSource = new LocalCanvasSource();
+/** The active read source for a command: an explicit `--canvas <name>` wins,
+ *  else the durable `crtr canvas use` selection (`ScopeState.activeCanvas`),
+ *  else local — byte-for-byte the same `localCanvasSource` singleton so a
+ *  caller with neither set sees zero behavior change. */
+export function resolveCanvasSource(opts, sandboxed = isSandboxedNode()) {
+    const scope = opts?.scope ?? 'user';
+    // An app's sandboxed node has no runtime user store and no remote canvas
+    // targets: `crtr canvas use` and `--canvas` are the person's selection.
+    if (sandboxed) {
+        if (opts?.canvasName !== undefined)
+            throw ownerOnly('--canvas selects the person\'s remote canvas targets, which an app\'s node cannot reach', 'Omit --canvas; this node reads its own runtime\'s canvas.');
+        return localCanvasSource;
+    }
+    const name = opts?.canvasName ?? readState(scope).activeCanvas ?? null;
+    if (!name)
+        return localCanvasSource;
+    const { previewEndpoint, relayToken } = resolveRemoteCanvasTarget(name, scope);
+    return new RemoteCanvasSource(previewEndpoint, relayToken);
+}

package/dist/core/canvas/status-glyph.d.ts

@@ -0,0 +1,52 @@
+import type { NodeStatus } from './types.js';
+import { type Fault, type FaultKind } from '../runtime/fault.js';
+export declare const STATUS_GLYPH: Record<NodeStatus, string>;
+export declare const STATUS_COLOR: Record<NodeStatus, string>;
+export declare const HANGING_GLYPH = "\u26A0";
+export declare const HANGING_COLOR = "33";
+/** Short label for the fault kind. The overlay keeps one glyph and lets the
+ *  label carry the distinction. */
+export declare function hangingLabel(kind: FaultKind): string;
+export interface NodeVisual {
+    glyph: string;
+    /** SGR fg parameters, e.g. '32' or '38;5;243' — interpolate as `\x1b[${color}m`. */
+    color: string;
+    /** Overlay word (hanging kind label / 'live'); undefined for a plain status
+     *  (the caller supplies its own status word). */
+    word?: string;
+    bold?: boolean;
+}
+/** Whether a row is frozen: the broker ledger marked it waiting for a slot and
+ *  no process holds it. Both halves matter — a launch clears `frozen_at`, so a
+ *  mark sitting beside a live pid is stale rather than frozen. A projection
+ *  that carries no pid at all (the dashboard row) reads on the mark alone. */
+export declare function isFrozenRow(row: {
+    frozen_at?: string | null;
+    pi_pid?: number | null;
+}): boolean;
+/** Resolve a node's glyph + hue + overlay word, applying the precedence
+ *  hanging > frozen > streaming > status. */
+export declare function resolveNodeVisual(status: NodeStatus, opts: {
+    streaming?: boolean;
+    frozen?: boolean;
+    hanging?: Fault | {
+        kind: FaultKind;
+    } | null;
+}): NodeVisual;
+/** True for exactly the fault dispositions `faultDispositionText` renders as
+ *  "needs you" — nothing (sdk/daemon/client) is auto-driving recovery, so the
+ *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
+ *  `node lifecycle revive --now`, src/commands/node-lifecycle-revive.ts) can gate on the SAME
+ *  predicate the dashboard advertises instead of drifting out of sync with it
+ *  and rejecting exactly the nodes shown as "needs you". */
+export declare function faultNeedsYou(fault: Pick<Fault, 'retry'>): boolean;
+/** Human-friendly active-fault disposition text. `auto` faults show the current
+ *  retry attempt plus the next scheduled retry; client-owned redials say
+ *  `redialing`; everything else says `needs you`. */
+export declare function faultDispositionText(fault: Fault, now?: number): string;
+/** One-line active-fault summary used by the canvas surfaces: `link kind ·
+ *  disposition`. */
+export declare function faultSummary(fault: Fault, now?: number): string;
+/** Elapsed counter used by the browse rail's countdown slot. `faultSummary`
+ *  covers the presenter surfaces; this stays for the rail's existing time text. */
+export declare function hangingCountdown(since: string, now?: number): string;

package/dist/core/canvas/status-glyph.js

@@ -0,0 +1,132 @@
+// status-glyph.ts — the canonical status glyph and color map used by the canvas
+// ASCII forest and interactive browser. The overlay precedence is
+// hanging > frozen > streaming > status. `hanging` and `streaming` are
+// mutually exclusive in practice (hanging means the turn ended, so `busy` is
+// gone) but the precedence is defined regardless. `frozen` outranks `streaming`
+// because a frozen row has no process at all: any streaming read against it is
+// a stale marker, and showing it as active is the lie the freeze state exists
+// to stop telling.
+import { RECESSIVE_FG } from '../tui/draw.js';
+import { FAULT_QUIET_MS } from '../runtime/fault.js';
+// ── Status glyphs (the mono, color-free primary encoding) ─────────────────────
+export const STATUS_GLYPH = {
+    active: '●',
+    idle: '○',
+    done: '✓',
+    dead: '✗',
+    canceled: '⊘',
+};
+// ── Status hue: SGR fg parameters per status. ─────────────────────────────────
+// Reinforces the glyph; the glyph SHAPE stays the NO_COLOR carrier.
+//
+// The four live statuses use basic-16 hues, which every terminal palette renders
+// as a saturated colour. `canceled` cannot: it wants GREY, and basic-16 grey is
+// bright-black — a slot themes routinely set to a value barely off their own
+// background, which is what made every canceled row unreadable. Grey is therefore
+// an explicit 256-colour step (see RECESSIVE_FG) chosen for measured contrast
+// rather than delegated to the palette.
+export const STATUS_COLOR = {
+    active: '32', // green
+    idle: '33', // yellow
+    done: '36', // cyan
+    dead: '31', // red
+    canceled: RECESSIVE_FG,
+};
+// ── Streaming overlay (genuinely mid-turn) — browse's existing statusRail visual.
+const STREAMING_GLYPH = '⟳';
+const STREAMING_COLOR = '92'; // bright green (brighter than active-status green)
+// ── Frozen overlay (waiting on a broker slot: marked, but no process). ───────
+const FROZEN_GLYPH = '◌';
+const FROZEN_COLOR = '94'; // bright blue
+// ── Active-fault overlay (one glyph, kind label carries the detail). ─────────
+export const HANGING_GLYPH = '⚠';
+export const HANGING_COLOR = '33'; // yellow
+/** Short label for the fault kind. The overlay keeps one glyph and lets the
+ *  label carry the distinction. */
+export function hangingLabel(kind) {
+    switch (kind) {
+        case 'rate-limit': return 'rate-limited';
+        case 'overloaded': return 'overloaded';
+        case 'connection': return 'down';
+        case 'auth': return 'auth';
+        case 'protocol': return 'protocol';
+        case 'context-overflow': return 'context-overflow';
+        case 'wedged': return 'wedged';
+        case 'model-not-found': return 'model-not-found';
+        default: return 'other';
+    }
+}
+/** Whether a row is frozen: the broker ledger marked it waiting for a slot and
+ *  no process holds it. Both halves matter — a launch clears `frozen_at`, so a
+ *  mark sitting beside a live pid is stale rather than frozen. A projection
+ *  that carries no pid at all (the dashboard row) reads on the mark alone. */
+export function isFrozenRow(row) {
+    return row.frozen_at != null && row.pi_pid == null;
+}
+/** Resolve a node's glyph + hue + overlay word, applying the precedence
+ *  hanging > frozen > streaming > status. */
+export function resolveNodeVisual(status, opts) {
+    if (opts.hanging != null) {
+        return { glyph: HANGING_GLYPH, color: HANGING_COLOR, word: hangingLabel(opts.hanging.kind), bold: true };
+    }
+    if (opts.frozen === true) {
+        return { glyph: FROZEN_GLYPH, color: FROZEN_COLOR, word: 'frozen' };
+    }
+    if (opts.streaming === true) {
+        return { glyph: STREAMING_GLYPH, color: STREAMING_COLOR, word: 'live', bold: true };
+    }
+    return { glyph: STATUS_GLYPH[status] ?? '?', color: STATUS_COLOR[status] };
+}
+function retryCountdown(iso, now) {
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return 'now';
+    const remaining = at - now;
+    if (remaining <= 0)
+        return 'now';
+    if (remaining >= 60_000)
+        return `${Math.max(1, Math.round(remaining / 60_000))}m`;
+    return `${Math.max(1, Math.ceil(remaining / 1000))}s`;
+}
+/** True for exactly the fault dispositions `faultDispositionText` renders as
+ *  "needs you" — nothing (sdk/daemon/client) is auto-driving recovery, so the
+ *  dashboard flags the node for the human. Exported so a recovery verb (e.g.
+ *  `node lifecycle revive --now`, src/commands/node-lifecycle-revive.ts) can gate on the SAME
+ *  predicate the dashboard advertises instead of drifting out of sync with it
+ *  and rejecting exactly the nodes shown as "needs you". */
+export function faultNeedsYou(fault) {
+    return fault.retry.disposition !== 'auto';
+}
+/** Human-friendly active-fault disposition text. `auto` faults show the current
+ *  retry attempt plus the next scheduled retry; client-owned redials say
+ *  `redialing`; everything else says `needs you`. */
+export function faultDispositionText(fault, now = Date.now()) {
+    const retry = fault.retry;
+    if (!faultNeedsYou(fault)) {
+        if (retry.by === 'client')
+            return 'redialing';
+        const progress = typeof retry.attempt === 'number' && typeof retry.max === 'number'
+            ? `auto-retry ${retry.attempt}/${retry.max}`
+            : 'auto-retrying';
+        return retry.nextAt ? `${progress}, next ${retryCountdown(retry.nextAt, now)}` : progress;
+    }
+    return 'needs you';
+}
+/** One-line active-fault summary used by the canvas surfaces: `link kind ·
+ *  disposition`. */
+export function faultSummary(fault, now = Date.now()) {
+    return `${fault.link} ${hangingLabel(fault.kind)} · ${faultDispositionText(fault, now)}`;
+}
+/** Elapsed counter used by the browse rail's countdown slot. `faultSummary`
+ *  covers the presenter surfaces; this stays for the rail's existing time text. */
+export function hangingCountdown(since, now = Date.now()) {
+    const start = Date.parse(since);
+    if (Number.isNaN(start))
+        return 'retrying…';
+    const remaining = FAULT_QUIET_MS - (now - start);
+    if (remaining <= 0)
+        return 'retrying…';
+    if (remaining >= 60_000)
+        return `retry in ~${Math.max(1, Math.round(remaining / 60_000))}m`;
+    return `retry in ~${Math.ceil(remaining / 1000)}s`;
+}

package/dist/core/canvas/structured-requests.d.ts

@@ -0,0 +1,69 @@
+import type { StructuredRequestDTO, StructuredRequestModeDTO, StructuredRequestStateDTO, StructuredRequestSubmissionDTO } from '../../api/dto/structured-requests.js';
+import type { DeclinedResult, NodeOutcomeDetailV1, TerminalReason } from './types.js';
+import { type CanvasDb } from './db.js';
+export type StructuredRequestFailureReason = TerminalReason | 'node_create_failed' | 'bind_failed' | 'prompt_delivery_failed' | 'node_deadline_exceeded';
+export interface StructuredRequestRow {
+    request_id: string;
+    node_id: string | null;
+    mode: StructuredRequestModeDTO;
+    submission: StructuredRequestSubmissionDTO;
+    dedicated: boolean;
+    state: StructuredRequestStateDTO;
+    schema: Record<string, unknown>;
+    result: unknown | null;
+    deadline_at: number | null;
+    created_at: number;
+    settled_at: number | null;
+    effects_done_at: number | null;
+    result_path: string | null;
+    declined: DeclinedResult | null;
+    failure_reason: StructuredRequestFailureReason | null;
+    failure_detail: NodeOutcomeDetailV1 | null;
+    /** The inbox entry a one-off request arrived in; its subscription ends when the result report lands. */
+    request_message_id: string | null;
+}
+export interface SettleStructuredRequestInput {
+    intended: Exclude<StructuredRequestStateDTO, 'pending'>;
+    now?: number;
+    result?: unknown;
+    declined?: DeclinedResult;
+    failureReason?: StructuredRequestFailureReason;
+    failureDetail?: NodeOutcomeDetailV1 | null;
+}
+export interface SettleStructuredRequestResult {
+    changed: boolean;
+    row: StructuredRequestRow | null;
+}
+/** The daemon installs its post-commit effects here. Core only exposes a committed row. */
+export declare function registerStructuredRequestEffectRunner(runner: (row: StructuredRequestRow) => void): void;
+export declare function runStructuredRequestEffects(row: StructuredRequestRow | null): void;
+export declare function getStructuredRequest(requestId: string): Promise<StructuredRequestRow | null>;
+export declare function getPendingStructuredRequestForNode(nodeId: string): Promise<StructuredRequestRow | null>;
+export declare function admitStructuredRequest(input: {
+    requestId: string;
+    mode: StructuredRequestModeDTO;
+    submission: StructuredRequestSubmissionDTO;
+    dedicated: boolean;
+    schema: Record<string, unknown>;
+    deadlineAt: number | null;
+    nodeId?: string | null;
+    requestMessageId?: string | null;
+    now?: number;
+}): Promise<StructuredRequestRow>;
+/** Bind is conditional so a cancel that won after creation cannot attach its node. */
+export declare function bindStructuredRequest(requestId: string, nodeId: string): Promise<SettleStructuredRequestResult>;
+/** One settlement statement with deadline precedence. Callers that own a wider transaction pass that db. */
+export declare function settleStructuredRequestIn(db: CanvasDb, requestId: string, input: SettleStructuredRequestInput): Promise<SettleStructuredRequestResult>;
+export declare function settleStructuredRequest(requestId: string, input: SettleStructuredRequestInput): Promise<SettleStructuredRequestResult>;
+export declare function settlePendingStructuredRequestForNodeIn(db: CanvasDb, nodeId: string, input: SettleStructuredRequestInput): Promise<SettleStructuredRequestResult>;
+export declare function settlePendingStructuredRequestForNode(nodeId: string, input: SettleStructuredRequestInput): Promise<SettleStructuredRequestResult>;
+export declare function pendingStructuredRequestsPast(now: number): Promise<StructuredRequestRow[]>;
+export declare function incompleteStructuredRequestEffects(): Promise<StructuredRequestRow[]>;
+/** One-off result paths belong to one request; terminal result paths belong to the latest terminal settlement on the node. */
+export declare function ownsStructuredRequestResultProjection(row: StructuredRequestRow): Promise<boolean>;
+/** Declines share one legacy path, so its owner is the latest declined request regardless of submission mode. */
+export declare function ownsStructuredRequestDeclineProjection(row: StructuredRequestRow): Promise<boolean>;
+export declare function markStructuredRequestEffectsDone(requestId: string, resultPath: string | null): Promise<void>;
+/** Legacy node/message schema paths get the same identity and authority. */
+export declare function registerLegacyStructuredRequest(nodeId: string, mode: StructuredRequestSubmissionDTO, schema: Record<string, unknown>, requestMessageId?: string): Promise<StructuredRequestRow>;
+export declare function toStructuredRequestDTO(row: StructuredRequestRow): StructuredRequestDTO;