@north-light/crouter 0.3.154

package/dist/core/canvas/human-work-outbox.js

@@ -0,0 +1,261 @@
+// human-work-outbox.ts — the CONSULT_OUTBOX storage ABI's data-access layer.
+//
+// `consult_outbox` remains the physical table name so live older runtimes keep
+// their storage contract. Code calls the generalized record human work:
+// follow-up work retains its original armed/pending receipting lifecycle, while
+// Visual work reserves its own namespaced statuses and immutable bindings.
+import { readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { submitFollowUpResult, submitVisualResult } from '@crouton-kit/humanloop';
+import { openDb } from './db.js';
+import { getNode } from './canvas.js';
+import { reportsDir } from './paths.js';
+function rowFrom(r) {
+    return {
+        node_id: r['node_id'],
+        dir: r['dir'],
+        root: r['root'],
+        request_id: r['request_id'],
+        work_kind: r['work_kind'],
+        status: r['status'],
+        final_report: r['final_report'] ?? null,
+        interaction_id: r['interaction_id'] ?? null,
+        generation_id: r['generation_id'] ?? null,
+        interaction_snapshot: r['interaction_snapshot'] ?? null,
+        handler_command: r['handler_command'] ?? null,
+        handler_args_json: r['handler_args_json'] ?? null,
+        claim_token: r['claim_token'] ?? null,
+        updated_at: r['updated_at'],
+    };
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Insert a follow-up receipt before its fork launches. `work_kind` is explicit
+ * even though the migration default preserves old inserts, so new code never
+ * depends on a compatibility default. */
+export function armFollowUpWork(opts) {
+    openDb()
+        .prepare("INSERT INTO consult_outbox (node_id, dir, root, request_id, work_kind, status, final_report, updated_at) VALUES (?, ?, ?, ?, 'follow_up', 'armed', NULL, ?)")
+        .run(opts.nodeId, opts.dir, opts.root, opts.requestId, nowIso());
+}
+/** Promote only follow-up work inside the canonical-final transaction. */
+export function promoteFollowUpWork(nodeId, finalReportBasename) {
+    const result = openDb()
+        .prepare("UPDATE consult_outbox SET status = 'pending', final_report = ?, updated_at = ? WHERE node_id = ? AND work_kind = 'follow_up' AND status = 'armed'")
+        .run(finalReportBasename, nowIso(), nodeId);
+    return result.changes > 0;
+}
+export function ackFollowUpWork(nodeId) {
+    openDb().prepare("UPDATE consult_outbox SET status = 'acked', updated_at = ? WHERE node_id = ? AND work_kind = 'follow_up'").run(nowIso(), nodeId);
+}
+export function errorFollowUpWork(nodeId) {
+    openDb().prepare("UPDATE consult_outbox SET status = 'errored', updated_at = ? WHERE node_id = ? AND work_kind = 'follow_up'").run(nowIso(), nodeId);
+}
+export function cancelFollowUpWork(nodeId) {
+    openDb().prepare("UPDATE consult_outbox SET status = 'canceled', updated_at = ? WHERE node_id = ? AND work_kind = 'follow_up'").run(nowIso(), nodeId);
+}
+/** Create or return the one immutable Visual claim for a request. A conflicting
+ * duplicate fails closed; a byte-identical duplicate reuses its original row. */
+export function claimVisualWork(binding) {
+    const db = openDb();
+    const handlerArgsJson = JSON.stringify(binding.handlerArgs);
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const existing = db
+            .prepare("SELECT * FROM consult_outbox WHERE dir = ? AND request_id = ? AND work_kind = 'visual'")
+            .get(binding.dir, binding.requestId);
+        if (existing !== undefined) {
+            const row = rowFrom(existing);
+            const exact = row.root === binding.root
+                && row.interaction_id === binding.interactionId
+                && row.generation_id === binding.generationId
+                && row.interaction_snapshot === binding.interactionSnapshot
+                && row.handler_command === binding.handlerCommand
+                && row.handler_args_json === handlerArgsJson
+                && row.claim_token === binding.claimToken;
+            if (!exact)
+                throw new Error(`conflicting Visual work claim for ${binding.dir}/${binding.requestId}`);
+            db.exec('COMMIT');
+            return { row, created: false };
+        }
+        db.prepare("INSERT INTO consult_outbox (node_id, dir, root, request_id, work_kind, status, final_report, interaction_id, generation_id, interaction_snapshot, handler_command, handler_args_json, claim_token, updated_at) VALUES (?, ?, ?, ?, 'visual', 'visual_armed', NULL, ?, ?, ?, ?, ?, ?, ?)").run(binding.nodeId, binding.dir, binding.root, binding.requestId, binding.interactionId, binding.generationId, binding.interactionSnapshot, binding.handlerCommand, handlerArgsJson, binding.claimToken, nowIso());
+        const row = getHumanWorkRow(binding.nodeId);
+        if (row === null)
+            throw new Error(`Visual work claim disappeared for ${binding.nodeId}`);
+        db.exec('COMMIT');
+        return { row, created: true };
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+/** The future Visual finalizer may promote only its exact armed claim. */
+export function promoteVisualWork(nodeId, finalReportBasename) {
+    const result = openDb()
+        .prepare("UPDATE consult_outbox SET status = 'visual_pending', final_report = ?, updated_at = ? WHERE node_id = ? AND work_kind = 'visual' AND status = 'visual_armed'")
+        .run(finalReportBasename, nowIso(), nodeId);
+    return result.changes > 0;
+}
+/** Retire only an exact Visual request binding; cancellation never creates work. */
+export function retireVisualWork(dir, requestId) {
+    const result = openDb()
+        .prepare("UPDATE consult_outbox SET status = 'visual_retired', updated_at = ? WHERE dir = ? AND request_id = ? AND work_kind = 'visual' AND status IN ('visual_armed', 'visual_pending')")
+        .run(nowIso(), dir, requestId);
+    return result.changes > 0;
+}
+export function getHumanWorkRow(nodeId) {
+    const r = openDb().prepare('SELECT * FROM consult_outbox WHERE node_id = ?').get(nodeId);
+    return r ? rowFrom(r) : null;
+}
+export function getFollowUpWorkRow(nodeId) {
+    const r = openDb()
+        .prepare("SELECT * FROM consult_outbox WHERE node_id = ? AND work_kind = 'follow_up'")
+        .get(nodeId);
+    return r ? rowFrom(r) : null;
+}
+export function listActiveVisualWorkByDir(dir) {
+    return openDb().prepare("SELECT * FROM consult_outbox WHERE dir = ? AND work_kind = 'visual' AND status IN ('visual_armed', 'visual_pending')").all(dir).map(rowFrom);
+}
+export function getVisualWorkByRequest(dir, requestId) {
+    const r = openDb()
+        .prepare("SELECT * FROM consult_outbox WHERE dir = ? AND request_id = ? AND work_kind = 'visual'")
+        .get(dir, requestId);
+    return r ? rowFrom(r) : null;
+}
+export function listPendingFollowUpWork() {
+    return openDb().prepare("SELECT * FROM consult_outbox WHERE work_kind = 'follow_up' AND status = 'pending'").all().map(rowFrom);
+}
+export function listArmedFollowUpWork() {
+    return openDb().prepare("SELECT * FROM consult_outbox WHERE work_kind = 'follow_up' AND status = 'armed'").all().map(rowFrom);
+}
+export function getActiveFollowUpWorkByRequest(dir, requestId) {
+    const r = openDb()
+        .prepare("SELECT * FROM consult_outbox WHERE dir = ? AND request_id = ? AND work_kind = 'follow_up' AND status IN ('armed', 'pending') LIMIT 1")
+        .get(dir, requestId);
+    return r ? rowFrom(r) : null;
+}
+export function listActiveFollowUpWorkByDir(dir) {
+    return openDb().prepare("SELECT * FROM consult_outbox WHERE dir = ? AND work_kind = 'follow_up' AND status IN ('armed', 'pending')").all(dir).map(rowFrom);
+}
+function stripReportFrontmatter(raw) {
+    const match = /^---\nnode: [^\n]*\nkind: [^\n]*\nts: [^\n]*\n---\n/.exec(raw);
+    return match ? raw.slice(match[0].length) : raw;
+}
+/** Deliver one pending follow-up receipt. */
+export function dispatchFollowUpWork(nodeId) {
+    const row = getHumanWorkRow(nodeId);
+    if (row === null || row.work_kind !== 'follow_up' || row.status !== 'pending')
+        return;
+    let markdown = null;
+    let readError = null;
+    if (row.final_report === null) {
+        readError = 'consultation produced no final report';
+    }
+    else {
+        try {
+            markdown = stripReportFrontmatter(readFileSync(join(reportsDir(nodeId), row.final_report), 'utf8'));
+        }
+        catch (err) {
+            readError = err.message;
+        }
+    }
+    try {
+        if (markdown !== null)
+            submitFollowUpResult(row.root, row.dir, { requestId: row.request_id, status: 'ready', markdown });
+        else
+            submitFollowUpResult(row.root, row.dir, { requestId: row.request_id, status: 'error', error: readError ?? 'consultation failed' });
+    }
+    catch {
+        return;
+    }
+    ackFollowUpWork(nodeId);
+}
+function visualSubmission(row, outcome) {
+    if (row.interaction_id === null || row.generation_id === null || row.interaction_snapshot === null || row.claim_token === null)
+        throw new Error('Visual work row lacks immutable correlation');
+    const interaction = JSON.parse(row.interaction_snapshot);
+    submitVisualResult(row.root, row.dir, {
+        requestId: row.request_id,
+        generationId: row.generation_id,
+        interactionId: row.interaction_id,
+        interaction,
+        claimToken: row.claim_token,
+        ...outcome,
+    });
+}
+/** Dispatch a checked canonical final as the single correlated Visual result. */
+export function dispatchVisualWork(nodeId) {
+    const row = getHumanWorkRow(nodeId);
+    if (row === null || row.work_kind !== 'visual' || row.status !== 'visual_pending')
+        return;
+    try {
+        const node = getNode(nodeId);
+        if (node === null || node.final_report === null || row.final_report === null || node.final_report !== row.final_report || basename(row.final_report) !== row.final_report)
+            throw new Error('Visual work produced no canonical final report');
+        const raw = readFileSync(join(reportsDir(nodeId), row.final_report), 'utf8');
+        const match = new RegExp(`^---\\nnode: ${nodeId}\\nkind: final\\nts: ([^\\n]+)\\n---\\n([\\s\\S]*)$`).exec(raw);
+        if (match === null || Number.isNaN(Date.parse(match[1])) || match[2].trim() === '')
+            throw new Error('Visual work produced an invalid final report');
+        visualSubmission(row, { status: 'ready', markdown: match[2] });
+    }
+    catch (error) {
+        try {
+            visualSubmission(row, { status: 'error', error: `Visual generation failed: ${String(error)}`.slice(0, 8_192) });
+        }
+        catch {
+            return;
+        }
+    }
+    retireVisualWork(row.dir, row.request_id);
+}
+/** Reconcile this durable lane after a dead private child or interrupted dispatch. */
+export function reconcileVisualWork() {
+    const rows = openDb().prepare("SELECT * FROM consult_outbox WHERE work_kind = 'visual' AND status IN ('visual_armed', 'visual_pending')").all();
+    for (const row of rows.map(rowFrom)) {
+        try {
+            if (row.status === 'visual_pending') {
+                dispatchVisualWork(row.node_id);
+                continue;
+            }
+            const node = getNode(row.node_id);
+            // A fork_pending child is intentionally persisted as canceled until the
+            // start handler rechecks its request and reviveNode consumes this armed
+            // claim. Visual cancellation retires the claim before canceling its node,
+            // so an armed fork in this state remains launchable.
+            if (node?.status === 'canceled' && node.private_fork_phase === 'fork_pending')
+                continue;
+            if (node === null || node.status === 'dead' || node.status === 'canceled') {
+                visualSubmission(row, { status: 'error', error: 'Visual generation could not complete' });
+                retireVisualWork(row.dir, row.request_id);
+            }
+        }
+        catch { /* retain the immutable claim for a later reconciliation */ }
+    }
+}
+/** Reconcile only follow-up work. */
+export function reconcileFollowUpWork() {
+    for (const row of listPendingFollowUpWork()) {
+        try {
+            dispatchFollowUpWork(row.node_id);
+        }
+        catch {
+            /* best-effort — never let one receipt block the rest */
+        }
+    }
+    for (const row of listArmedFollowUpWork()) {
+        try {
+            const node = getNode(row.node_id);
+            const deadOrMissing = node === null || node.status === 'dead' || node.status === 'canceled';
+            const hasFinal = node !== null && node.final_report !== null && node.final_report !== undefined;
+            if (deadOrMissing && !hasFinal) {
+                submitFollowUpResult(row.root, row.dir, { requestId: row.request_id, status: 'error', error: 'consultation could not complete' });
+                errorFollowUpWork(row.node_id);
+            }
+        }
+        catch {
+            /* leave the armed receipt retryable */
+        }
+    }
+}

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

@@ -0,0 +1,11 @@
+export * from './types.js';
+export * from './labels.js';
+export * from './paths.js';
+export * from './canvas.js';
+export * from './source.js';
+export * from './history.js';
+export * from './focuses.js';
+export * from './crons.js';
+export * from './human-work-outbox.js';
+export * from './telemetry.js';
+export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

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

package/dist/core/canvas/install-id.d.ts

@@ -0,0 +1,9 @@
+/** 4-16 lowercase [a-z0-9] characters — the shape both an env-supplied and a
+ *  self-minted install id must satisfy. */
+export declare function isValidInstallId(id: string): boolean;
+/** 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. Single-writer transaction (mirrors
+ *  `reconcileBootLiveness` in boot.ts). `env` is injectable for tests. */
+export declare function resolveInstallId(env?: NodeJS.ProcessEnv): string;

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

@@ -0,0 +1,84 @@
+// 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) — same single-writer `BEGIN IMMEDIATE` transaction idiom,
+// copied from `reconcileBootLiveness`.
+//
+// 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 { openDb } 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;
+}
+function readInstallId(db) {
+    const row = db.prepare('SELECT value FROM canvas_meta WHERE key = ?').get(INSTALL_ID_KEY);
+    return row?.value ?? null;
+}
+function writeInstallId(db, id) {
+    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. Single-writer transaction (mirrors
+ *  `reconcileBootLiveness` in boot.ts). `env` is injectable for tests. */
+export function resolveInstallId(env = process.env) {
+    const db = openDb();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const stored = 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).`);
+            }
+            db.exec('COMMIT');
+            return stored;
+        }
+        let resolved;
+        if (injected !== null) {
+            if (!isValidInstallId(injected)) {
+                throw new Error(`CRTR_INSTALL_ID='${injected}' is not a valid install id — expected 4-16 lowercase [a-z0-9] characters.`);
+            }
+            resolved = injected;
+        }
+        else {
+            resolved = mintInstallId();
+        }
+        writeInstallId(db, resolved);
+        db.exec('COMMIT');
+        return resolved;
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            /* best-effort — nothing was committed, or already rolled back above */
+        }
+        throw err;
+    }
+}

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

@@ -0,0 +1,28 @@
+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 and by anything
+ *  else carrying name + kind (description optional). */
+export interface NamedNode {
+    name: string;
+    kind: string;
+    description?: 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
+ *  the node's human task name only; persona lives in the editor's bottom-right
+ *  badge. Recomputed from meta on every revive and pushed live when naming
+ *  generates the first task description. */
+export declare function editorLabel(meta: NodeMeta): string;

package/dist/core/canvas/labels.js

@@ -0,0 +1,38 @@
+// 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) — the same string the editor
+// label, the canvas dashboard tree, the nav spine, and the tmux window tab all
+// render, so a node reads identically everywhere it appears.
+/** 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
+ *  the node's human task name only; persona lives in the editor's bottom-right
+ *  badge. Recomputed from meta on every revive and pushed live when naming
+ *  generates the first task description. */
+export function editorLabel(meta) {
+    return fullName(meta);
+}

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,98 @@
+// Durable node-meta file primitives shared by normal canvas writes and forward migrations.
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+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) {
+    const lock = `${path}.lock`;
+    const wait = new Int32Array(new SharedArrayBuffer(4));
+    const deadline = Date.now() + 5_000;
+    for (;;) {
+        try {
+            mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || Date.now() >= deadline)
+                throw error;
+            Atomics.wait(wait, 0, 0, 10);
+        }
+    }
+    try {
+        return operation();
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+}
+/** 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`;
+    const fd = openSync(tmp, 'w');
+    try {
+        writeSync(fd, JSON.stringify(value, null, 2));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+    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-model.d.ts

@@ -0,0 +1,55 @@
+import { type FlatRow, type FoldState, type SubtreeActivity } from './nav-render.js';
+import type { NodeMeta, SubscriptionRef } from './index.js';
+export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REVERSE, BG_ATTACHED, GREEN, RED, YELLOW, CYAN, GRAY, nodeGlyph, visibleWidth, truncate, fillWidth, fillBar, readTelemetry, fmtTokens, tokensCell, activityCell, cycleBadge, navLabel, shortId, askBadge, liveBelowBadge, isAttached, hasBrokerViewers, fetchAsksMap, graphWidgetBudget, GRAPH_HINT, type Telemetry, type FlatRow, type FoldState, type SubtreeActivity, } from './nav-render.js';
+export declare function beginFrame(): void;
+/** getNode memoized for the current frame (meta.json read + sqlite row). */
+export declare function cNode(id: string): NodeMeta | null;
+/** subscriptionsOf (a node's reports) memoized for the current frame. */
+export declare function cSubscriptions(id: string): SubscriptionRef[];
+/** subscribersOf (a node's managers) memoized for the current frame. */
+export declare function cSubscribers(id: string): SubscriptionRef[];
+/** First manager (by created) — the UP step for the ancestry spine. */
+export declare function managerOf(id: string): string | undefined;
+/** A kind:'human' node is a control-plane ASK (a humanloop deck on the human's
+ *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
+ *  boots a confused blank "you have been revived" pi. Its pending-ask signal
+ *  already rides the ⚑ badge on the ASKING node (attention.ts follows the
+ *  bridge node's parent relation), so the row carries no signal of its
+ *  own. Drop it from every navigable list (the tree, BASE reports, child counts,
+ *  subtree expansion) so it can never be selected. */
+export declare function isHumanAsk(id: string): boolean;
+/** A node's direct children that are navigable conversations — human-ask nodes
+ *  dropped. The one place the nav chrome enumerates children. */
+export declare function convoChildIds(id: string): string[];
+/** Live reports (active|idle) of a node — the DOWN set in BASE. */
+export declare function liveReports(id: string): string[];
+/** Direct navigable children — used for the ⤳ badge (human-ask nodes excluded,
+ *  so the count matches what the tree actually shows). */
+export declare function childCount(id: string): number;
+/** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
+export declare function climbRoot(self: string): string;
+/** Space-joined ids of a node's subtree (cursor-relative {subtree} var). */
+export declare function subtreeIds(root: string): string[];
+/** ⤳M direct-children badge — the single child-count signal, shown on any row
+ *  with navigable children (folded or not). In GRAPH the ▸ caret separately marks
+ *  a collapsed row, so this stays a pure count and never doubles as a fold badge. */
+export declare function childBadge(node: NodeMeta | null): string;
+/** Sort rank for sibling ordering — live nodes (active, then idle) ahead of
+ *  terminal ones, so sessions still running surface at the TOP of each child
+ *  group instead of being buried under finished/failed ones. */
+export declare function statusRank(id: string): number;
+/** Direct children, live-first — the sibling order used both when flattening
+ *  the tree and when stepping into a subtree (`l`). Array.sort is stable, so
+ *  equal-status siblings keep their creation order. */
+export declare function sortedChildIds(id: string): string[];
+export declare function computeSubtreeActivity(root: string, self: string): SubtreeActivity;
+/** Fold policy alone — thin wrapper over computeSubtreeActivity for the keypress
+ *  path (buildGraphModel without a precomputed set). The render path computes the
+ *  activity once and threads `expand` in, so it never recomputes here. */
+export declare function computeDefaultExpanded(root: string, self: string): Set<string>;
+export declare function buildGraphModel(self: string, folds: FoldState, expand?: ReadonlySet<string>): FlatRow[];
+/** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ATTACHED
+ *  (human-watched) node → a coloured background bar; SELF → bold name. The
+ *  cursor outranks the attached tint when both land on the same row. The
+ *  overlay-aware glyph alone carries the live signal (status / ⟳ / ⚠). */
+export declare function renderGraphRow(r: FlatRow, isCursor: boolean, focused: ReadonlySet<string>, activeBelow: ReadonlyMap<string, number>, asks: Record<string, number>): string;