@north-light/api 0.3.580 → 0.3.588

package/dist/core/canvas/nav-render.js

@@ -0,0 +1,224 @@
+// nav-render.ts — the pure render half of the nav model.
+//
+// Everything here is canvas-db-free. Telemetry, fault, and streaming fields are
+// projected onto node rows by crtrd; only attach.json remains a local viewer cue.
+// No `getNode`/`subscriptionsOf`/`listFocuses` — the graph-walking half lives in
+// nav-model.ts (which re-exports these helpers for its own callers).
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { nodeRunDir, nodeRunJobDir } from './paths.js';
+import { readFileBeneath } from '../spaces/open-beneath.js';
+import { isFrozenRow, resolveNodeVisual } from './status-glyph.js';
+// Tuning constants
+/** pi's InteractiveMode.MAX_WIDGET_LINES — the hard cap on lines in a string
+ *  array widget; anything beyond it pi truncates with its own "... (widget
+ *  truncated)". Our GRAPH viewport stays at/under this and scrolls internally. */
+export const PI_MAX_WIDGET_LINES = 10;
+export const VIEWPORT_FALLBACK_ROWS = 30;
+// ANSI styling. pi renders embedded escapes in widget lines and measures width
+// ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
+// (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
+// NO_COLOR; the attached-row tint is a background COLOUR, while the overlay-
+// aware glyph (●/○/✓/✗/⟳/⚠) carries the live signal independently, even where
+// colour is stripped.
+export const ESC = '\x1b[';
+export const RESET = `${ESC}0m`;
+export const BOLD = `${ESC}1m`;
+export const DIM = `${ESC}2m`;
+export const REVERSE = `${ESC}7m`;
+/** Dark-green background bar marking an ATTACHED node (a human is currently
+ *  watching it) — distinct from the cursor's reverse-video bar; chosen so
+ *  default-fg text stays readable. */
+export const BG_ATTACHED = `${ESC}48;5;22m`;
+export const GREEN = `${ESC}32m`;
+export const RED = `${ESC}31m`;
+export const YELLOW = `${ESC}33m`;
+export const CYAN = `${ESC}36m`;
+export const GRAY = `${ESC}90m`;
+function streamingFor(node) {
+    if (node.status !== 'active' && node.status !== 'idle')
+        return false;
+    // The projected field is the live execution's open turn AND-ed with broker-pid
+    // liveness, so a witness left by a crashed pi reads false.
+    return node.streaming === true;
+}
+/** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
+ *  outranks the base status glyph. Every input is a projected row field — the
+ *  owning daemon computed `fault`/`streaming` — so this holds for a remote node
+ *  too, with no local read keyed on a node id that may collide. */
+export function nodeGlyph(node) {
+    if (node === null)
+        return '?';
+    const v = resolveNodeVisual(node.status, {
+        streaming: streamingFor(node),
+        frozen: isFrozenRow(node),
+        hanging: node.fault ?? null,
+    });
+    return `${ESC}${v.color}m${v.glyph}${RESET}`;
+}
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Drop every SGR sequence, keeping the visible text. The selection bar uses
+ *  this: reverse-video INVERTS a coloured cell into a coloured block, so a row
+ *  built from tinted spans highlights as a patchwork of background swatches
+ *  instead of one bar. Stripping colour first leaves a single clean bar — the
+ *  glyphs (●/○/✓/✗/⚙/◷) still carry the signal, exactly as under NO_COLOR. */
+export function stripSgr(s) {
+    return s.replace(ANSI_RE, '');
+}
+/** Visible width, ignoring ANSI escapes. */
+export function visibleWidth(s) {
+    return s.replace(ANSI_RE, '').length;
+}
+/** Truncate to `max` VISIBLE columns: escape sequences are copied through
+ *  verbatim (so a cut never lands mid-escape) and the result always ends in
+ *  RESET, so a clipped style can't bleed into the editor below. */
+export function truncate(s, max = fillWidth()) {
+    if (visibleWidth(s) <= max)
+        return s;
+    let out = '';
+    let w = 0;
+    let i = 0;
+    while (i < s.length && w < max - 1) {
+        if (s[i] === '\x1b') {
+            const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
+            if (m) {
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        out += s[i];
+        w++;
+        i++;
+    }
+    return `${out}…${RESET}`;
+}
+/** Visible columns available to ONE widget line — the cap for every line we
+ *  emit, and the width a full-width reverse-video SELF bar fills to.
+ *
+ *  pi does NOT clip widget lines; it WRAPS them. Each string line is wrapped in
+ *  a `Text(paddingX = 1)` inside a full-terminal-width container, so the usable
+ *  content width is `columns - 2` (a 1-col margin on each side). A line wider
+ *  than that wraps, and the overflow spills onto a second row as a stray
+ *  reverse-video block (the bug this guards against). Clamp to `columns - 2`. */
+export function fillWidth() {
+    return Math.max(20, Math.min((process.stdout.columns ?? 80) - 2, 180));
+}
+/** Wrap `content` in a full-width background bar opened by `open` (REVERSE for
+ *  the cursor, BG_ATTACHED for a human-watched node). `open` is re-asserted after every
+ *  embedded RESET so a coloured cell (the status dot) can't punch a hole in the
+ *  bar; the visible width is padded out to `width`; the line closes with a real
+ *  RESET so the style never bleeds into the editor below. */
+export function fillBar(content, width, open) {
+    const clipped = truncate(content, width);
+    const reasserted = clipped.replace(/\x1b\[0m/g, `${RESET}${open}`);
+    const pad = Math.max(0, width - visibleWidth(clipped));
+    return `${open}${reasserted}${' '.repeat(pad)}${RESET}`;
+}
+export function fmtTokens(n) {
+    return n < 1_000 ? `${n}` : `${Math.round(n / 1_000)}k`;
+}
+/** The context-window cell — live window fill rounded to the nearest 1k (the same
+ * figure pi's footer shows), NOT a per-turn delta. Remote canvases retain the
+ * existing safe 0 display rather than treating a local node id as remote state. */
+export function tokensCell(node, remote = false) {
+    return fmtTokens(remote ? 0 : (node?.telemetry_context_tokens ?? 0));
+}
+/** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
+ * Empty for non-active rows and when none is recorded. */
+export function activityCell(node, remote = false) {
+    if (remote || node?.status !== 'active')
+        return '';
+    const activity = (node.telemetry_last_activity ?? '').trim();
+    return activity === '' ? '' : ` ${DIM}· ${activity}${RESET}`;
+}
+/** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
+export function cycleBadge(node) {
+    const c = node?.cycles ?? 0;
+    return c > 0 ? ` ${DIM}⟳${c}${RESET}` : '';
+}
+/** Short on-screen label: the explicit handle when set, else the pi-generated
+ *  description, else the bare name. fullName joins BOTH (`handle description`);
+ *  the nav chrome shows just the first so rows stay compact. */
+export function navLabel(node, id) {
+    if (node === null)
+        return shortId(id);
+    const handle = node.name && node.name !== node.kind ? node.name : '';
+    if (handle !== '')
+        return handle;
+    const desc = (node.description ?? '').trim();
+    return desc !== '' ? desc : node.name;
+}
+export function shortId(id) {
+    return id.slice(0, 8);
+}
+/** True when a human is watching `id` right now via the broker viewer count
+ *  (attach.json). The tmux-focus axis (a `focuses` row) is a canvas-db read and
+ *  stays in nav-model's `isAttached`, which ORs this signal with the focus set.
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export function hasBrokerViewers(id, node, remote = false) {
+    if (remote)
+        return false;
+    if (node?.status !== 'active')
+        return false; // stale attach.json from a crash
+    try {
+        const rec = JSON.parse(readFileBeneath(nodeRunDir(id), join(nodeRunJobDir(id), 'attach.json')).toString('utf8'));
+        return typeof rec.viewers === 'number' && rec.viewers > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `focused` is the tmux-focus set (a canvas-db read the caller supplies). The
+ *  broker-viewer half is a pure `attach.json` read. `remote` skips the local read
+ *  entirely and reports false (a remote node id may collide with a local one). */
+export function isAttached(id, node, focused, remote = false) {
+    if (remote)
+        return false;
+    if (focused.has(id))
+        return true;
+    return hasBrokerViewers(id, node, remote);
+}
+/** ⚑K pending-asks badge for a node, read from the supplied per-node ask map. */
+export function askBadge(id, asks) {
+    const k = asks[id] ?? 0;
+    return k > 0 ? ` ${YELLOW}⚑${k}${RESET}` : '';
+}
+/** "Live work below" badge — green ⇣N when this node is NOT itself active but has
+ *  N active descendants. The one signal that an idle/parked node isn't dead: real
+ *  work is still running beneath it. Count comes from the single subtree-activity
+ *  pass (no per-row walk). Suppressed on active rows (their own ● already says so). */
+export function liveBelowBadge(node, activeBelow) {
+    if (node === null || node.status === 'active')
+        return '';
+    const n = activeBelow.get(node.node_id) ?? 0;
+    return n > 0 ? ` ${GREEN}⇣${n}${RESET}` : '';
+}
+// Per-node ask counts — ONE shell-out per poll. `crtr canvas attention map`
+// buckets a whole sub-DAG's pending asks by node in a single process, so the
+// timer stays cheap (< 2 s) regardless of how many nodes are visible. --json
+// gives a parseable {counts} blob (the default render is XML chrome).
+export function fetchAsksMap(rootId) {
+    try {
+        const raw = execFileSync('crtr', ['canvas', 'attention', 'map', '--view', rootId, '--json'], {
+            timeout: 2_500,
+            encoding: 'utf8',
+        });
+        const parsed = JSON.parse(raw.trim());
+        return parsed.counts ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
+ *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own
+ *  scroll chrome — so never exceed it (and shrink on a very short terminal).
+ *  The viewport scrolls WITHIN this cap as the cursor moves. */
+export function graphWidgetBudget() {
+    const rows = process.stdout.rows ?? VIEWPORT_FALLBACK_ROWS;
+    return Math.max(4, Math.min(PI_MAX_WIDGET_LINES, rows - 4));
+}
+export const GRAPH_HINT = `${DIM}jk move · hl fold · ↵ focus · e expand · x kill · m mgr · esc${RESET}`;

package/dist/core/canvas/node-agent-paths.d.ts

@@ -0,0 +1,8 @@
+/** Resolve an existing node's app from the sole durable assignment, its row.
+ * Brokers have only their own app in their launch environment, not the DB. */
+export declare function appForNode(nodeId: string): Promise<string>;
+export declare function nodeAgentDir(nodeId: string, grantee?: string): Promise<string>;
+export declare function contextDir(nodeId: string, grantee?: string): Promise<string>;
+export declare function reportsDir(nodeId: string, grantee?: string): Promise<string>;
+export declare function interpolateNodePaths(text: string, nodeId: string): Promise<string>;
+export declare function ensureNodeDirs(nodeId: string, grantee?: string): Promise<void>;

package/dist/core/canvas/node-agent-paths.js

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+import { envGrantee, envNodeId } from '../../shared/env.js';
+import { openDb } from './db.js';
+import { nodeAgentDir as agentDirForApp, ensureNodeDirs as ensureDirsForApp, interpolateNodePaths as interpolatePathsForApp } from './paths.js';
+/** Resolve an existing node's app from the sole durable assignment, its row.
+ * Brokers have only their own app in their launch environment, not the DB. */
+export async function appForNode(nodeId) {
+    const ownApp = envGrantee();
+    if (envNodeId() === nodeId && ownApp)
+        return ownApp;
+    const row = await (await openDb()).prepare('SELECT grantee FROM node_rows WHERE node_id = ?').get(nodeId);
+    if (!row?.grantee)
+        throw new Error(`node ${nodeId} has no app assignment`);
+    return row.grantee;
+}
+export async function nodeAgentDir(nodeId, grantee) {
+    return agentDirForApp(nodeId, grantee ?? await appForNode(nodeId));
+}
+export async function contextDir(nodeId, grantee) {
+    return join(await nodeAgentDir(nodeId, grantee), 'context');
+}
+export async function reportsDir(nodeId, grantee) {
+    return join(await nodeAgentDir(nodeId, grantee), 'reports');
+}
+export async function interpolateNodePaths(text, nodeId) {
+    return interpolatePathsForApp(text, nodeId, await appForNode(nodeId));
+}
+export async function ensureNodeDirs(nodeId, grantee) {
+    ensureDirsForApp(nodeId, grantee ?? await appForNode(nodeId));
+}

package/dist/core/canvas/node-order.d.ts

@@ -0,0 +1,24 @@
+import type { NodeStatus, Lifecycle } from './types.js';
+/** Sort live work before terminal work; unknown statuses sort last. */
+export declare function statusRank(status: NodeStatus | undefined): number;
+/** True when the node has a broker the daemon supervises — the statuses that
+ *  mean "a live engine is (or should be) running right now". */
+export declare function isLiveStatus(status: NodeStatus | undefined): boolean;
+/** True when a node's work is FINISHED — a terminal one-shot worker, or any node
+ *  that pushed a final report.
+ *
+ *  This is deliberately NOT "is it running": a non-live status alone conflates two
+ *  unrelated situations. Finished work is archive — opening it is inspection, and
+ *  relaunching it puts a completed worker back to work (the stop-guard reprompts a
+ *  terminal node that never pushed a final). A RESIDENT node with no final report
+ *  is the opposite: its `done` is only `markCleanExitDone` recording a clean broker
+ *  exit, which the stop-guard itself rules a legitimate stop (`reason: 'dormant'`),
+ *  so it never finished anything and resuming it is simply reopening a conversation.
+ *
+ *  `lifecycle` is optional because DashboardRow only carries it on the full browser
+ *  snapshot; absent, this answers `true` (treat as finished), keeping the caller on
+ *  the conservative inspect-don't-revive path. */
+export declare function isFinishedWork(node: {
+    lifecycle?: Lifecycle;
+    finalized: boolean;
+}): boolean;

package/dist/core/canvas/node-order.js

@@ -0,0 +1,37 @@
+// node-order.ts — canonical ordering and status/lifecycle classification for
+// canvas nodes. Pure (type-only imports) so every surface — the browser model,
+// command leaves, renderers — can share one answer to "is this node live?" and
+// "did this node finish?" without reaching the db.
+/** Sort live work before terminal work; unknown statuses sort last. */
+export function statusRank(status) {
+    switch (status) {
+        case 'active': return 0;
+        case 'idle': return 1;
+        case 'done': return 2;
+        case 'canceled': return 3;
+        case 'dead': return 4;
+        default: return 5;
+    }
+}
+/** True when the node has a broker the daemon supervises — the statuses that
+ *  mean "a live engine is (or should be) running right now". */
+export function isLiveStatus(status) {
+    return status === 'active' || status === 'idle';
+}
+/** True when a node's work is FINISHED — a terminal one-shot worker, or any node
+ *  that pushed a final report.
+ *
+ *  This is deliberately NOT "is it running": a non-live status alone conflates two
+ *  unrelated situations. Finished work is archive — opening it is inspection, and
+ *  relaunching it puts a completed worker back to work (the stop-guard reprompts a
+ *  terminal node that never pushed a final). A RESIDENT node with no final report
+ *  is the opposite: its `done` is only `markCleanExitDone` recording a clean broker
+ *  exit, which the stop-guard itself rules a legitimate stop (`reason: 'dormant'`),
+ *  so it never finished anything and resuming it is simply reopening a conversation.
+ *
+ *  `lifecycle` is optional because DashboardRow only carries it on the full browser
+ *  snapshot; absent, this answers `true` (treat as finished), keeping the caller on
+ *  the conservative inspect-don't-revive path. */
+export function isFinishedWork(node) {
+    return node.lifecycle !== 'resident' || node.finalized;
+}

package/dist/core/canvas/node-recap.d.ts

@@ -0,0 +1,23 @@
+export interface NodeRecap {
+    /** What this conversation is for — the recap's `Goal:` line. */
+    goal: string;
+    /** Where it actually stands — the recap's `State:` line. */
+    state: string;
+    /** ISO 8601 stamp of when the briefing was generated. */
+    at: string;
+}
+/** Split the model's two-line briefing into its labelled halves. Returns null for
+ *  anything that doesn't yield at least one non-empty line — a garbled recap is
+ *  worse than none, so it is never stored. Missing labels fall back to line order
+ *  (the prompt asks for Goal first, State second). */
+export declare function parseRecapBriefing(briefing: string): {
+    goal: string;
+    state: string;
+} | null;
+/** Persist a generated briefing. A failed write leaves the prior recap intact
+ * and must be reported to the broker before it paints the replacement. */
+export declare function writeNodeRecap(nodeId: string, briefing: string): void;
+/** The node's stored briefing, or undefined when it never generated one (a node
+ *  that finished before its first idle window, or one last run before this file
+ *  existed). Never throws. */
+export declare function readNodeRecap(nodeId: string): NodeRecap | undefined;

package/dist/core/canvas/node-recap.js

@@ -0,0 +1,62 @@
+// node-recap.ts — the node's last Goal/State briefing, persisted.
+//
+// The recap itself is generated in the broker (`pi-extensions/canvas-recap.ts`)
+// and painted above the editor as throwaway chrome. That widget lives in broker
+// memory, so the moment a node goes dormant its briefing is gone — which is
+// exactly when a developer scanning `crtr canvas browse` needs it most ("what was
+// this one for, and where did it stop?"). Persisting the two lines the viewer
+// already produced makes them readable without a broker and without a model call.
+//
+// Stored beside telemetry in `job/` because it is machine-generated runtime
+// state, not a document the node authored: safe to delete, rebuilt on the node's
+// next idle recap. `context/` stays the agent's own document space.
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { jobDir } from './paths.js';
+import { readJsonIfExists, atomicWriteJson } from '../fs-utils.js';
+function recapPath(nodeId) {
+    return join(jobDir(nodeId), 'recap.json');
+}
+/** Strip one leading `Goal:` / `State:` label from a briefing line. */
+function stripLabel(line) {
+    return line.replace(/^\s*(goal|state)\s*:\s*/i, '').trim();
+}
+/** Split the model's two-line briefing into its labelled halves. Returns null for
+ *  anything that doesn't yield at least one non-empty line — a garbled recap is
+ *  worse than none, so it is never stored. Missing labels fall back to line order
+ *  (the prompt asks for Goal first, State second). */
+export function parseRecapBriefing(briefing) {
+    const lines = briefing.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+    if (lines.length === 0)
+        return null;
+    const labelled = (prefix) => lines.find((l) => new RegExp(`^${prefix}\\s*:`, 'i').test(l));
+    const goalLine = labelled('goal') ?? lines[0];
+    const stateLine = labelled('state') ?? (lines[1] !== goalLine ? lines[1] : undefined);
+    const goal = goalLine === undefined ? '' : stripLabel(goalLine);
+    const state = stateLine === undefined ? '' : stripLabel(stateLine);
+    if (goal === '' && state === '')
+        return null;
+    return { goal, state };
+}
+/** Persist a generated briefing. A failed write leaves the prior recap intact
+ * and must be reported to the broker before it paints the replacement. */
+export function writeNodeRecap(nodeId, briefing) {
+    const parsed = parseRecapBriefing(briefing);
+    if (parsed === null)
+        throw new TypeError('recap briefing has no goal or state');
+    mkdirSync(jobDir(nodeId), { recursive: true });
+    atomicWriteJson(recapPath(nodeId), { ...parsed, at: new Date().toISOString() });
+}
+/** The node's stored briefing, or undefined when it never generated one (a node
+ *  that finished before its first idle window, or one last run before this file
+ *  existed). Never throws. */
+export function readNodeRecap(nodeId) {
+    const raw = readJsonIfExists(recapPath(nodeId));
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const goal = typeof raw.goal === 'string' ? raw.goal : '';
+    const state = typeof raw.state === 'string' ? raw.state : '';
+    if (goal === '' && state === '')
+        return undefined;
+    return { goal, state, at: typeof raw.at === 'string' ? raw.at : '' };
+}

package/dist/core/canvas/node-tokens.d.ts

@@ -0,0 +1,19 @@
+import { type CanvasDb } from './db.js';
+export interface NodePrincipal {
+    app: string;
+    node: string;
+    run: string | null;
+    uid: number;
+    sub: string;
+    grant: string | null;
+    client_id: string | null;
+    scopes: string[] | null;
+}
+export declare function mintNodeToken(db: CanvasDb, executionId: string, nodeId: string, issuedAt: string): Promise<string>;
+/** Mints the node token of a `launching` execution in its own canvas write: what a runner's `start` hands to the process it launches. */
+export declare const mintExecutionToken: (executionId: string, nodeId: string) => Promise<string>;
+/** A stopped or superseded execution can never authenticate, even after restart. */
+export declare function resolveNodeToken(token: string): Promise<NodePrincipal | null>;
+export declare function revokeExitedNodeToken(executionId: string): Promise<void>;
+export declare function revokePriorEpochNodeTokens(epoch: string): Promise<void>;
+export declare function revokeNodeTokens(db: CanvasDb, where: 'broker_process_id' | 'node_id', id: string, at: string): Promise<void>;

package/dist/core/canvas/node-tokens.js

@@ -0,0 +1,53 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { openDb, withCanvasWrite } from './db.js';
+import { terminalGrant } from '../grants/mirror.js';
+import { personIdAsync } from './person.js';
+import { uidForApp } from '../spaces/users.js';
+// The database stores token hashes, never a recoverable token. The raw token is
+// returned once to the caller of `mintNodeToken` (the runner's hand-off) and kept nowhere.
+const hash = (token) => createHash('sha256').update(token).digest('hex');
+export async function mintNodeToken(db, executionId, nodeId, issuedAt) {
+    const node = await db.prepare('SELECT grantee, sub, grant_id, client_id, scopes_json, run_id FROM node_rows WHERE node_id = ?').get(nodeId);
+    if (!node)
+        throw new Error(`cannot mint node token: missing node ${nodeId}`);
+    const root = node.run_id && node.run_id !== nodeId ? await db.prepare('SELECT sub, grant_id, client_id FROM nodes WHERE node_id = ?').get(node.run_id) : undefined;
+    // The person is the node's own (its run root's, else its row's): on the fleet runtime the minting lane has no request person.
+    const person = root?.sub ?? node.sub ?? await personIdAsync();
+    const terminal = node.grantee === 'app:terminal' ? await terminalGrant(person) : null;
+    if (node.grantee === 'app:terminal' && !terminal)
+        throw new Error('cannot mint node token: terminal grant is not active');
+    const grant = terminal?.id ?? root?.grant_id ?? node.grant_id ?? null;
+    const token = randomBytes(32).toString('base64url');
+    // One token per execution, minted while it is `launching`: the primary key refuses a second mint,
+    // and an execution that is not launching (ended, running) gets none.
+    const launching = await db.prepare("SELECT 1 AS ok FROM executions WHERE execution_id = ? AND node_id = ? AND state = 'launching'").get(executionId, nodeId);
+    if (!launching)
+        throw new Error(`cannot mint node token: execution ${executionId} is not launching`);
+    await db.prepare('INSERT INTO node_tokens (broker_process_id, node_id, token_hash, grantee, uid, sub, "grant", client_id, scopes_json, issued_at, revoked_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)')
+        .run(executionId, nodeId, hash(token), node.grantee, await uidForApp(node.grantee), person, grant, root?.client_id ?? node.client_id, node.scopes_json, issuedAt);
+    return token;
+}
+/** Mints the node token of a `launching` execution in its own canvas write: what a runner's `start` hands to the process it launches. */
+export const mintExecutionToken = async (executionId, nodeId) => await withCanvasWrite((db) => mintNodeToken(db, executionId, nodeId, new Date().toISOString()));
+/** A stopped or superseded execution can never authenticate, even after restart. */
+export async function resolveNodeToken(token) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(token))
+        return null;
+    const row = await (await openDb()).prepare(`SELECT t.node_id, t.grantee, t.uid, t.sub, t."grant", t.client_id, t.scopes_json, n.run_id
+    FROM node_tokens t JOIN executions e ON e.execution_id = t.broker_process_id
+    JOIN nodes n ON n.node_id = t.node_id
+    WHERE t.token_hash = ? AND t.revoked_at IS NULL AND e.state != 'exited'`).get(hash(token));
+    return row ? { app: row.grantee, node: row.node_id, run: row.run_id, uid: row.uid,
+        sub: row.sub, grant: row.grant, client_id: row.client_id,
+        scopes: row.scopes_json === null ? null : JSON.parse(row.scopes_json) } : null;
+}
+export async function revokeExitedNodeToken(executionId) {
+    await revokeNodeTokens(await openDb(), 'broker_process_id', executionId, new Date().toISOString());
+}
+export async function revokePriorEpochNodeTokens(epoch) {
+    await (await openDb()).prepare(`UPDATE node_tokens SET revoked_at = ? WHERE revoked_at IS NULL
+    AND broker_process_id IN (SELECT execution_id FROM executions WHERE daemon_epoch IS DISTINCT FROM ?)`).run(new Date().toISOString(), epoch);
+}
+export async function revokeNodeTokens(db, where, id, at) {
+    await db.prepareUncached(`UPDATE node_tokens SET revoked_at = ? WHERE ${where} = ? AND revoked_at IS NULL`).run(at, id);
+}

package/dist/core/canvas/outcome-actions.d.ts

@@ -0,0 +1,23 @@
+import type { ObjectRow } from '../graph/types.js';
+import type { NodeOutcomeDocumentV1 } from '../runtime/outcome-document.js';
+import type { OutcomeDeliveryBinding } from './canvas.js';
+import { type DeliveryRecord } from './deliveries.js';
+import type { CanvasDb } from './db.js';
+export interface OutcomeActionRecord {
+    object: ObjectRow;
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload: unknown;
+    delivery: DeliveryRecord | null;
+    updatedAt: number;
+}
+/** Resolve only the live action belonging to this node, never an unrelated action of the same name. */
+export declare function readOutcomeAction(db: CanvasDb, nodeId: string): Promise<OutcomeActionRecord | null>;
+/** Register or replace an undelivered action in the caller's transaction. */
+export declare function registerOutcomeAction(db: CanvasDb, nodeId: string, binding: OutcomeDeliveryBinding): Promise<void>;
+/** Refuse removal after any delivery, including an acknowledged historical one. */
+export declare function unregisterOutcomeAction(db: CanvasDb, nodeId: string): Promise<boolean>;
+/** Late registration dispatches directly to its action, not to every outcome watcher. */
+export declare function enqueueLateOutcomeAction(db: CanvasDb, nodeId: string, document: NodeOutcomeDocumentV1): Promise<void>;

package/dist/core/canvas/outcome-actions.js

@@ -0,0 +1,71 @@
+import { writeActsFor } from '../permissions/facts.js';
+import { createObject, nodeObject } from '../graph/objects.js';
+import { recordWatch } from '../graph/watches.js';
+import { argvReceiver } from '../graph/receivers.js';
+import { finalizeNodeMail, insertMessage } from '../feed/messages.js';
+import { deliveryFrom } from './deliveries.js';
+/** Resolve only the live action belonging to this node, never an unrelated action of the same name. */
+export async function readOutcomeAction(db, nodeId) {
+    const row = await db.prepare(`SELECT a.*, c.receiver_json, c.payload_json FROM objects a
+    JOIN objects n ON n.id = ? AND n.type = 'node'
+    JOIN custom_objects c ON c.object = a.id
+    WHERE a.type = 'action' AND a.name = ? AND a.owner = n.owner AND a.deleted_at IS NULL
+    ORDER BY a.seq DESC LIMIT 1`).get(nodeId, `outcome/${nodeId}`);
+    if (!row)
+        return null;
+    const receiver = JSON.parse(row.receiver_json);
+    const delivery = await db.prepare(`SELECT * FROM deliveries WHERE destination_id = ? ORDER BY created_at DESC, seq DESC LIMIT 1`)
+        .get(row.id);
+    return { object: row, actionName: receiver.name, argv: receiver.argv, cwd: receiver.cwd,
+        configOrigin: receiver.config_origin, payload: row.payload_json === null ? null : JSON.parse(row.payload_json),
+        delivery: delivery ? deliveryFrom(delivery) : null,
+        updatedAt: receiver.updated_at ?? Date.parse(row.created_at) };
+}
+/** Register or replace an undelivered action in the caller's transaction. */
+export async function registerOutcomeAction(db, nodeId, binding) {
+    const node = await nodeObject(db, nodeId);
+    const existing = await readOutcomeAction(db, nodeId);
+    if (existing?.delivery)
+        throw new Error(`outcome action ${nodeId} already has a delivery`);
+    const object = existing?.object ?? await createObject(db, { type: 'action', kind: null, owner: node.owner,
+        privacy: 'public', name: `outcome/${nodeId}`, preview: binding.actionName });
+    // The action sits under the node's owner; when that is an app, the node's person owns it too.
+    const sub = (await db.prepare('SELECT sub FROM nodes WHERE node_id = ?').get(nodeId))?.sub;
+    if (!existing && sub && (await db.prepare("SELECT 1 FROM objects WHERE id = ? AND type = 'app'").get(node.owner)) !== undefined)
+        await writeActsFor(db, object.id, sub);
+    const receiver = JSON.stringify({ argv: binding.argv, cwd: binding.cwd,
+        config_origin: binding.configOrigin, name: binding.actionName,
+        updated_at: existing ? Math.max(Date.now(), existing.updatedAt + 1) : Date.parse(object.created_at) });
+    await db.prepare(`INSERT INTO custom_objects (object, receiver_json, payload_json) VALUES (?, ?, ?)
+    ON CONFLICT(object) DO UPDATE SET receiver_json = excluded.receiver_json, payload_json = excluded.payload_json`)
+        .run(object.id, receiver, JSON.stringify(binding.payload ?? null));
+    if (existing)
+        await db.prepare('UPDATE objects SET preview = ? WHERE id = ?').run(binding.actionName, object.id);
+    else {
+        await db.prepare('UPDATE objects SET reception = 2 WHERE id = ?').run(object.id);
+        await recordWatch(db, object, node, 'spawn', { patterns: ['outcome'], config: [{ threshold: 1, delivery: 'after-turn' }] });
+    }
+}
+/** Refuse removal after any delivery, including an acknowledged historical one. */
+export async function unregisterOutcomeAction(db, nodeId) {
+    const action = await readOutcomeAction(db, nodeId);
+    if (!action)
+        return true; // DELETE of an absent registration is idempotent.
+    if (action.delivery)
+        return false;
+    await db.prepare('DELETE FROM objects WHERE id = ?').run(action.object.id);
+    return true;
+}
+/** Late registration dispatches directly to its action, not to every outcome watcher. */
+export async function enqueueLateOutcomeAction(db, nodeId, document) {
+    const action = await readOutcomeAction(db, nodeId);
+    if (!action || action.delivery)
+        throw new Error(`outcome action ${nodeId} cannot be delivered again`);
+    const node = await nodeObject(db, nodeId);
+    const prepared = finalizeNodeMail({ senderNodeId: nodeId, senderName: node.name, kind: 'completed',
+        label: `outcome node ${node.name}`, bodyJson: document, urgency: 'normal' }, null);
+    const messageId = await insertMessage(db, { ...prepared, senderNodeId: nodeId, senderName: node.name,
+        kind: 'completed', label: `outcome node ${node.name}`, disposition: null,
+        event: { event: 'outcome', objectId: nodeId, level: 1, actorId: nodeId } });
+    await argvReceiver.enqueue(db, { messageId, event: 'outcome', level: 1, senderNodeId: nodeId, elevatesTier: false }, [{ id: action.object.id, reception: 2, delivery: 'after-turn' }]);
+}

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

@@ -0,0 +1,32 @@
+import { PersonUnresolvedError, PersonOutsideRequestError, setPersonId, markCloudRole, isCloudRole, runAsPerson, personId } from './person-state.js';
+import { type CanvasDb } from './db.js';
+import { LEGACY_LOCAL_PERSON } from './legacy-person.js';
+export { LEGACY_LOCAL_PERSON };
+export type PersonSource = 'stored' | 'joined' | 'grants' | 'minted';
+export { PersonUnresolvedError, PersonOutsideRequestError, setPersonId, markCloudRole, isCloudRole, runAsPerson, personId };
+/** As `personId()`, but a process that is not the daemon gets a lazy get-or-create keyed by the active canvas database. */
+export declare function personIdAsync(): Promise<string>;
+/** Get-or-create the person and say where it came from. Order: stored, the join file's owner, the single `sub` of the
+ *  mirrored grants (a runtime with an issuer and no join file), else a minted id on a runtime without an issuer.
+ *  Null when an issuer runtime has no mirrored grants yet; nothing is stored then. */
+export declare function resolvePerson(): Promise<{
+    id: string;
+    source: PersonSource;
+} | null>;
+export declare function resolvePersonId(): Promise<string | null>;
+type Counts = Record<string, number>;
+/** Replace person `from` with `to` in every known column, inside the caller's `withCanvasWrite` transaction. Idempotent.
+ *  Rows keyed by the principal merge on collision. Returns rows changed per column. */
+export declare function substitutePerson(db: CanvasDb, from: string, to: string): Promise<Counts>;
+export interface RetireResult {
+    person: string;
+    /** The join reconcile (part A) ran: the person changed from the stored one to the join file's owner. */
+    joinedFrom: string | null;
+    /** The legacy retire (part B) ran. */
+    retired: boolean;
+    /** Rows changed per column (zeros omitted). */
+    columns: Counts;
+}
+/** The boot step (flow 2), one transaction. Part A applies a join that landed after the person was minted; part B retires the
+ *  legacy local person once per person; part C installs the local terminal grant on a runtime without an issuer. */
+export declare function retireLocalPerson(): Promise<RetireResult>;