@crouter/api 0.3.377

package/dist/api/dto/canvas.d.ts

@@ -0,0 +1,359 @@
+import type { Cursor, IsoTime, NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { NodeFaultDTO, 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;
+    /** Open ticket titles for this node, newest first — one per counted ticket. */
+    subjects: string[];
+}
+/** `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 conversation corpus (inboxes and transcripts), 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: inbox | transcript. */
+    types?: 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;
+    /** Inbound-message narrowing (transcript + inbox): what drove arrival. */
+    origins?: string[];
+    /** Transcript-message roles: user | assistant | toolResult. */
+    roles?: string[];
+    /** Case-insensitive substring against sender attribution. */
+    from?: string;
+    /** 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 conversation corpus (inboxes and transcripts), 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: inbox | transcript. */
+    types?: 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;
+    /** Inbound-message narrowing (transcript + inbox): what drove arrival. */
+    origins?: string[];
+    /** Transcript-message roles: user | assistant | toolResult. */
+    roles?: string[];
+    /** Case-insensitive substring against sender attribution. */
+    from?: string;
+    limit?: number;
+    cursor?: Cursor;
+}
+/** `POST /v1/canvas/history/stats` body — the grouped-count projection over
+ *  the same corpus search and grep scan, backing `crtr canvas history stats`.
+ *  Shares every scope/corpus/message filter; carries no query, pattern, or
+ *  pagination because the result is an aggregate, not a hit list. */
+export interface HistoryStatsQuery {
+    /** origin | node | kind | day | type | role. Defaults to type. */
+    group_by?: string;
+    cwd?: string;
+    all_cwds?: boolean;
+    under?: string;
+    nodes?: string[];
+    types?: string[];
+    kinds?: string[];
+    statuses?: string[];
+    since_ms?: number;
+    until_ms?: number;
+    origins?: string[];
+    roles?: string[];
+    from?: string;
+}
+/** `POST /v1/canvas/history/stats` result — counts by the grouped dimension,
+ *  descending. `total` counts the artifacts that carried the dimension, so it
+ *  can be lower than the corpus size when grouping by one not every artifact
+ *  has (origin, role). */
+export interface HistoryStatsResultDTO {
+    group_by: string;
+    groups: Array<{
+        key: string;
+        count: number;
+    }>;
+    total: number;
+    /** Artifacts scanned before the grouping dimension was applied. */
+    scanned: number;
+}
+/** 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>:inbox/<n>`,
+ *  `<node-id>:session` or `<node-id>:session/<n>` ref. */
+export interface HistoryReadQuery {
+    ref: string;
+    /** `rendered` (default) or `raw` — the verbatim bytes behind the ref: the
+     *  session file for a bare `session` ref, the one jsonl line for a message. */
+    format?: string;
+}
+/** `GET /v1/canvas/history/read` result — one hit's full body. */
+export interface HistoryReadResultDTO {
+    ref: string;
+    /** "name (id)". */
+    node: string;
+    /** inbox | transcript. */
+    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;
+    /** Caller-supplied node title, kept separate from the enriched full label. */
+    title: string;
+    /** Caller-supplied node brief, or null when absent. */
+    description: string | null;
+    kind: string;
+    mode: string;
+    lifecycle?: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    /** The profile this node runs under; null for a historical no-profile row.
+     *  Carried here because it is the only field that says WHOSE work a node is —
+     *  a snapshot consumer grouping nodes by agent has nothing else to key on. */
+    profile_id: string | null;
+    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;
+    /** Number of active background bash jobs, reported only for a live broker. */
+    jobs_active: number;
+    /** Controller node this node is durably waiting for, or null. */
+    waiting_for: string | null;
+    /** 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;
+    /** Basename of the node's final report, or null when it never pushed one.
+     *  Presence — not `status === 'done'` — is what distinguishes finished work
+     *  from clean parking. */
+    final_report: string | null;
+    finalized_at: IsoTime | null;
+}
+/** `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
+ *  stored node fields, without a 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[];
+}
+/** Browse's initial frame needs the dashboard fields and topology, not the full
+ * node detail/list projection. Transported as gzip JSON (application/gzip) over
+ * the local socket; other /v1/nodes consumers keep their original response. */
+export interface BrowseNodeDTO {
+    node_id: string;
+    name: string;
+    description?: string;
+    kind: string;
+    mode: string;
+    lifecycle: string;
+    status: NodeStatusDTO;
+    cwd: string;
+    profile_id: string | null;
+    grantee: string;
+    parent: string | null;
+    created: IsoTime;
+    frozen_at: IsoTime | null;
+    terminal_reason: string | null;
+    final_report: string | null;
+    telemetry_tokens_in: number | null;
+    telemetry_updated_at: IsoTime | null;
+    fault: import('./nodes.js').NodeFaultDTO | null;
+    streaming: boolean;
+}
+export interface BrowseCanvasDTO {
+    nodes: BrowseNodeDTO[];
+    edges: RosterEdgeDTO[];
+}
+/** One row in `GET /v1/canvas/graph`: exactly the node fields the attach graph displays. */
+export interface GraphNodeDTO {
+    node_id: NodeIdDTO;
+    name: string;
+    description: string | null;
+    cycles: number | null;
+    kind: string;
+    status: NodeStatusDTO;
+    frozen_at: IsoTime | null;
+    pi_pid: number | null;
+    telemetry_context_tokens: number | null;
+    telemetry_last_activity: string | null;
+    fault: NodeFaultDTO | null;
+    streaming: boolean;
+}
+/** `GET /v1/canvas/graph` — the attach graph's one-read projection: display rows, subscription topology, and the current local viewer-focus set. */
+export interface GraphDTO {
+    generated_at: IsoTime;
+    nodes: GraphNodeDTO[];
+    edges: RosterEdgeDTO[];
+    focused_node_ids: NodeIdDTO[];
+}
+/** `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;
+}

package/dist/api/dto/canvas.js

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

package/dist/api/dto/chat-inventory.d.ts

@@ -0,0 +1,56 @@
+/** One command a chat surface may advertise. Builtin and non-opted-in rows are
+ *  dropped before this DTO exists, so `source` never carries `'builtin'`. */
+export interface ChatInventoryCommandDTO {
+    /** No leading slash, exactly as the engine dispatches it. */
+    name: string;
+    description: string;
+    source: 'command' | 'template';
+    /** Argument shape to display beside the name, when the command supplies one. */
+    argument_hint?: string;
+    /** Deterministic expansion metadata for a memory-slash command — the same
+     *  material the terminal preview uses, so a chat preview cannot drift from
+     *  what submission sends. */
+    expansion?: {
+        kind: 'memory-slash';
+        commandName: string;
+        body: string;
+    };
+    /** Raw prompt-template content (frontmatter stripped), for `source: 'template'`. */
+    template?: string;
+}
+/** One resolvable inline memory reference. Metadata only — never the document
+ *  body or its source path. `shortForm` stays camelCase to mirror the broker's
+ *  own `RefMeta`, which is where these rows come from. */
+export interface ChatInventoryMemoryRefDTO {
+    /** Canonical `/`-joined name, e.g. `taste/writing`. */
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+}
+/** `GET /v1/nodes/{id}/chat-inventory` result.
+ *
+ *  `broker_live` reports whether the node's engine was reachable at all. There
+ *  is no per-part error flag: a part that failed and a part that is genuinely
+ *  empty both arrive as an empty array, and a client's behavior is identical
+ *  for both. A dormant node answers 200 with `broker_live: false` — this read
+ *  never revives an engine. */
+export interface ChatInventoryDTO {
+    node_id: string;
+    broker_live: boolean;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+/** Session-less inventory for the launch target a create would resolve. */
+export interface ProspectiveChatInventoryDTO {
+    profile_id: string | null;
+    cwd: string;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export interface ProspectiveChatInventoryQuery {
+    profile?: string;
+    cwd?: string;
+    /** Same optional kind operand as POST /v1/nodes. */
+    kind?: string;
+}

package/dist/api/dto/chat-inventory.js

@@ -0,0 +1,11 @@
+// Chat-inventory DTO. Backs `GET /v1/nodes/{id}/chat-inventory` — the one read
+// a non-terminal chat surface makes to learn what the node's live engine will
+// accept: the slash commands that can complete their outcome from a chat
+// conversation, and the memory documents an inline `/name` token resolves to.
+//
+// Eligibility is decided in crouter and disclosed here. A client never filters
+// by name, infers capability, or invents a row: what is absent from these
+// arrays is not offered.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/api/dto/common.d.ts

@@ -0,0 +1,29 @@
+/** 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' | 'parked' | null;
+/** Why a terminal node ended (mirrors the runtime `TerminalReason` union). */
+export type TerminalReasonDTO = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined';
+/** 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/api/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/api/dto/config.d.ts

@@ -0,0 +1,36 @@
+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;
+    /** 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;
+    /** Repair-only replacement launch directory; exclusive of every other field. */
+    cwd?: string;
+    /** Per-run allow-list. A patch may only remove scopes; it applies to a live broker on its next revive. */
+    scopes?: string[];
+    /** The node's default listening configuration: event level ("1".."10") → delivery
+     *  (`interrupt`|`steer`|`after-turn`|`next-turn`) for watches with no config of their own.
+     *  `null` resets it to the global default. */
+    listen?: Record<string, 'interrupt' | 'steer' | 'after-turn' | 'next-turn'> | null;
+}
+/** One installed persona kind, as the daemon resolves kinds for node creation. */
+export interface KindDTO {
+    kind: string;
+    when_to_use: string | null;
+    /** Top-level kinds a sub-kind is offered to; null takes the default (its own ancestor). */
+    available_to: string[] | null;
+}
+/** `GET /v1/kinds` — every kind the daemon accepts on create, sorted by name. */
+export interface KindListDTO {
+    kinds: KindDTO[];
+}

package/dist/api/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/api/dto/crons.d.ts

@@ -0,0 +1,150 @@
+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;
+    /** The shell and any spawned node stay isolated when armed from an isolated node. */
+    isolated: boolean;
+    /** 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;
+    /** True while the row is parked by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A daemon poke re-dues it now; otherwise a
+     *  recurring row re-checks at its natural `fire_at` slot (the backstop) and
+     *  a held one-shot waits for a poke until `expires_at` deletes it. `state`
+     *  stays honest (active|paused) — renderers derive; an active held row must
+     *  never present as paused. */
+    held: boolean;
+    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;
+}
+/** Cancellation-only query. `run_id` is set automatically inside a cron run,
+ * letting crtrd distinguish a run ending itself from an external cancellation
+ * that must terminate an in-flight process. */
+export interface CancelCronQuery extends CronScopeQuery {
+    run_id?: string;
+}
+/** 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;
+}
+/** `POST /v1/crons/poke` — the bare daemon-level eligibility poke. Re-dues
+ *  every held active cron now; paused rows keep their held state. Idempotent
+ *  and free when nothing is held. */
+export interface PokeCronsResult {
+    /** How many held rows were re-dued — for the caller's log line. */
+    unparked: number;
+    /** The poke receipt instant (UTC). */
+    at: IsoTime;
+}
+/** `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;
+    isolated?: boolean;
+    /** 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;
+}