@north-light/crouter 0.3.154

package/dist/commands/api-client.d.ts

@@ -0,0 +1,100 @@
+import { CrtrClient } from '../api/index.js';
+import type { CanvasSource } from '../core/canvas/source.js';
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from '../core/canvas/types.js';
+import type { Scope } from '../types.js';
+import type { NodeDetailDTO } from '../api/dto/nodes.js';
+/** 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 declare function rethrowAsCliError(err: unknown, next?: string): never;
+/** 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 declare function getNodeOrNull(nodeId: string): Promise<NodeDetailDTO | null>;
+/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout
+ *  (issue #516). 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. */
+export declare const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4096;
+/** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
+ *  cold-start timeout (issue #516: the prior bare message discarded the actual
+ *  startup failure). 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 declare function readColdStartDiagnostic(): string | 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 — or
+ *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
+ *  §8). This is the ONLY CLI reference to `ensureDaemon`.
+ *
+ *  #508 follow-up: `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. That poll
+ *  used to default to a fixed 10s window while `spawnDaemon`'s
+ *  `verifyDaemonStartup` (which `ensureDaemon`'s spawn transitively awaits, in
+ *  the detached child, on the SAME cold-start path) was widened to 20s for a
+ *  slow-but-valid cold boot: a daemon that took 12s was a valid, verified
+ *  startup, but the CLI process that triggered it still gave up and reported
+ *  `daemon_unavailable` at 10s. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
+ *  here keeps the two in lockstep — one authoritative window, not two that can
+ *  drift apart — without adding any retry/fallback poll loop. */
+export declare function cliClient(opts?: {
+    timeoutMs?: number;
+}): CrtrClient;
+export declare class ApiCanvasSource implements CanvasSource {
+    private readonly client;
+    private rosterCache;
+    private rosterInFlight;
+    constructor(client?: CrtrClient);
+    private roster;
+    /** Map a 404 from the API to the interface's `null` "not found" contract;
+     *  re-throw everything else. */
+    private orNull;
+    getNode(nodeId: string): Promise<NodeMeta | null>;
+    getRow(nodeId: string): Promise<NodeRow | null>;
+    listNodes(filter?: {
+        status?: NodeStatus | NodeStatus[];
+    }): Promise<NodeRow[]>;
+    subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
+    subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
+    /** 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. */
+    view(root: string): Promise<string[]>;
+    /** 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. */
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
+    /** 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. */
+    hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
+}
+/** 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 declare function cliCanvasSource(opts?: {
+    canvasName?: string;
+    scope?: Scope;
+}): CanvasSource;

package/dist/commands/api-client.js

@@ -0,0 +1,377 @@
+// 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, fstatSync, openSync, readSync } from 'node:fs';
+import { join } from 'node:path';
+import { CrtrClient, ApiError } from '../api/index.js';
+import { apiErrorToCliError } from '../core/io.js';
+import { ensureDaemon, DAEMON_VERIFY_WINDOW_MS } from '../daemon/manage.js';
+import { readState } from '../core/config.js';
+import { resolveRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+import { RemoteCanvasSource } from '../core/canvas/remote-canvas-source.js';
+import { crtrHome } from '../core/canvas/paths.js';
+// ---------------------------------------------------------------------------
+// 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
+// ---------------------------------------------------------------------------
+/** Whether autostart is suppressed for this invocation. `--no-autostart` or
+ *  `CRTR_NO_DAEMON_AUTOSTART=1` forces fail-loud on a cold socket (spec §7.1) —
+ *  for environments that manage crtrd externally and want the diagnostic. */
+function autostartDisabled() {
+    return process.env['CRTR_NO_DAEMON_AUTOSTART'] === '1' || process.argv.includes('--no-autostart');
+}
+/** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout
+ *  (issue #516). 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. */
+export const COLD_START_DIAGNOSTIC_TAIL_BYTES = 4_096;
+const COLD_START_DIAGNOSTIC_TAIL_LINES = 20;
+/** Read a bounded tail of crtrd's stderr log to enrich a `daemon_unavailable`
+ *  cold-start timeout (issue #516: the prior bare message discarded the actual
+ *  startup failure). 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.err'), '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.err (tail):\n${tail}`;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // best-effort close; the read already happened (or failed) above.
+            }
+        }
+    }
+}
+/** 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 — or
+ *  autostart is disabled — the client throws `daemon_unavailable` (spec §7.1,
+ *  §8). This is the ONLY CLI reference to `ensureDaemon`.
+ *
+ *  #508 follow-up: `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. That poll
+ *  used to default to a fixed 10s window while `spawnDaemon`'s
+ *  `verifyDaemonStartup` (which `ensureDaemon`'s spawn transitively awaits, in
+ *  the detached child, on the SAME cold-start path) was widened to 20s for a
+ *  slow-but-valid cold boot: a daemon that took 12s was a valid, verified
+ *  startup, but the CLI process that triggered it still gave up and reported
+ *  `daemon_unavailable` at 10s. Passing the SAME `DAEMON_VERIFY_WINDOW_MS`
+ *  here keeps the two in lockstep — one authoritative window, not two that can
+ *  drift apart — without adding any retry/fallback poll loop. */
+export function cliClient(opts) {
+    if (autostartDisabled()) {
+        return CrtrClient.forLocalSocket({ autostart: false, ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    }
+    return CrtrClient.forLocalSocket({
+        ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        onColdSocket: async () => {
+            // Fire-and-forget spawn; the client's bounded /healthz poll below (sized
+            // to the SAME window spawnDaemon's verifyDaemonStartup uses) owns the
+            // "did it come up?" wait and the loud failure.
+            ensureDaemon();
+        },
+        // On a cold-start timeout, enrich the bare `daemon_unavailable` with the
+        // tail of crtrd's own stderr log (issue #516) instead of discarding it.
+        coldStartDiagnostic: readColdStartDiagnostic,
+        coldStartPollWindowMs: DAEMON_VERIFY_WINDOW_MS,
+    });
+}
+// ---------------------------------------------------------------------------
+// DTO → internal projections
+//
+// The DTO boundary deliberately reshapes internals (spec §3.1), so these are
+// lossy in the read-only direction: fields the API surface does not carry
+// (tmux-presence runtime, per-edge `active`) are defaulted, matching the
+// documented parity bar (structural, not byte-identical). See the mapping notes
+// on each helper.
+// ---------------------------------------------------------------------------
+/** `NodeSummaryDTO` → `NodeRow`. The DTO carries every indexed identity + core
+ *  runtime column; the four fields it omits are LOCAL tmux-presence /
+ *  process-identity runtime (`window`/`tmux_session`/`pane`/`pi_pid_identity`),
+ *  which are meaningless to a remote/pure client and are defaulted to null. A
+ *  viewer reading canvas STRUCTURE never needs them; local placement reads them
+ *  from tmux, not the source. */
+function summaryToRow(s) {
+    return {
+        node_id: s.node_id,
+        name: s.name,
+        kind: s.kind,
+        mode: s.mode,
+        lifecycle: s.lifecycle,
+        status: s.status,
+        cwd: s.cwd,
+        host_kind: s.host_kind,
+        profile_id: s.profile_id,
+        parent: s.parent,
+        created: s.created,
+        intent: s.intent,
+        waiting_for: s.waiting_for,
+        final_report: s.final_report ?? null,
+        finalized_at: s.finalized_at ?? null,
+        pi_pid: s.pi_pid,
+        pi_pid_identity: null,
+        window: null,
+        tmux_session: null,
+        pane: null,
+    };
+}
+/** `NodeDetailDTO` → `NodeMeta`. Populates the durable-identity ∪ runtime fields
+ *  the DTO projects; the durable LAUNCH-RECIPE facts a projection cannot carry
+ *  (`launch`/`env`, `persona_ack`, `human_work_target`, `private_fork_*`,
+ *  `model_override`, `passive_default`, `fork_from`, `pi_session_file`,
+ *  `cycle_pending`) are left undefined — read-only viewer/inspect consumers
+ *  (Stage B-7/B-9) never read them; the daemon owns the full meta for revive. */
+function detailToMeta(d) {
+    return {
+        node_id: d.node_id,
+        name: d.name,
+        description: d.description,
+        cycles: d.cycles,
+        created: d.created,
+        cwd: d.cwd,
+        host_kind: d.host_kind,
+        profile_id: d.profile_id,
+        kind: d.kind,
+        mode: d.mode,
+        lifecycle: d.lifecycle,
+        parent: d.parent,
+        spawned_by: d.edges.spawned_by,
+        pi_session_id: d.pi_session_id ?? null,
+        managed_worktree: d.worktree ?? null,
+        // Runtime (from the authoritative row, projected onto the DTO).
+        status: d.status,
+        intent: d.intent,
+        waiting_for: d.waiting_for,
+        final_report: d.final_report ?? null,
+        finalized_at: d.finalized_at ?? null,
+        pi_pid: d.pi_pid,
+        pi_pid_identity: d.pi_pid_identity ?? null,
+    };
+}
+/** Edge ids → `SubscriptionRef[]`. KNOWN GAP: `NodeEdgesDTO` carries only the
+ *  peer node ids, not the per-edge `active` flag or `created` timestamp (the
+ *  `GET /nodes/{id}` projection built in A-1/A-7 does not expose them). We
+ *  default `active: true` (the SAFE direction — never under-reports a live
+ *  listener) and `created: ''` (matching `RemoteCanvasSource`'s same-shaped
+ *  fallback). Fully faithful `active`/`created` needs an additive DTO extension
+ *  (surface it as objects), which is an A-1/A-7 change, not B-0. */
+// ---------------------------------------------------------------------------
+// ApiCanvasSource — a read CanvasSource backed entirely by the crtrd API
+// ---------------------------------------------------------------------------
+// The attach viewer's recurring subtree walk (chrome/canvas-panels.ts + overlays/graph.ts
+// computeActivity/visitActivity) calls subscriptionsOf/subscribersOf once per
+// visited node on every poll tick; each call was previously its own
+// `GET /v1/nodes/:id` round trip just to read the edge list off the detail DTO.
+// This short-TTL cache backs those two methods with the lean roster
+// (`GET /v1/canvas/roster`) instead — one shared fetch per TTL window covers
+// every topology walk in that window, comfortably under the attach viewer's 5s
+// poll cadence. Scoped to subscriptionsOf/subscribersOf only: listNodes/getRow
+// stay on the full per-id/list HTTP path because the roster does not carry the
+// runtime fields (intent/waiting_for/pi_pid/etc) those two already populate for
+// real from the full DTO — backing them with the roster would silently null out
+// live display fields, not just the already-lossy tmux-presence ones.
+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.roster;
+        }
+        if (this.rosterInFlight !== null)
+            return this.rosterInFlight;
+        this.rosterInFlight = this.client
+            .canvasRoster()
+            .then((roster) => {
+            this.rosterCache = { at: Date.now(), roster };
+            return roster;
+        })
+            .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 ? detailToMeta(detail) : null;
+    }
+    async getRow(nodeId) {
+        const detail = await this.orNull(() => this.client.getNode(nodeId));
+        return detail ? summaryToRow(detail) : null;
+    }
+    async listNodes(filter) {
+        const status = filter?.status;
+        let rows;
+        if (Array.isArray(status)) {
+            // The list query takes a single status; fetch all + filter client-side to
+            // honor a multi-status filter without N round-trips.
+            const wanted = new Set(status);
+            const all = await this.client.listNodes();
+            rows = all.filter((r) => wanted.has(r.status));
+        }
+        else if (status !== undefined) {
+            rows = await this.client.listNodes({ status });
+        }
+        else {
+            rows = await this.client.listNodes();
+        }
+        return rows.map(summaryToRow);
+    }
+    async subscriptionsOf(subscriber) {
+        const roster = await this.roster();
+        return roster.edges
+            .filter((e) => e.from_id === subscriber)
+            .map((e) => ({ node_id: e.to_id, active: e.active, created: e.created }));
+    }
+    async subscribersOf(publisher) {
+        const roster = await this.roster();
+        return roster.edges
+            .filter((e) => e.to_id === publisher)
+            .map((e) => ({ node_id: e.from_id, active: e.active, created: e.created }));
+    }
+    /** 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 ticketCountsForView(root) {
+        const ids = [root, ...await this.view(root)];
+        return (await this.client.attentionCounts(ids)).counts;
+    }
+    /** 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 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) {
+    const scope = opts?.scope ?? 'user';
+    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;