@north-light/api 0.3.580 → 0.3.588

package/dist/commands/api-client.js

@@ -0,0 +1,427 @@
+// api-client.ts — the shared CLI-side client factory + read-source adapter that
+// every re-plumbed `crtr` verb (Stage B) builds on.
+//
+// THE POINT (spec §1/§10, plan B-0): a `crtr` CLI process must NEVER open
+// canvas.db. This file is the seam that makes that possible — its transitive
+// RUNTIME import graph reaches ZERO canvas state-store code (`core/canvas/db.ts`
+// `openDb` / `core/canvas/canvas.ts` accessors). It gets there three ways:
+//   1. `CrtrClient` (`src/api`) is dependency-light by construction (spec §3.1).
+//   2. `ensureDaemon` is imported from the lean `daemon/manage.ts`, which — after
+//      the B-0 pidfile/boot-id extractions — is fs/process-only (no crtrd.ts,
+//      no `openDb`).
+//   3. `CanvasSource`/`NodeRow`/`NodeMeta` are TYPE-ONLY imports (erased at
+//      emit), so naming them pulls no runtime canvas code.
+// The `--canvas` remote branch reuses `RemoteCanvasSource`, itself verified
+// openDb-free (its only runtime import is the HTTP `createRemoteExec`; its
+// `CanvasSource`/`types` imports are type-only) — plan Q-3.
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { CrtrClient, ApiError } from '../api/index.js';
+import { localClient } from '../api/node-transport.js';
+import { northlightFetch, notSignedIn, readPersonCredential } from '../core/directory/person-credential.js';
+import { isMoveCommitted, moveUnfinishedError, readMachineConfig } from '../daemon/machine-link/config.js';
+import { northlightUnreachable } from '../core/directory/reach.js';
+import { apiErrorToCliError } from '../core/io.js';
+import { autostartDisabled, daemonAutostartStartupFailure, ensureDaemon } from '../daemon/manage.js';
+import { DAEMON_STARTUP_WINDOW_MS } from '../daemon/startup-policy.js';
+import { readState } from '../core/config.js';
+import { resolveRemoteCanvasTarget } from '../core/remote-canvas-target.js';
+import { RemoteCanvasSource } from '../core/canvas/remote-canvas-source.js';
+import { BROKER_RELEASED_MARKER, BROKER_RELAY_GENERATION, crtrHome } from '../core/canvas/paths.js';
+import { envTestNodeSocketWindowMs, isSandboxedNode } from '../shared/env.js';
+import { CrtrError, ownerOnly } from '../core/errors.js';
+import { ExitCode } from '../types.js';
+/** The API projects exactly the fault a node row carries; `api/` simply cannot
+ *  express the branded `operation_id` (it imports Node built-ins only), so the
+ *  wire value is asserted back to the row's fault type here rather than
+ *  reshaped. `broker↔crtrd` is deliberately absent from the wire link union: a
+ *  stored fault can never carry it. */
+function withRowFault(dto) {
+    return { ...dto, fault: (dto.fault ?? null) };
+}
+// Error translation
+/** Rethrow an `ApiError` as the clean structured CLI error agents parse
+ *  (`core/io` `handle`) — instead of the generic "internal bug" stderr path a
+ *  raw non-`CrtrError` throw would take. The mapping itself lives in ONE place
+ *  (`apiErrorToCliError`, `core/io.ts`); this is the explicit-catch helper a
+ *  leaf uses when it wants to attach a call-site `next` hint. Non-`ApiError`
+ *  throws propagate unchanged (a genuine bug still reads as `internal`). Typed
+ *  `never` so callers can use it as the tail of a `catch` without confusing
+ *  definite assignment. */
+export function rethrowAsCliError(err, next) {
+    if (err instanceof ApiError)
+        throw apiErrorToCliError(err, next);
+    throw err;
+}
+/** Fetch a node, mapping ONLY a 404 to `null` (the "not found" contract every
+ *  existence-check leaf wants) and surfacing every other failure as the clean
+ *  network-class CLI error via `rethrowAsCliError`. This replaces the old
+ *  `.catch(() => null)` idiom that, post-B-1 (`getNode` is now an HTTP round-trip),
+ *  masked a broken/slow/restarting daemon as a false "node not found". Same
+ *  404-only→null mapping as `ApiCanvasSource.orNull`, but returning the raw DTO
+ *  and rethrowing non-404s as CLI errors rather than swallowing them. */
+export async function getNodeOrNull(nodeId) {
+    try {
+        return await cliClient().getNode(nodeId);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        rethrowAsCliError(err);
+    }
+}
+// cliClient — the one place the CLI constructs a daemon client
+/** Bounded tail of crtrd.log surfaced on a cold-start `/healthz` timeout.
+ *  Large enough to catch a real startup failure/stack trace,
+ *  small enough that a runaway daemon log can never leak unbounded into a CLI
+ *  error message. */
+/** A machine cron's run token (`daemon/cron/run-token.ts`) starts with this. */
+const RUN_TOKEN_PREFIX = 'crtr_run_';
+export const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4_096;
+const COLD_START_DIAGNOSTIC_TAIL_LINES = 20;
+/** Read a bounded tail of crtrd's event log to enrich a `daemon_unavailable`
+ *  cold-start timeout, so the actual startup failure is not discarded behind a
+ *  bare message. Bounds the I/O itself — opens the file and reads only the
+ *  final `COLD_START_DIAGNOSTIC_TAIL_BYTES` bytes via `fstatSync`+`readSync`,
+ *  never `readFileSync`-ing the whole append-only log — then decodes/filters
+ *  that bounded slice. Best-effort and synchronous per the `coldStartDiagnostic`
+ *  contract — a missing/unreadable/empty log yields `undefined` so the base
+ *  message is used unchanged. */
+export function readColdStartDiagnostic() {
+    let fd;
+    try {
+        fd = openSync(join(crtrHome(), 'crtrd.log'), 'r');
+        const { size } = fstatSync(fd);
+        const start = Math.max(0, size - COLD_START_DIAGNOSTIC_TAIL_BYTES);
+        const length = size - start;
+        if (length <= 0)
+            return undefined;
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, start);
+        const lines = buffer.toString('utf8').split('\n').filter((line) => line.trim() !== '');
+        const tail = lines.slice(-COLD_START_DIAGNOSTIC_TAIL_LINES).join('\n').trim();
+        return tail === '' ? undefined : `crtrd.log (tail):\n${tail}`;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // best-effort close; the read already happened (or failed) above.
+            }
+        }
+    }
+}
+/** Where a `crtr` process outside a node reaches the control plane instead of a local daemon: a machine cron's run token goes to
+ *  `CRTR_API_URL`; an imported Mac (`runtime/machine.json`) goes to its `apiUrl` with the signed-in person's bearer. Neither: undefined,
+ *  and the local socket is used. `CRTR_API_SOCKET` (inside a node) is checked by the caller first and is never remote. */
+export function remoteTarget() {
+    if (process.env['CRTR_API_SOCKET'])
+        return undefined;
+    const runToken = process.env['CRTR_API_TOKEN'];
+    const runUrl = process.env['CRTR_API_URL'];
+    if (runToken !== undefined && runToken.startsWith(RUN_TOKEN_PREFIX) && runUrl) {
+        return { client: (timeoutMs) => new CrtrClient({ baseUrl: runUrl, headers: { authorization: `Bearer ${runToken}` }, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }) };
+    }
+    const machine = readMachineConfig();
+    if (machine === undefined)
+        return undefined;
+    if (readPersonCredential() === undefined)
+        throw notSignedIn('this computer is imported into Northlight, so crtr needs your sign-in');
+    // The bearer is fetched per request (cached on disk until 30 s before it ends), so a long command never sends an ended one.
+    // `CrtrClient` rethrows what its fetch throws as an `ApiError`, so a sign-in refusal or an unreachable Northlight crosses as one carrying its own next step.
+    const northlight = northlightFetch(machine.directoryUrl, machine.apiUrl);
+    const authed = (input, init) => northlight(input, init).catch((error) => { throw error instanceof CrtrError ? asApiError(error) : error; });
+    return { client: (timeoutMs) => unreachableOnTimeout(new CrtrClient({ baseUrl: machine.apiUrl, fetch: authed, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }), machine.apiUrl) };
+}
+/** `CrtrClient` rejects with its own per-request timeout (`request_timeout`) before the fetch's rejection can reach `authed`, so a control plane that takes a
+ *  connection and never answers would read as a crtr bug. On a remote target that timeout means Northlight is unreachable; a caller's own abort stays `request_aborted`. */
+function unreachableOnTimeout(client, apiUrl) {
+    return new Proxy(client, {
+        get(target, property) {
+            const value = Reflect.get(target, property, target);
+            if (typeof value !== 'function')
+                return value;
+            return (...args) => {
+                const result = value.apply(target, args);
+                return result instanceof Promise
+                    ? result.catch((error) => { throw error instanceof ApiError && error.code === 'request_timeout' ? asApiError(northlightUnreachable(error, apiUrl)) : error; })
+                    : result;
+            };
+        },
+    });
+}
+/** A CLI error carried through `CrtrClient` as the `ApiError` `apiErrorToCliError` turns back into it. */
+function asApiError(error) {
+    const next = typeof error.details?.['next'] === 'string' ? error.details['next'] : undefined;
+    return new ApiError(error.exitCode === ExitCode.NETWORK ? 503 : 401, error.code, error.message, { error: error.code, message: error.message, ...(next === undefined ? {} : { next }) });
+}
+/** A move whose cloud run reached `done` but whose computer has not switched over: the account holds the records, the local daemon stays drained,
+ *  and no command may run against either side until `crtr sys signin` finishes it (design D14). The record is deleted only once the machine-role daemon
+ *  is up (`finishMove`, or that daemon's own start), so a `machine.json` written before a failed restart does not lift this. */
+export function moveUnfinished() {
+    return isMoveCommitted() ? moveUnfinishedError() : undefined;
+}
+/** The local-socket `CrtrClient` every CLI verb uses. Autostart is on by
+ *  default: on a cold socket the injected `onColdSocket` hook fires
+ *  `ensureDaemon()` (spawns crtrd detached via the branded host), then the
+ *  client polls `/healthz` to a bounded deadline and retries once (the poll
+ *  lives inside `CrtrClient`, A-2). If crtrd never becomes reachable, the
+ *  client surfaces the final observed transport failure. This is the ONLY CLI
+ *  reference to `ensureDaemon`.
+ *
+ *  `onColdSocket` is fire-and-forget — `ensureDaemon()` spawns crtrd and
+ *  returns immediately, so the client's OWN `/healthz` poll is the only
+ *  deadline the initiating CLI invocation actually waits on. It must never be
+ *  narrower than the window `spawnDaemon`'s `verifyDaemonStartup` allows.
+ *  Both callers use the shared startup policy so a valid on-disk migration
+ *  cannot outlast the initiating CLI command. */
+export function cliClient(opts) {
+    if (opts?.local !== true) {
+        const unfinished = moveUnfinished();
+        if (unfinished !== undefined)
+            throw unfinished;
+    }
+    const remote = opts?.local === true ? undefined : remoteTarget();
+    if (remote !== undefined)
+        return remote.client(opts?.timeoutMs);
+    const relay = process.env['CRTR_API_SOCKET'];
+    if (relay) {
+        // The marker is committed by crtrd; a successor relay clears it only after binding.
+        const availabilityFailure = () => {
+            if (existsSync(relay))
+                return undefined;
+            try {
+                const dir = dirname(relay);
+                const released = readFileSync(join(dir, BROKER_RELEASED_MARKER), 'utf8');
+                const current = readFileSync(join(dir, BROKER_RELAY_GENERATION), 'utf8');
+                if (released === current && released !== '') {
+                    return new ApiError(503, 'broker_released', "This node's broker has been released, so crtr commands from its background jobs are not available.");
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            return undefined;
+        };
+        const released = availabilityFailure();
+        if (released !== undefined)
+            throw apiErrorToCliError(released, "Run the command from the node's own turn instead.");
+        // Inside a node the socket is the broker's relay, which exists only while
+        // that broker runs. A daemon restart or broker respawn removes it until the
+        // successor broker is up, which takes longer than the default 10-second
+        // window; a command that began before then (a long-running tool call or a
+        // backgrounded job) must outlast it rather than fail with
+        // `daemon_unavailable` after its work is done.
+        return localClient({
+            autostart: false,
+            availabilityFailure,
+            coldStartPollWindowMs: (autostartDisabled() ? envTestNodeSocketWindowMs() : undefined) ?? DAEMON_STARTUP_WINDOW_MS,
+            ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+    }
+    if (autostartDisabled()) {
+        return localClient({ autostart: false, ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    }
+    return localClient({
+        ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        onColdSocket: async () => {
+            // The client's bounded /healthz poll owns the readiness wait and failure.
+            ensureDaemon();
+        },
+        // On a cold-start timeout, enrich the bare `daemon_unavailable` with the
+        // tail of crtrd's event log instead of discarding it.
+        coldStartDiagnostic: readColdStartDiagnostic,
+        // A daemon that exits before it is ready (not a migration still making
+        // progress, which keeps the long window) ends the wait with its own reason.
+        coldStartFailure: daemonAutostartStartupFailure,
+        coldStartPollWindowMs: DAEMON_STARTUP_WINDOW_MS,
+    });
+}
+// ApiCanvasSource — a read CanvasSource backed entirely by the crtrd API
+// Index the short-lived lean roster once so repeated topology lookups stay O(1).
+// listNodes/getRow still use full DTO endpoints for fields the roster omits.
+const ROSTER_CACHE_TTL_MS = 2000;
+export class ApiCanvasSource {
+    client;
+    rosterCache = null;
+    rosterInFlight = null;
+    constructor(client = cliClient()) {
+        this.client = client;
+    }
+    async roster() {
+        const now = Date.now();
+        if (this.rosterCache !== null && now - this.rosterCache.at < ROSTER_CACHE_TTL_MS) {
+            return this.rosterCache.index;
+        }
+        if (this.rosterInFlight !== null)
+            return this.rosterInFlight;
+        this.rosterInFlight = this.client
+            .canvasRoster()
+            .then((roster) => {
+            const index = { snapshot: roster, subscriptions: new Map(), subscribers: new Map() };
+            for (const edge of roster.edges) {
+                const subscription = { node_id: edge.to_id, active: edge.active, created: edge.created };
+                const subscriber = { node_id: edge.from_id, active: edge.active, created: edge.created };
+                const subscriptions = index.subscriptions.get(edge.from_id);
+                if (subscriptions === undefined)
+                    index.subscriptions.set(edge.from_id, [subscription]);
+                else
+                    subscriptions.push(subscription);
+                const subscribers = index.subscribers.get(edge.to_id);
+                if (subscribers === undefined)
+                    index.subscribers.set(edge.to_id, [subscriber]);
+                else
+                    subscribers.push(subscriber);
+            }
+            this.rosterCache = { at: Date.now(), index };
+            return index;
+        })
+            .finally(() => {
+            this.rosterInFlight = null;
+        });
+        return this.rosterInFlight;
+    }
+    /** Map a 404 from the API to the interface's `null` "not found" contract;
+     *  re-throw everything else. */
+    async orNull(fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    async getNode(nodeId) {
+        const detail = await this.orNull(() => this.client.getNode(nodeId));
+        return detail === null ? null : withRowFault(detail);
+    }
+    async getRow(nodeId) {
+        const detail = await this.orNull(() => this.client.getNode(nodeId));
+        return detail === null ? null : withRowFault(detail);
+    }
+    async listNodes(filter) {
+        const status = filter?.status;
+        const under = filter?.under === undefined ? {} : { under: filter.under, under_inclusive: true };
+        let rows;
+        if (Array.isArray(status)) {
+            // The list query takes a single status; fetch the scope + filter client-side to
+            // honor a multi-status filter without N round-trips.
+            const wanted = new Set(status);
+            const all = await this.client.listNodes(under);
+            rows = all.filter((r) => wanted.has(r.status));
+        }
+        else {
+            rows = await this.client.listNodes({ ...(status !== undefined ? { status } : {}), ...under });
+        }
+        return rows.map((row) => withRowFault(row));
+    }
+    /** The browse screen uses one slim, compressed read for rows AND topology.
+     * The same roster index feeds subscriptionsOf/view until its normal TTL ends. */
+    async browseSnapshot() {
+        const bytes = await this.client.canvasBrowseCompressed();
+        const snapshot = JSON.parse(gunzipSync(bytes).toString('utf8'));
+        const index = { subscriptions: new Map(), subscribers: new Map() };
+        for (const edge of snapshot.edges) {
+            const subscriptions = index.subscriptions.get(edge.from_id) ?? [];
+            subscriptions.push({ node_id: edge.to_id, active: edge.active, created: edge.created });
+            index.subscriptions.set(edge.from_id, subscriptions);
+            const subscribers = index.subscribers.get(edge.to_id) ?? [];
+            subscribers.push({ node_id: edge.from_id, active: edge.active, created: edge.created });
+            index.subscribers.set(edge.to_id, subscribers);
+        }
+        this.rosterCache = { at: Date.now(), index };
+        return snapshot.nodes.map((node) => withRowFault(node));
+    }
+    async panelRoster() {
+        const index = await this.roster();
+        if (index.snapshot !== undefined)
+            return index.snapshot;
+        // A browse snapshot populated only the edge index; request current roster rows.
+        this.rosterCache = null;
+        return (await this.roster()).snapshot;
+    }
+    async subscriptionsOf(subscriber) {
+        return this.roster().then((index) => index.subscriptions.get(subscriber) ?? []);
+    }
+    async subscribersOf(publisher) {
+        return this.roster().then((index) => index.subscribers.get(publisher) ?? []);
+    }
+    /** BFS over the active `subscribes_to` edges from `root` (its transitive view),
+     *  excluding `root` itself — the same traversal shape as
+     *  `RemoteCanvasSource.view`, expressed over the API's edge lists. */
+    async view(root) {
+        const seen = new Set([root]);
+        const out = [];
+        const queue = (await this.subscriptionsOf(root)).map((s) => s.node_id);
+        while (queue.length > 0) {
+            const id = queue.shift();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            out.push(id);
+            for (const s of await this.subscriptionsOf(id)) {
+                if (!seen.has(s.node_id))
+                    queue.push(s.node_id);
+            }
+        }
+        return out;
+    }
+    /** Per-NODE open-ticket counts across `root`'s view. The renderer badges each
+     * node with the tickets it raised (the human bridge's parent), so this must
+     * be per-node. Request only this view's ids: using the
+     * enriched full-canvas snapshot for a five-second viewer poll blocked crtrd
+     * behind metadata and telemetry reads for every historical node. */
+    async ticketCountsForNodes(nodeIds) {
+        return (await this.client.attentionCounts([...nodeIds])).counts;
+    }
+    async ticketCountsForView(root) {
+        return this.ticketCountsForNodes([root, ...await this.view(root)]);
+    }
+    /** True when `nodeId` has at least one active (`active` edge flag, not just a
+     *  live subscriber) subscription to a node that is currently live
+     *  (`active`/`idle` status). `subscriptionsOf`'s roster-backed edges carry the
+     *  real per-edge `active` flag, so this filter is exact, not an over-report. */
+    async newestReport(nodeId) {
+        return (await this.client.getReports(nodeId, { limit: 1 }))[0] ?? null;
+    }
+    async hasActiveLiveSubscription(nodeId) {
+        const subs = (await this.subscriptionsOf(nodeId)).filter((s) => s.active);
+        for (const s of subs) {
+            const row = await this.getRow(s.node_id);
+            if (row && (row.status === 'active' || row.status === 'idle'))
+                return true;
+        }
+        return false;
+    }
+}
+// cliCanvasSource — the source selector (mirrors resolveCanvasSource)
+/** The active read source for a CLI command. Mirrors `resolveCanvasSource`'s
+ *  selection WITHOUT importing `core/canvas/source.ts` (which pulls
+ *  `LocalCanvasSource` → `openDb`, failing the Stage-C import checker): an
+ *  explicit `--canvas <name>` wins, else the durable `crtr canvas use` selection
+ *  (`ScopeState.activeCanvas`), else the API-backed local source. The remote
+ *  branch reuses the verified-openDb-free `RemoteCanvasSource` (plan Q-3). */
+export function cliCanvasSource(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 new ApiCanvasSource();
+    }
+    const name = opts?.canvasName ?? readState(scope).activeCanvas ?? null;
+    if (!name)
+        return new ApiCanvasSource();
+    const { previewEndpoint, relayToken } = resolveRemoteCanvasTarget(name, scope);
+    return new RemoteCanvasSource(previewEndpoint, relayToken);
+}

package/dist/commands/attention.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare const attentionBranch: BranchDef;

package/dist/commands/attention.js

@@ -0,0 +1,215 @@
+// `crtr canvas attention` — aggregate pending human tickets across the canvas.
+//
+// A pending "ticket" is any humanloop interaction awaiting the user: a page or
+// an anchored review. Each lives in its human bridge node
+// directory and is attributed through that bridge's parent relation. This
+// subtree surfaces a direct node projection; cwd is display metadata only.
+//
+// Exported as a branch; `crtr canvas` (canvas.ts) mounts it.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliClient, cliCanvasSource } from './api-client.js';
+/** The nodes represented in the sub-DAG rooted at `viewId` (root + view). */
+async function viewNodeSet(source, viewId) {
+    return new Set([viewId, ...(await source.view(viewId))]);
+}
+// attention count
+const attentionCount = defineLeaf({
+    name: 'count',
+    description: 'total pending human-ticket count (machine-parseable stdout.count)',
+    whenToUse: 'a lightweight summary when you just need the number, not which cwds are blocked — scope it to a node or a sub-DAG, or default to canvas-wide. Use `list` when you need to act on where to go answer.',
+    help: {
+        name: 'canvas attention count',
+        // stdout.count is parsed directly by the nav chrome — keep the contract.
+        summary: 'return the number of pending human tickets (asks, reviews, notifications); stdout.count is machine-parseable',
+        params: [
+            {
+                kind: 'flag',
+                name: 'node',
+                type: 'string',
+                required: false,
+                constraint: 'Count tickets asked by this node. Mutually exclusive with --view.',
+            },
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Sum tickets for all nodes in the sub-DAG rooted at this id. Mutually exclusive with --node.',
+            },
+        ],
+        output: [
+            { name: 'count', type: 'integer', required: true, constraint: 'Total pending human tickets in the requested scope.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans humanloop interaction dirs.'],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        const viewId = input['view'];
+        if (nodeId !== undefined && viewId !== undefined) {
+            throw new InputError({
+                error: 'ambiguous_scope',
+                message: '--node and --view are mutually exclusive',
+                next: 'Use one of --node <id>, --view <id>, or neither (canvas-wide).',
+            });
+        }
+        if (nodeId !== undefined) {
+            const source = cliCanvasSource();
+            const node = await source.getNode(nodeId);
+            if (node === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${nodeId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const counts = await cliClient().attentionCounts([nodeId]);
+            return { count: counts.counts[nodeId] ?? 0 };
+        }
+        const items = (await cliClient().attention()).items;
+        if (viewId !== undefined) {
+            const source = cliCanvasSource();
+            if ((await source.getNode(viewId)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const ids = await viewNodeSet(source, viewId);
+            const total = items.filter((it) => ids.has(it.node_id)).reduce((s, e) => s + e.count, 0);
+            return { count: total };
+        }
+        // Canvas-wide — sum every asking-node entry.
+        return { count: items.reduce((s, e) => s + e.count, 0) };
+    },
+});
+// attention list
+const attentionList = defineLeaf({
+    name: 'list',
+    description: 'itemised list of cwds with pending human tickets',
+    whenToUse: 'finding which agents are blocked waiting on the user — an itemised list of the cwds with pending tickets (asks, reviews, notifications), oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.',
+    help: {
+        name: 'canvas attention list',
+        summary: 'list nodes that asked pending human tickets',
+        params: [
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Scope the list to the sub-DAG rooted at this node id. Omit for canvas-wide.',
+            },
+        ],
+        output: [
+            {
+                name: 'items',
+                type: 'object[]',
+                required: true,
+                constraint: 'Each: {node_id, name, cwd, count}. One entry per asking node with count > 0.',
+            },
+            { name: 'total', type: 'integer', required: true, constraint: 'Sum of counts across all entries.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans humanloop interaction dirs.'],
+    },
+    run: async (input) => {
+        const viewId = input['view'];
+        let items = (await cliClient().attention()).items;
+        if (viewId !== undefined) {
+            const source = cliCanvasSource();
+            if ((await source.getNode(viewId)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const ids = await viewNodeSet(source, viewId);
+            items = items.filter((it) => ids.has(it.node_id));
+        }
+        const total = items.reduce((s, e) => s + e.count, 0);
+        return { items, total };
+    },
+});
+// attention map
+const attentionMap = defineLeaf({
+    name: 'map',
+    description: 'per-node ticket counts for a visible set, batched in one pass',
+    whenToUse: 'labelling every node in a UI with its pending-ticket count in one batched pass — the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+    tier: 'hidden',
+    help: {
+        name: 'canvas attention map',
+        summary: 'per-node pending human-ticket counts for a visible set of nodes in ONE pass — the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+        params: [
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Include this node and its whole sub-DAG (root + reports recursively). Union with --nodes. At least one of --view/--nodes is required.',
+            },
+            {
+                kind: 'flag',
+                name: 'nodes',
+                type: 'string',
+                required: false,
+                constraint: 'Comma-separated explicit node ids to include (e.g. ancestry + peers). Union with --view.',
+            },
+        ],
+        output: [
+            {
+                name: 'counts',
+                type: 'object',
+                required: true,
+                constraint: 'Map of node_id → pending human-ticket count. Every requested id is present (0 when none).',
+            },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans the registered humanloop node root once.'],
+    },
+    run: async (input) => {
+        const viewId = input['view'];
+        const nodesRaw = input['nodes'];
+        if (viewId === undefined && (nodesRaw === undefined || nodesRaw.trim() === '')) {
+            throw new InputError({
+                error: 'missing_scope',
+                message: 'at least one of --view <id> or --nodes <a,b,c> is required',
+                next: 'Pass --view <root> to cover a sub-DAG, --nodes <a,b,c> for an explicit set, or both.',
+            });
+        }
+        const source = cliCanvasSource();
+        const ids = new Set();
+        if (viewId !== undefined) {
+            if ((await source.getNode(viewId)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            ids.add(viewId);
+            for (const id of await source.view(viewId))
+                ids.add(id);
+        }
+        if (nodesRaw !== undefined) {
+            for (const id of nodesRaw.split(',').map((s) => s.trim()).filter((s) => s !== ''))
+                ids.add(id);
+        }
+        const counts = await cliClient().attentionCounts([...ids]);
+        return { counts: counts.counts };
+    },
+});
+// Export — mounted under `crtr canvas`
+export const attentionBranch = defineBranch({
+    name: 'attention',
+    description: 'count/list pending human tickets across the graph',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on the user, and where: count the pending tickets (asks, reviews, notifications) or list the cwds that have them. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
+    help: {
+        name: 'canvas attention',
+        summary: 'aggregate pending human tickets across the canvas',
+        model: '`count` returns a single integer (stdout.count is machine-parseable) and accepts --node or --view; `list` returns itemised asking-node entries and accepts --view only. Both default to canvas-wide. A ticket is any humanloop interaction awaiting the user: an ask, a review, or a notification.',
+    },
+    children: [attentionCount, attentionList, attentionMap],
+});

package/dist/commands/canvas/edges.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const edgesLeaf: LeafDef;