@north-light/crouter-api 0.3.156

package/dist/dto/broker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The crtrd broker `error` control frame — `{ code, message, id? }`. `id` is a
+ * correlation token echoed only from the request that failed (a read-op /
+ * `dequeue`); absent on uncorrelated errors. There is NO `retryable` field.
+ */
+export interface BrokerErrorFrame {
+    type: 'error';
+    code: string;
+    message: string;
+    /** Correlation token, echoed from the failed request; absent on uncorrelated errors. */
+    id?: string;
+}
+/**
+ * The `welcome` frame's history/state snapshot, narrowed to what a relay consumer
+ * replays: the message history and the streaming flag. `M` is the message shape
+ * (pi's `AgentMessage` in a pi consumer; `unknown` by default).
+ */
+export interface BrokerWelcomeSnapshot<M = unknown> {
+    messages: M[];
+    state?: {
+        isStreaming?: boolean;
+    };
+}
+/**
+ * The crtrd broker `welcome` control frame — the history/resume catch-up snapshot
+ * delivered on (re)attach.
+ */
+export interface BrokerWelcomeFrame<M = unknown> {
+    type: 'welcome';
+    snapshot?: BrokerWelcomeSnapshot<M>;
+}
+/**
+ * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot)
+ * and `error`. The broker interleaves others (display_*, control_changed, ack, …)
+ * under non-colliding `type` discriminants; a relay mapper drops those through its
+ * `default` arm untyped, so they are not enumerated here.
+ */
+export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerErrorFrame;
+/**
+ * What the crtrd broker attach delivers to a relay consumer: the live engine
+ * event stream (`E` — pi's `AgentSessionEvent`, relayed verbatim) unioned with the
+ * broker's own control frames. Discriminants never collide: an `AgentSessionEvent`
+ * owns no `welcome` / `error` `type`.
+ */
+export type BrokerAttachFrame<E, M = unknown> = E | BrokerControlFrame<M>;

package/dist/dto/broker.js

@@ -0,0 +1,20 @@
+// Broker attach-protocol envelope DTOs — the crtrd-specific control frames the
+// broker interleaves around pi's native agent-session event stream over a node's
+// `view.sock` (and its WS bridge, spec §5). This module owns ONLY that envelope
+// vocabulary: the two broker-control frames a relay consumer reads (`welcome` +
+// `error`), the welcome snapshot they carry, and the relay union that folds them
+// together with the live engine event stream.
+//
+// PURITY (spec §3.1): like every file under `src/api/`, this imports NOTHING —
+// not `core/*`, not pi. The live engine event type (pi's `AgentSessionEvent`)
+// and the snapshot message type (pi's `AgentMessage`) are left as TYPE PARAMETERS
+// so a consumer instantiates them with the exact pi shapes it pins, while this
+// package stays zero-dependency. A pi-free consumer can leave them at their
+// `unknown` defaults.
+//
+// NARROWING NOTE: `BrokerWelcomeSnapshot` is deliberately the fields a live/history
+// relay mapper reads — `messages` plus `state.isStreaming` — not the broker's full
+// authoritative `BrokerSnapshot` (stats + the complete `get_state` mirror). The
+// broker sends the richer object on the wire; consumers that only replay history
+// read this narrowing of it.
+export {};

package/dist/dto/canvas.d.ts

@@ -0,0 +1,253 @@
+import type { Cursor, IsoTime, NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { NodeSummaryDTO } from './nodes.js';
+/** `GET /v1/nodes` + `GET /v1/status` composed for the dashboard view. */
+export interface DashboardQuery {
+    /** Restrict to the subtree under this node. */
+    under?: NodeIdDTO;
+}
+export interface DashboardDTO {
+    nodes: NodeSummaryDTO[];
+    /** Node counts keyed by status. */
+    counts: Partial<Record<NodeStatusDTO, number>>;
+    generated_at: IsoTime;
+}
+/** A node needing attention (tickets across the canvas). Projected from the
+ *  `TicketEntry` reader — one entry per node with open human tickets. */
+export interface AttentionItemDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    cwd: string;
+    /** Number of open tickets on this node. */
+    count: number;
+}
+/** `GET /v1/canvas/attention` result. */
+export interface AttentionDTO {
+    items: AttentionItemDTO[];
+}
+/** `POST /v1/canvas/attention/counts` request. Restrict the synchronous inbox
+ * scan to the nodes a viewer is actually rendering instead of enriching the
+ * entire canvas roster. */
+export interface AttentionCountsRequest {
+    node_ids: NodeIdDTO[];
+}
+/** `POST /v1/canvas/attention/counts` result, keyed by requested node id. */
+export interface AttentionCountsDTO {
+    counts: Record<NodeIdDTO, number>;
+}
+/** `POST /v1/canvas/history/search` body — the ranked/filtered search over the
+ *  per-cwd episodic corpus, backing `crtr canvas history search` (optional
+ *  query: ranked when present, recency browse when omitted). The CLI parses +
+ *  validates flags (`--type` set, `--since`/`--until` → epoch ms) and sends
+ *  this normalized query; the server runs `buildCorpus` + ranking + pagination
+ *  (closures like `loadBody` cannot cross the boundary, so the whole search
+ *  executes server-side). Sent as POST — the query carries arrays and
+ *  free-text that do not serialize cleanly as GET params. */
+export interface HistorySearchQuery {
+    /** Whitespace-separated terms, ranked; omit to browse by recency. */
+    query?: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    /** Restrict to specific node ids. */
+    nodes?: string[];
+    /** Corpus types: report | doc | roadmap | meta | inbox. */
+    types?: string[];
+    report_kind?: string;
+    kinds?: string[];
+    statuses?: string[];
+    /** Lower bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    since_ms?: number;
+    /** Upper bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    until_ms?: number;
+    /** Weigh full body text in ranking (`--body`). */
+    weigh_body?: boolean;
+    /** relevance | recency | oldest — already resolved to the effective sort. */
+    sort?: string;
+    snippet_lines?: number;
+    full?: boolean;
+    limit?: number;
+    cursor?: Cursor;
+}
+/** `POST /v1/canvas/history/search` result. `hits` is heterogeneous by mode
+ *  (with/without a relevance score, snippet vs full body), so it stays a
+ *  loose object list — the CLI's renderer already treats hits as
+ *  `Record<string, unknown>[]`. The static `follow_up` line is appended
+ *  CLI-side. */
+export interface HistorySearchResultDTO {
+    hits: Record<string, unknown>[];
+    next_cursor: Cursor | null;
+    total: number;
+}
+/** `POST /v1/canvas/history/grep` body — the required-pattern line-hit search
+ *  over the per-cwd episodic corpus, backing `crtr canvas history grep`.
+ *  Shares scope/corpus filters with `HistorySearchQuery` but is a distinct
+ *  wire contract: `pattern` is mandatory (an ECMAScript regex) and there is no
+ *  ranking/snippet/full-body shape. */
+export interface HistoryGrepQuery {
+    /** Required ECMAScript regex, matched per body line (case-insensitive). */
+    pattern: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    /** Restrict to specific node ids. */
+    nodes?: string[];
+    /** Corpus types: report | doc | roadmap | meta | inbox. */
+    types?: string[];
+    report_kind?: string;
+    kinds?: string[];
+    statuses?: string[];
+    /** Lower bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    since_ms?: number;
+    /** Upper bound on artifact timestamp (epoch ms), parsed CLI-side. */
+    until_ms?: number;
+    limit?: number;
+    cursor?: Cursor;
+}
+/** One matching body line from `crtr canvas history grep`. */
+export interface HistoryGrepHitDTO {
+    ref: string;
+    /** "name (id)". */
+    node: string;
+    ts: IsoTime;
+    line: number;
+    text: string;
+}
+/** `POST /v1/canvas/history/grep` result — a stable line-hit schema, distinct
+ *  from `HistorySearchResultDTO`'s heterogeneous ranked/browse shape. */
+export interface HistoryGrepResultDTO {
+    hits: HistoryGrepHitDTO[];
+    next_cursor: Cursor | null;
+    total: number;
+}
+/** `GET /v1/canvas/history/read` query — resolve one `<node-id>:<relpath>` ref. */
+export interface HistoryReadQuery {
+    ref: string;
+    /** Keep the artifact's YAML frontmatter (stripped by default). */
+    frontmatter?: boolean;
+}
+/** `GET /v1/canvas/history/read` result — one hit's full body. */
+export interface HistoryReadResultDTO {
+    ref: string;
+    /** "name (id)". */
+    node: string;
+    /** report:<kind> | doc | roadmap | meta | inbox. */
+    source: string;
+    ts: IsoTime;
+    content: string;
+}
+/** One node row in the browser canvas roster (`GET /v1/canvas/snapshot`). A
+ *  richer projection than `NodeSummaryDTO`: it carries the enriched viewer
+ *  fields (`dashboardRowsAll` + `enrichRows`) the browser canvas renders —
+ *  attention counts, ctx tokens, streaming/hanging/viewed state, last activity. */
+export interface SnapshotNodeDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    kind: string;
+    mode: string;
+    lifecycle?: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    parent: NodeIdDTO | null;
+    created: IsoTime;
+    host_kind: string;
+    /** True when the node hosts an enterable broker (`host_kind === 'broker'`). */
+    enterable: boolean;
+    attention_count: number;
+    cycles?: number;
+    last_activity?: IsoTime;
+    ctx_tokens?: number;
+    streaming: boolean;
+    /** The node's active fault projection (structurally a `Fault`), or null. Kept
+     *  as a loose object to keep this DTO free of a `core` type import. */
+    hanging: Record<string, unknown> | null;
+    viewed: boolean;
+}
+/** `GET /v1/canvas/snapshot` result — the machine-readable browser canvas
+ *  roster (`crtr canvas snapshot`). Distinct from the per-node `NodeSnapshotDTO`
+ *  (nodes.ts). `subscriptions` is the authoritative `subscribes_to` adjacency
+ *  map: each node id → its publisher/child node ids in edge order. */
+export interface SnapshotDTO {
+    generated_at: IsoTime;
+    nodes: SnapshotNodeDTO[];
+    subscriptions: Record<string, NodeIdDTO[]>;
+}
+/** One node row in the lean roster (`GET /v1/canvas/roster`). Carries only
+ *  columns already native to the `nodes` row — no meta.json read, no
+ *  process-liveness probe. `attention_count`/`last_activity`/`ctx_tokens`/
+ *  `streaming`/`hanging`/`viewed` stay on `SnapshotNodeDTO`; a roster consumer
+ *  that needs attention counts fetches them separately via the existing
+ *  `POST /v1/canvas/attention/counts` (already scoped to exactly the ids it
+ *  renders, never the whole canvas). */
+export interface RosterNodeDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    kind: string;
+    mode: string;
+    lifecycle?: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    host_kind: string;
+    /** True when the node hosts an enterable broker (`host_kind === 'broker'`). */
+    enterable: boolean;
+    parent: NodeIdDTO | null;
+    created: IsoTime;
+}
+/** One `subscribes_to` edge in the roster's topology half. Every edge is kept
+ *  (passive + multiple per node) — never collapsed to one edge per node. */
+export interface RosterEdgeDTO {
+    from_id: NodeIdDTO;
+    to_id: NodeIdDTO;
+    active: boolean;
+    created: IsoTime;
+}
+/** `GET /v1/canvas/roster` result — the lean, set-based topology read shared by
+ *  the attach viewer and the browser canvas: exactly two indexed queries
+ *  (`rosterNodes()` + `rosterEdges()`), no `enrichRows`, no per-row
+ *  `getNode`/`subscriptionsOf` loop, no synchronous liveness probe. The
+ *  recurring poll target that replaces the enriched `/v1/canvas/snapshot`
+ *  storm; that endpoint remains for genuinely on-demand rich views. */
+export interface RosterDTO {
+    generated_at: IsoTime;
+    nodes: RosterNodeDTO[];
+    edges: RosterEdgeDTO[];
+}
+/** `POST /v1/canvas/prune` body — the three exclusive prune modes of
+ *  `crtr canvas prune`, precedence COUNT (`limit`) > EMPTY (`empty`) > TTL sweep. */
+export interface PruneRequest {
+    /** COUNT mode: keep the N most-recently-active nodes, prune the oldest
+   *   remaining terminal nodes (protected nodes always survive). */
+    limit?: number;
+    /** TTL sweep retention window in days (default 14). */
+    ttl_days?: number;
+    /** TTL sweep: also prune stale active/idle nodes past the TTL whose process
+   *   is provably gone. */
+    include_stale?: boolean;
+    /** EMPTY mode: reap nodes whose engine never produced an assistant message. */
+    empty?: boolean;
+    /** Report what would be pruned without mutating. */
+    dry_run?: boolean;
+}
+/** One node in a prune result (pruned, or candidate under `dry_run`). */
+export interface PrunedNodeDTO {
+    node_id: NodeIdDTO;
+    /** Lifecycle status, or `empty` for EMPTY-mode reaps. */
+    status: string;
+    /** ISO created timestamp (empty string for EMPTY-mode reaps). */
+    created: string;
+}
+/** `POST /v1/canvas/prune` result. `pruned` is the pruned set (or, under
+ *  `dry_run`, the candidate set — nothing deleted). `ttl_days` echoes the
+ *  retention window used. */
+export interface PruneResultDTO {
+    pruned: PrunedNodeDTO[];
+    dry_run: boolean;
+    ttl_days: number;
+}
+/** `POST /v1/canvas/rebuild-index` result. Fails loud server-side when metas
+ *  exist on disk but the rebuild yields zero rows (a corrupt/empty index). */
+export interface RebuildIndexResultDTO {
+    /** How many `nodes/<id>/meta.json` files were found on disk. */
+    metas: number;
+    /** How many node rows exist in canvas.db after the rebuild. */
+    rows: number;
+}

package/dist/dto/canvas.js

@@ -0,0 +1,2 @@
+// Canvas-wide read + maintenance DTOs (spec §6.3).
+export {};

package/dist/dto/common.d.ts

@@ -0,0 +1,27 @@
+/** ISO-8601 timestamp string (matches the runtime's `nowIso()` output). */
+export type IsoTime = string;
+/** A node id — the existing `<slug>-<hash>` string. Typed as a nominal alias so
+ *  DTOs read as thin projections; validated at the boundary by `isSafeNodeId`. */
+export type NodeIdDTO = string;
+/** Opaque pagination cursor (server-defined; clients pass it back verbatim). */
+export type Cursor = string;
+/** Standard list-pagination inputs shared by paged queries. */
+export interface Pagination {
+    limit?: number;
+    cursor?: Cursor;
+}
+/** Runtime status of a node (mirrors the runtime `NodeStatus` union; declared
+ *  locally to keep `/api` free of any `core/*` import). */
+export type NodeStatusDTO = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** Lifecycle class of a node (mirrors the runtime `Lifecycle` union). */
+export type LifecycleDTO = 'terminal' | 'resident';
+/** Execution mode of a node (mirrors the runtime `Mode` union). */
+export type ModeDTO = 'base' | 'orchestrator';
+/** Why a node last stopped (mirrors the runtime `ExitIntent` union). */
+export type ExitIntentDTO = 'done' | 'refresh' | 'idle-release' | null;
+/** Inbox urgency tier for a delivered message (mirrors feed/inbox `InboxTier`). */
+export type InboxTierDTO = 'critical' | 'urgent' | 'normal' | 'deferred';
+/** Whether a node id is a safe single filesystem path segment. Re-declared here
+ *  (not imported from `core/canvas/paths.ts`) to keep the exported `/api`
+ *  contract dependency-light; kept byte-for-byte equivalent to the runtime's. */
+export declare function isSafeNodeId(id: string): boolean;

package/dist/dto/common.js

@@ -0,0 +1,15 @@
+// Shared scalars and cross-cutting DTO primitives.
+//
+// PURITY (spec §3.1): this file — like every file under `src/api/` — imports
+// ONLY other `src/api/*` modules and Node built-ins. Never `core/*`,
+// `node:sqlite`, TUI, or any heavy runtime module.
+const MAX_NODE_ID_BYTES = 128;
+/** Whether a node id is a safe single filesystem path segment. Re-declared here
+ *  (not imported from `core/canvas/paths.ts`) to keep the exported `/api`
+ *  contract dependency-light; kept byte-for-byte equivalent to the runtime's. */
+export function isSafeNodeId(id) {
+    return typeof id === 'string'
+        && id !== '' && id !== '.' && id !== '..'
+        && !/[\\/\0]/u.test(id)
+        && Buffer.byteLength(id, 'utf8') <= MAX_NODE_ID_BYTES;
+}

package/dist/dto/config.d.ts

@@ -0,0 +1,19 @@
+import type { LifecycleDTO, ModeDTO } from './common.js';
+/** `PATCH /v1/nodes/{id}/config` body. All fields optional; a set field is
+ *  applied, an absent field is untouched. */
+export interface NodeConfigPatch {
+    /** Model tier or exact selection override. */
+    model?: string;
+    /** Thinking/reasoning level override. */
+    thinking?: string;
+    /** Ambient situational-context text override. */
+    situational_context?: string;
+    /** Persona kind respecialization — rebuilds the launch spec server-side. */
+    kind?: string;
+    /** Persona mode; setting `orchestrator` seeds a roadmap scaffold if absent. */
+    mode?: ModeDTO;
+    /** Lifecycle flip (terminal↔resident), rebuilding the launch spec. */
+    lifecycle?: LifecycleDTO;
+    /** Rename the node (and, when it has a live viewer window, that window). */
+    name?: string;
+}

package/dist/dto/config.js

@@ -0,0 +1,3 @@
+// Node config-patch DTO (spec §6.2). Dormant → row write; live → `view.sock`
+// `set_model` — the liveness branch runs server-side; the CLI just PATCHes.
+export {};

package/dist/dto/crons.d.ts

@@ -0,0 +1,124 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+export type CronScopeDTO = 'profile' | 'global';
+export type CronOverlapDTO = 'skip' | 'queue' | 'replace';
+export type CronOnOutputDTO = 'silent' | 'on-failure' | 'always' | 'on-change';
+export type CronStateDTO = 'active' | 'paused';
+export type CronRunStateDTO = 'idle' | 'running';
+/** Is this a safe single path segment for `routes.cron*()` interpolation?
+ *  Cron ids are server-minted UUIDs, but the route builders carry no logic, so
+ *  every interpolated id is gated here first (the `isSafeNodeId` discipline). */
+export declare function isSafeCronId(id: string): boolean;
+/** The last settled run, carried on every cron projection so `cron list` shows
+ *  recent health without a `cron show` per row. Null until the first run. */
+export interface CronLastRunDTO {
+    /** When the run settled (UTC). */
+    finished: IsoTime | null;
+    /** -1 = timeout kill; null = no exit observed (process error / skip marker). */
+    exit_code: number | null;
+    /** What the sink did with the output, or why it didn't. */
+    delivered: string | null;
+}
+/** A cron row projection (`GET /v1/crons`). */
+export interface CronDTO {
+    cron_id: string;
+    /** Agent-legible label; how the cron shows in list. */
+    name: string;
+    /** Provenance only — the node that armed it, if any; never a cascade anchor. */
+    created_by: NodeIdDTO | null;
+    /** The bash command each fire runs. */
+    command: string;
+    /** Next occurrence (UTC). */
+    fire_at: IsoTime;
+    /** Recur JSON (interval or cron); null for a one-shot. */
+    recur: string | null;
+    /** IANA zone for a calendar cadence; null otherwise. */
+    tz: string | null;
+    /** Clock bound; the row is deleted when passed. Null = no bound. */
+    expires_at: IsoTime | null;
+    /** Opt-in node coupling (cascades on that node's deletion); null = detached. */
+    anchor_node: NodeIdDTO | null;
+    cancel_on_wake: boolean;
+    /** Execution context, snapshotted at arm time. */
+    cwd: string;
+    profile: string | null;
+    scope: CronScopeDTO;
+    /** Names of the extra env vars snapshotted onto the row — KEYS ONLY: the
+     *  values are the caller's to know and may be secrets. */
+    env_keys: string[];
+    run_timeout_s: number;
+    overlap: CronOverlapDTO;
+    on_output: CronOnOutputDTO;
+    /** Where deliveries go — the raw sink spec (`node:<id>` | `spawn:<kind>` |
+     *  `human`), or null when the disposition never delivers. */
+    sink: string | null;
+    tier: string;
+    state: CronStateDTO;
+    run_state: CronRunStateDTO;
+    /** Recent health: the most recent settled run, or null if it never ran. */
+    last_run: CronLastRunDTO | null;
+    created: IsoTime;
+    updated: IsoTime;
+}
+/** `GET /v1/crons` query. `profile` is the CALLER's profile, which is what
+ *  scoping means here: a profile-scoped cron belongs to its profile, a global
+ *  one is canvas-home-wide. Omitting `profile` means the caller stands outside
+ *  every profile (a plain shell, or a provenance read such as "which crons did
+ *  node X arm") and sees the whole canvas home. This is a namespacing
+ *  boundary between profiles, not a security boundary. */
+export interface ListCronsQuery {
+    profile?: string;
+}
+/** Caller identity for the per-cron routes (show/pause/resume/run/cancel).
+ *  Same rule as `ListCronsQuery`: a cron outside the caller's scope is 404,
+ *  and an absent profile sees everything. */
+export interface CronScopeQuery {
+    profile?: string | null;
+}
+/** One settled run-log entry (`GET /v1/crons/:cronId`, `POST /v1/crons/:cronId/run`). */
+export interface CronRunDTO {
+    run_id: string;
+    started: IsoTime;
+    finished: IsoTime | null;
+    duration_ms: number | null;
+    /** null = no exit observed (spawn/process error, or a skip marker); -1 = timeout kill. */
+    exit_code: number | null;
+    stdout_head: string | null;
+    stderr_head: string | null;
+    /** What the sink did with this run's output, or why it didn't. */
+    delivered: string | null;
+}
+/** `GET /v1/crons/:cronId` — one cron with its run-log ring (most recent first). */
+export interface CronShowDTO {
+    cron: CronDTO;
+    runs: CronRunDTO[];
+}
+/** `POST /v1/crons` — arm one cron. The CLI resolves timing client-side
+ *  (parseWhen/parseCadence) and sends the settled `fire_at`/`recur`/`tz`;
+ *  the server mints the cron_id and applies spec defaults for everything
+ *  omitted. */
+export interface ArmCronRequest {
+    name: string;
+    command: string;
+    fire_at: IsoTime;
+    recur?: string | null;
+    tz?: string | null;
+    created_by?: NodeIdDTO | null;
+    /** Execution context, snapshotted at arm time — chosen by the client, else
+     *  inherited from the creating node; never re-resolved at run time. */
+    cwd: string;
+    /** Extra env for every run, as a JSON object of string values. */
+    env_json?: string | null;
+    profile?: string | null;
+    /** `profile` (default when a profile is resolved) requires a profile. */
+    scope?: CronScopeDTO;
+    on_output?: CronOnOutputDTO;
+    /** Raw sink spec: `node:<id>` | `spawn:<kind>` | `human`. Required by the
+     *  always/on-change dispositions; meaningless otherwise. */
+    sink?: string | null;
+    tier?: string;
+    expires_at?: IsoTime | null;
+    anchor_node?: NodeIdDTO | null;
+    cancel_on_wake?: boolean;
+    run_timeout_s?: number;
+    overlap?: CronOverlapDTO;
+}

package/dist/dto/crons.js

@@ -0,0 +1,10 @@
+// Cron DTOs (the cron-spec scheduler — arm/list/show/run/pause/resume/cancel).
+/** Is this a safe single path segment for `routes.cron*()` interpolation?
+ *  Cron ids are server-minted UUIDs, but the route builders carry no logic, so
+ *  every interpolated id is gated here first (the `isSafeNodeId` discipline). */
+export function isSafeCronId(id) {
+    return typeof id === 'string'
+        && id !== '' && id !== '.' && id !== '..'
+        && !/[\\/\0\s?#%]/u.test(id)
+        && Buffer.byteLength(id, 'utf8') <= 128;
+}

package/dist/dto/files.d.ts

@@ -0,0 +1,11 @@
+/** `GET /v1/files/peek?path=<abs>` result — the UTF-8 contents of an absolute
+ *  host path, truncated to a byte cap (the panel shows a partial-content notice
+ *  when `truncated` is set). */
+export interface FilePeekDTO {
+    /** The absolute path read (echoes the request). */
+    path: string;
+    /** UTF-8 file contents (a prefix when `truncated`). */
+    content: string;
+    /** True when the file exceeded the read cap and `content` is a prefix. */
+    truncated: boolean;
+}

package/dist/dto/files.js

@@ -0,0 +1,7 @@
+// Host file-read DTO (spec §6). Backs `GET /v1/files/peek` — the browser
+// file-peek panel reads an absolute host path shown in a transcript tool card.
+// A single trusted local user (unix socket); the browser reaches it only
+// through the auth-gated web proxy.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/dto/focus.d.ts

@@ -0,0 +1,24 @@
+import type { NodeIdDTO } from './common.js';
+/** One viewer row: a node's single on-screen pane in a tmux session. */
+export interface FocusDTO {
+    focus_id: string;
+    pane: string | null;
+    session: string | null;
+    node_id: NodeIdDTO;
+}
+/** `POST /v1/focuses` body — register a viewer pane as a node's focus row.
+ *  UNIQUE(node_id): returns the existing row (no insert) when the pane or node
+ *  is already registered. `window` is accepted for the call contract but not
+ *  stored (the table keys on pane + session). */
+export interface RegisterFocusRequest {
+    node_id: NodeIdDTO;
+    pane: string;
+    session: string | null;
+    window: string | null;
+}
+/** `PATCH /v1/focuses/{focus_id}` body — re-point a viewer row's pane + its
+ *  derived session cache after the pane moves. */
+export interface SetFocusPaneRequest {
+    pane: string | null;
+    session: string | null;
+}

package/dist/dto/focus.js

@@ -0,0 +1,10 @@
+// Focus DTOs (the viewer registry — canvas.db `focuses` table). A FOCUS is one
+// durable on-screen viewport bound to one node (UNIQUE node_id ⇒ ≤1 per node).
+// The wire shape mirrors the internal `FocusRow` 1:1 — the registry is a flat
+// pane↔node binding with no projection to reshape.
+//
+// The reads GC lazily server-side (a row whose pane is gone is pruned on read),
+// so a returned row is always live. The mutations are the tmux-driven CLI
+// surfaces' (surface-tmux-spread, focus placement) writes: the tmux verbs run
+// LOCALLY in the caller's session; only the canvas.db focus rows route here.
+export {};

package/dist/dto/health.d.ts

@@ -0,0 +1,41 @@
+import type { NodeStatusDTO } from './common.js';
+/** `GET /healthz` — substrate readiness probe. Versions are informational, never
+ *  a gate. Used by the provisioning ladder. */
+export interface HealthDTO {
+    ok: boolean;
+    daemon_up: boolean;
+    store_accessible: boolean;
+    brokers_reconciled: boolean;
+}
+/** `GET /v1/status` — daemon status snapshot. Backs `crtr sys daemon status`
+ *  state and the `crtr canvas dashboard` header. Versions are informational. */
+export interface StatusDTO {
+    daemon_pid: number;
+    tick_interval_ms: number;
+    /** Node counts keyed by status. */
+    node_counts: Partial<Record<NodeStatusDTO, number>>;
+    /** Bound listener addresses. `tcp` is null when the TCP listener is off. */
+    listeners: {
+        socket_path: string;
+        tcp: string | null;
+    };
+    runtime_version: string;
+    api_version: string;
+}
+/** `POST /v1/daemon/restart` — the ack for a daemon-owned handover.
+ *
+ *  The daemon answers BEFORE it tears anything down: the caller is normally a
+ *  node's own bash tool, whose broker this handover will kill, so the ack must
+ *  be a settled tool result in that node's transcript before the SIGTERM lands.
+ *  `accepted` is therefore a promise about the future, not a completed action —
+ *  the successor daemon is spawned after `grace_ms`, and every node the
+ *  teardown interrupts is resumed by it. */
+export interface DaemonRestartDTO {
+    accepted: boolean;
+    /** The daemon that took the request and is about to hand over. */
+    predecessor_pid: number;
+    /** Its epoch id — the successor mints a new one. */
+    predecessor_epoch: string;
+    /** How long the daemon waits after answering before teardown begins. */
+    grace_ms: number;
+}

package/dist/dto/health.js

@@ -0,0 +1,2 @@
+// Health / status DTOs (spec §6.1).
+export {};