@north-light/api 0.3.532 → 0.3.534

package/dist/api/client.d.ts

@@ -28,7 +28,7 @@ import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInve
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, CompleteModelAuthFlowRequest, ModelAuthFlowCompletedDTO, ModelAuthFlowDTO, ModelAuthFlowStartedDTO, ModelAuthListDTO, ModelAuthReadinessDTO, ModelAuthReadinessQuery, StartModelAuthFlowRequest } from './dto/modelauth.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
 import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentForkDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
-import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
+import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, PageTicketSummaryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
 import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest, PageComponentListDTO } from './dto/human-requests.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryStatsQuery, HistoryStatsResultDTO, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, GraphDTO, PruneRequest, PruneResultDTO, LiveRootsDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { AbandonWorktreeRequest, AbandonWorktreeResultDTO, CloseWorktreeResultDTO, QuarantinedWorktreeDTO, SpaceListDTO } from './dto/worktree.js';
@@ -377,8 +377,11 @@ export declare class CrtrClient {
     /** Read one page ticket by its opaque ticket id (pending, resolved, or canceled). */
     getHumanInboxPage(ticketId: InboxTicketIdDTO): Promise<InboxPageDTO>;
     /** All page tickets, oldest first (pending, resolved, or canceled) —
-     *  home-wide, or narrowed to one raising node when `nodeId` is given. */
-    getInboxHistory(nodeId?: string): Promise<InboxPageHistoryDTO>;
+     *  home-wide, or narrowed to one raising node when `nodeId` is given, and to
+     *  one ticket state when `opts.state` is given. */
+    getInboxHistory(nodeId?: string, opts?: {
+        state?: PageTicketSummaryDTO['state'];
+    }): Promise<InboxPageHistoryDTO>;
     /** Submit responses for a page ticket. Single-assignment server-side: a competing
      *  resolution races to `ticket_already_resolved`. */
     respondHumanInboxPage(ticketId: InboxTicketIdDTO, request: RespondInboxPageRequest): Promise<PageTicketResultDTO>;

package/dist/api/client.js

@@ -707,15 +707,13 @@ export class CrtrClient {
         return this.request('GET', routes.humanInboxTicket(this.ticketId(ticketId)));
     }
     /** All page tickets, oldest first (pending, resolved, or canceled) —
-     *  home-wide, or narrowed to one raising node when `nodeId` is given. */
-    getInboxHistory(nodeId) {
-        if (nodeId === undefined) {
-            return this.request('GET', routes.humanInbox() + '/history');
-        }
-        if (typeof nodeId !== 'string' || nodeId === '') {
+     *  home-wide, or narrowed to one raising node when `nodeId` is given, and to
+     *  one ticket state when `opts.state` is given. */
+    getInboxHistory(nodeId, opts = {}) {
+        if (nodeId !== undefined && (typeof nodeId !== 'string' || nodeId === '')) {
             throw new TypeError(`invalid node id: ${JSON.stringify(nodeId)}`);
         }
-        return this.request('GET', withQuery(routes.humanInbox() + '/history', { node_id: nodeId }));
+        return this.request('GET', withQuery(routes.humanInbox() + '/history', { node_id: nodeId, state: opts.state }));
     }
     /** Submit responses for a page ticket. Single-assignment server-side: a competing
      *  resolution races to `ticket_already_resolved`. */

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.25";
+export declare const CONTRACT_LEVEL = "1.26";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.25';
+export const CONTRACT_LEVEL = '1.26';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

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

@@ -257,6 +257,8 @@ export interface RosterNodeDTO {
     enterable: boolean;
     parent: NodeIdDTO | null;
     created: IsoTime;
+    /** The node's one-line description, the label for an unnamed node. Absent from daemons older than this field. */
+    description?: string | null;
 }
 /** 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. */

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

@@ -29,7 +29,7 @@ export interface CronDTO {
     command: string;
     /** The grant the cron runs under (checked at every fire, call and birth); null only for the terminal on a runtime with no issuer. */
     grant_id: string | null;
-    /** The scopes the cron is bounded to; null = the grant's whole current set (a person-armed terminal cron). */
+    /** The scopes the cron is bounded to; null = the grant's whole current set at each fire (a person-armed terminal cron, or one armed by a caller with no scope limit). */
     scopes: string[] | null;
     /** The run of the node that armed it, when a node did. */
     origin_run_id: string | null;
@@ -83,6 +83,8 @@ export interface CronDTO {
  *  boundary between profiles, not a security boundary. */
 export interface ListCronsQuery {
     profile?: string;
+    /** Only the crons this node armed (`CronDTO.created_by`). */
+    created_by?: 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,

package/dist/daemon/broker-signals/bus.d.ts

@@ -1,12 +1,11 @@
-import type { DatabaseSync } from 'node:sqlite';
 import type { BrokerExtensionNodeDTO } from '../../api/dto/broker-ops.js';
 /** Node-owned mutable fields in extensionNode's projection. Keep this list and
  * the typed cache view together; object/worktree-owned fields are never cached. */
 export declare const BROKER_SIGNAL_NODE_COLUMNS: readonly ["description", "title", "icon", "mode", "lifecycle", "status", "cwd", "parent", "fork_from", "profile_id", "review_binding_json", "persona_ack_json", "intent"];
 type ProjectedNodeKey<C extends string> = C extends 'review_binding_json' ? 'review_binding' : C extends 'persona_ack_json' ? 'persona_ack' : C;
 export type BrokerSignalCachedNode = Pick<BrokerExtensionNodeDTO, Extract<ProjectedNodeKey<(typeof BROKER_SIGNAL_NODE_COLUMNS)[number]>, keyof BrokerExtensionNodeDTO>>;
-/** Only node-owned columns are suitable for P4's cache. The source list also
- * drives the SQLite trigger, so a newly added node field has one edit point. */
+/** Only node-owned columns are suitable for P4's cache. The same columns
+ * appear in `crtr_sig_node_upd` in schema-pg.sql; keep the two lists together. */
 export declare function cachedBrokerNodeFields(node: BrokerExtensionNodeDTO): BrokerSignalCachedNode;
 export type BrokerSignalKind = 'mail' | 'node';
 export type BrokerSignalSubscriber = (nodeId: string, kind: BrokerSignalKind) => void;
@@ -21,9 +20,18 @@ export declare class BrokerSignalBus {
     markNode(nodeId: string): void;
     private mark;
     private flush;
-    /** Reinstalled for every new daemon canvas handle (TEMP triggers vanish on close). */
-    install(db: DatabaseSync): void;
-    close(): void;
+    /** Start listening on `crtr_signal` over a second, listen-only connection to `url` (the schema's `pg_notify`
+     * triggers publish `mail:<node id>` and `node:<node id>` at commit). Resolves once LISTEN is active, so a write
+     * committed after it returns is heard. A lost connection reconnects with backoff; signals sent while it was down
+     * are lost, which is safe because they are hints and every consumer re-reads durable state. */
+    listen(url: string): Promise<void>;
+    private listener;
+    private listening;
+    private url;
+    private reconnect;
+    private connectListener;
+    /** Stop listening and drop pending marks. The returned promise resolves once the connection has closed. */
+    close(): Promise<void>;
 }
 /** One daemon-process bus; the API fixture binds this same instance. */
 export declare const brokerSignalBus: BrokerSignalBus;

package/dist/daemon/broker-signals/bus.js

@@ -1,3 +1,4 @@
+import pg from 'pg';
 /** Node-owned mutable fields in extensionNode's projection. Keep this list and
  * the typed cache view together; object/worktree-owned fields are never cached. */
 export const BROKER_SIGNAL_NODE_COLUMNS = [
@@ -6,8 +7,8 @@ export const BROKER_SIGNAL_NODE_COLUMNS = [
     'persona_ack_json', 'intent',
 ];
 const nodeField = (column) => column === 'review_binding_json' ? 'review_binding' : column === 'persona_ack_json' ? 'persona_ack' : column;
-/** Only node-owned columns are suitable for P4's cache. The source list also
- * drives the SQLite trigger, so a newly added node field has one edit point. */
+/** Only node-owned columns are suitable for P4's cache. The same columns
+ * appear in `crtr_sig_node_upd` in schema-pg.sql; keep the two lists together. */
 export function cachedBrokerNodeFields(node) {
     const picked = {};
     for (const column of BROKER_SIGNAL_NODE_COLUMNS) {
@@ -48,39 +49,81 @@ export class BrokerSignalBus {
             }
         }
     }
-    /** Reinstalled for every new daemon canvas handle (TEMP triggers vanish on close). */
-    install(db) {
-        db.function('crtr_signal', { deterministic: false }, (kind, id) => {
-            // SQLite invokes this synchronously inside the writer's statement. A hint
-            // must never cause a transaction to fail, even for an unexpected row.
-            try {
-                if (typeof id === 'string') {
-                    if (kind === 'mail')
-                        this.markMail(id);
-                    if (kind === 'node')
-                        this.markNode(id);
-                }
-            }
-            catch { /* best-effort hint only */ }
-            return null;
+    /** Start listening on `crtr_signal` over a second, listen-only connection to `url` (the schema's `pg_notify`
+     * triggers publish `mail:<node id>` and `node:<node id>` at commit). Resolves once LISTEN is active, so a write
+     * committed after it returns is heard. A lost connection reconnects with backoff; signals sent while it was down
+     * are lost, which is safe because they are hints and every consumer re-reads durable state. */
+    async listen(url) {
+        if (this.listener !== undefined || this.listening !== undefined)
+            return;
+        this.url = url;
+        this.listening = this.connectListener().finally(() => { this.listening = undefined; });
+        await this.listening;
+    }
+    listener;
+    listening;
+    url;
+    reconnect;
+    async connectListener() {
+        const client = new pg.Client({ connectionString: this.url, application_name: `crtr-signal-${process.pid}` });
+        client.on('notification', message => {
+            // A hint must never cause an exception for an unexpected payload.
+            const payload = message.payload ?? '';
+            const colon = payload.indexOf(':');
+            if (colon < 0)
+                return;
+            const kind = payload.slice(0, colon);
+            const id = payload.slice(colon + 1);
+            if (kind === 'mail')
+                this.markMail(id);
+            else if (kind === 'node')
+                this.markNode(id);
         });
-        db.exec(`
-      CREATE TEMP TRIGGER crtr_sig_deliv_ins AFTER INSERT ON main.deliveries
-        WHEN NEW.wake = 1 BEGIN SELECT crtr_signal('mail', NEW.destination_id); END;
-      CREATE TEMP TRIGGER crtr_sig_deliv_upd AFTER UPDATE OF state, canceled_at, claim_owner ON main.deliveries
-        WHEN NEW.wake = 1 BEGIN SELECT crtr_signal('mail', NEW.destination_id); END;
-      CREATE TEMP TRIGGER crtr_sig_deliv_del AFTER DELETE ON main.deliveries
-        WHEN OLD.wake = 1 BEGIN SELECT crtr_signal('mail', OLD.destination_id); END;
-      CREATE TEMP TRIGGER crtr_sig_node_upd AFTER UPDATE OF ${BROKER_SIGNAL_NODE_COLUMNS.join(', ')} ON main.nodes
-        BEGIN SELECT crtr_signal('node', NEW.node_id); END;
-    `);
+        const lost = () => {
+            if (this.listener !== client)
+                return;
+            this.listener = undefined;
+            client.removeAllListeners();
+            client.on('error', () => { });
+            client.end().catch(() => { });
+            if (this.url === undefined)
+                return;
+            this.reconnect = setTimeout(() => {
+                this.reconnect = undefined;
+                this.connectListener().catch(() => lostRetry());
+            }, 1000);
+        };
+        const lostRetry = () => {
+            if (this.url === undefined || this.reconnect !== undefined)
+                return;
+            this.reconnect = setTimeout(() => {
+                this.reconnect = undefined;
+                this.connectListener().catch(() => lostRetry());
+            }, 1000);
+        };
+        client.on('error', lost);
+        client.on('end', lost);
+        await client.connect();
+        await client.query('LISTEN crtr_signal');
+        this.listener = client;
     }
+    /** Stop listening and drop pending marks. The returned promise resolves once the connection has closed. */
     close() {
+        this.url = undefined;
+        if (this.reconnect !== undefined)
+            clearTimeout(this.reconnect);
+        this.reconnect = undefined;
+        const listener = this.listener;
+        this.listener = undefined;
         if (this.scheduled !== undefined)
             clearImmediate(this.scheduled);
         this.scheduled = undefined;
         this.dirty.clear();
         this.subscribers.clear();
+        if (listener === undefined)
+            return Promise.resolve();
+        listener.removeAllListeners('notification');
+        return listener.end().catch(() => undefined);
     }
 }
 /** One daemon-process bus; the API fixture binds this same instance. */

package/dist/daemon/manage.d.ts

@@ -40,6 +40,16 @@ export declare function sweepStrayDaemons(keepPid: number | null): number[];
 /** Replace PID 1 with the selected daemon generation. Docker keeps a container
  *  alive only while PID 1 lives, so a handover there must preserve its pid. */
 export declare function execDaemon(): Promise<never>;
+export interface DaemonExportSqliteResult {
+    path: string;
+    rows: number;
+    ms: number;
+    userVersion: number;
+}
+/** Run the selected generation's `crtrd-cli export-sqlite` and wait for it. The export loads canvas database code, which
+ *  a CLI process may not, so it runs in the daemon entry the way the daemon itself is launched. Throws with the child's
+ *  stderr when it fails. */
+export declare function runDaemonExportSqlite(): Promise<DaemonExportSqliteResult>;
 export interface SpawnDaemonOptions {
     /** The phase that proves a daemon launched by this call is available. */
     targetPhase?: 'ready' | 'prepared';

package/dist/daemon/manage.js

@@ -195,6 +195,25 @@ export async function execDaemon() {
     const launchArgs = await resolveDaemonLaunch();
     return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
 }
+/** Run the selected generation's `crtrd-cli export-sqlite` and wait for it. The export loads canvas database code, which
+ *  a CLI process may not, so it runs in the daemon entry the way the daemon itself is launched. Throws with the child's
+ *  stderr when it fails. */
+export async function runDaemonExportSqlite() {
+    const launchArgs = await resolveDaemonLaunch();
+    const child = spawn(hostExecPath(), [...launchArgs, 'export-sqlite'], { stdio: ['ignore', 'pipe', 'pipe'], env: sanitizedDaemonEnv() });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8').on('data', (chunk) => { stdout += chunk; });
+    child.stderr.setEncoding('utf8').on('data', (chunk) => { stderr += chunk; });
+    const code = await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (exitCode) => resolve(exitCode));
+    });
+    if (code !== 0)
+        throw new Error(stderr.trim() || `the export process exited with code ${code}`);
+    const line = stdout.trim().split('\n').at(-1) ?? '';
+    return JSON.parse(line);
+}
 /** How long a handover successor waits for a running join: a registration call (30 s) plus the join's own stop and start. */
 const JOIN_WAIT_WINDOW_MS = 3 * 60_000;
 // Shutdown stays short even though startup may include corpus migration.
@@ -220,12 +239,14 @@ export function probeErrorMessage(error) {
 /** True only when one mandatory Unix API socket probe answers the existing ready health contract. */
 export async function probeDaemonServing(timeoutMs = DAEMON_HEALTH_PROBE_TIMEOUT_MS) {
     const health = await probeDaemonHealth(timeoutMs);
-    if (health.startup_blocked !== undefined) {
+    // Only `blocked` needs a person; `initializing` and `recovering` (a first-boot SQLite import, broker recovery) finish
+    // on their own, so a caller waiting out a startup window keeps waiting through them.
+    if (health.startup_phase === 'blocked') {
         const pid = readPidfile() ?? process.pid;
-        throw new DaemonStartupBlockedError(pid, health.startup_blocked);
+        throw new DaemonStartupBlockedError(pid, health.startup_blocked ?? 'daemon startup is blocked');
     }
     if (!health.ok)
-        throw new Error('crtrd health check reported not ready');
+        throw new Error(health.startup_blocked ?? 'crtrd health check reported not ready');
 }
 /** True only when one mandatory Unix API socket probe answers `/healthz`.
  * A pidfile identifies an owner; it is never readiness. */

package/dist/shared/env.d.ts

@@ -110,6 +110,9 @@ export declare function envMaxLiveBrokers(): number | undefined;
 /** Live-broker warning threshold override (`CRTR_WARN_LIVE_BROKERS`); wins
  *  over `readConfig('user').brokerThresholds.warning` when set. */
 export declare function envWarnLiveBrokers(): number | undefined;
+/** Test-only override (`CRTR_TEST_NODE_SOCKET_WINDOW_MS`) of how long a command inside a node waits for the broker's
+ *  relay socket to come back; gated by `envNoDaemonAutostart()` at the call site, so a real node always waits out a restart. */
+export declare function envTestNodeSocketWindowMs(): number | undefined;
 /** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
  *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
 export declare function envTestUnattendedParkMs(): number | undefined;

package/dist/shared/env.js

@@ -283,6 +283,11 @@ function parsePositiveMsNoDefault(raw) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : undefined;
 }
+/** Test-only override (`CRTR_TEST_NODE_SOCKET_WINDOW_MS`) of how long a command inside a node waits for the broker's
+ *  relay socket to come back; gated by `envNoDaemonAutostart()` at the call site, so a real node always waits out a restart. */
+export function envTestNodeSocketWindowMs() {
+    return parsePositiveMsNoDefault(process.env['CRTR_TEST_NODE_SOCKET_WINDOW_MS']);
+}
 /** Test-only unattended-park interval override (`CRTR_TEST_UNATTENDED_PARK_MS`),
  *  gated by `envNoDaemonAutostart()` at the call site; no production default. */
 export function envTestUnattendedParkMs() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.532",
+  "version": "0.3.534",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",