@north-light/crouter 0.3.154

package/dist/daemon/api/map.js

@@ -0,0 +1,360 @@
+// Internal type → DTO projection (spec §3.1, §8). This is the ONLY module that
+// imports BOTH `core/*` internal types and the `src/api` DTO shapes — the
+// boundary where crtrd's authoritative runtime types are projected into the
+// dependency-light wire contract. `src/api/*` stays pure (Node built-ins only);
+// all projection lives here, server-side.
+//
+// Every function here is a pure projection (no I/O, no db reach) except the
+// path builders, which call `core/canvas/paths.ts` — themselves pure string
+// constructors. The DTO field sets these project into were pinned by A-1 as
+// reasonable projections; this module is what makes them concrete, so any DTO
+// field that projection proves wrong is corrected here at the source.
+import { contextDir, inboxPath, nodeDir, nodeMetaPath, reportsDir, transcriptPath, viewSocketPath, } from '../../core/canvas/paths.js';
+import { FinalizationError } from '../../core/feed/feed.js';
+import { NodeIdConflictError } from '../../core/runtime/nodes.js';
+import { readContextTokens } from '../../core/canvas/telemetry.js';
+import { CrtrError } from '../../core/errors.js';
+import { ExitCode } from '../../types.js';
+import { sinkDisplay } from '../cron-sink.js';
+// ---------------------------------------------------------------------------
+// Node projections
+// ---------------------------------------------------------------------------
+/** Project the queryable row (what `listNodes` yields) into a summary DTO. */
+export function toNodeSummaryDTO(row) {
+    return {
+        node_id: row.node_id,
+        name: row.name,
+        kind: row.kind,
+        mode: row.mode,
+        lifecycle: row.lifecycle,
+        status: row.status,
+        cwd: row.cwd,
+        host_kind: row.host_kind,
+        profile_id: row.profile_id,
+        parent: row.parent,
+        created: row.created,
+        intent: row.intent,
+        waiting_for: row.waiting_for,
+        pi_pid: row.pi_pid,
+        final_report: row.final_report ?? null,
+        finalized_at: row.finalized_at ?? null,
+    };
+}
+/** Project a node's spine + subscription edges (absorbs `managers`/`paths`). */
+export function toNodeEdgesDTO(meta, edges) {
+    return {
+        parent: meta.parent ?? null,
+        spawned_by: meta.spawned_by ?? null,
+        subscribes_to: edges.subscribesTo.map((r) => r.node_id),
+        subscribers: edges.subscribers.map((r) => r.node_id),
+        children: [...edges.children],
+    };
+}
+/** Absolute filesystem paths for a node (absorbs the `paths` read). Pure — the
+ *  `core/canvas/paths.ts` helpers are string constructors, not db reach. */
+export function toNodePathsDTO(nodeId) {
+    return {
+        node_dir: nodeDir(nodeId),
+        context_dir: contextDir(nodeId),
+        reports_dir: reportsDir(nodeId),
+        meta_path: nodeMetaPath(nodeId),
+        inbox_path: inboxPath(nodeId),
+        transcript_path: transcriptPath(nodeId),
+        view_socket: viewSocketPath(nodeId),
+    };
+}
+/** Project a node's managed git worktree, if any. */
+export function toNodeWorktreeDTO(w) {
+    const dto = {
+        state: w.state,
+        path: w.path,
+        branch: w.branch,
+        repo_root: w.repo_root,
+        base_ref: w.base_ref,
+        base_sha: w.base_sha,
+        created: w.created,
+    };
+    if (w.closed !== undefined)
+        dto.closed = w.closed;
+    return dto;
+}
+/** Project the hydrated node view (`getNode` → `NodeMeta`) into a detail DTO.
+ *  The summary fields come from the meta's runtime half (hydrated from the
+ *  authoritative row); the identity extras (description/cycles/session) come
+ *  from the meta's identity half. Edges are gathered by the handler. */
+export function toNodeDetailDTO(meta, edges) {
+    const dto = {
+        node_id: meta.node_id,
+        name: meta.name,
+        kind: meta.kind,
+        mode: meta.mode,
+        lifecycle: meta.lifecycle,
+        status: meta.status,
+        cwd: meta.cwd,
+        host_kind: meta.host_kind ?? null,
+        profile_id: meta.profile_id ?? null,
+        parent: meta.parent ?? null,
+        created: meta.created,
+        intent: (meta.intent ?? null),
+        waiting_for: meta.waiting_for ?? null,
+        pi_pid: meta.pi_pid ?? null,
+        final_report: meta.final_report ?? null,
+        finalized_at: meta.finalized_at ?? null,
+        edges: toNodeEdgesDTO(meta, edges),
+        paths: toNodePathsDTO(meta.node_id),
+    };
+    if (meta.description !== undefined)
+        dto.description = meta.description;
+    if (meta.cycles !== undefined)
+        dto.cycles = meta.cycles;
+    dto.context_tokens = readContextTokens(meta.node_id);
+    dto.pi_pid_identity = meta.pi_pid_identity ?? null;
+    if (meta.pi_session_id !== undefined)
+        dto.pi_session_id = meta.pi_session_id ?? null;
+    dto.model_override = meta.model_override ?? null;
+    if (meta.pi_session_file !== undefined)
+        dto.pi_session_file = meta.pi_session_file ?? null;
+    if (meta.managed_worktree != null)
+        dto.worktree = toNodeWorktreeDTO(meta.managed_worktree);
+    return dto;
+}
+// ---------------------------------------------------------------------------
+// Action-result projections
+// ---------------------------------------------------------------------------
+/** Project a `reviveNode` result. `revived` is true only when a fresh launch
+ *  actually happened — the double-revive no-op (already-alive) returns without a
+ *  `launch` handle, so its absence is the "nothing relaunched" signal. `status`
+ *  is the caller's post-revive row read. */
+export function toReviveResultDTO(nodeId, result, status) {
+    return {
+        node_id: nodeId,
+        revived: result.launch !== undefined,
+        resumed: result.resumed,
+        status,
+    };
+}
+/** Project a `closeNode` cascade result. Field names align 1:1. */
+export function toCloseResultDTO(result) {
+    return {
+        root: result.root,
+        closed: [...result.closed],
+        spared: [...result.spared],
+    };
+}
+/** Project a feed `push` result into a push-report result. `transitioned` is
+ *  supplied by the handler only for a `final` push (the server-side lifecycle
+ *  flip); an update/urgent push omits it. */
+export function toReportResultDTO(result, transitioned, autoDroppedWorktreePath) {
+    const dto = {
+        report_path: result.reportPath,
+        notified: [...result.deliveredTo],
+    };
+    if (transitioned !== undefined)
+        dto.transitioned = transitioned;
+    if (autoDroppedWorktreePath !== undefined) {
+        dto.worktree_auto_dropped = true;
+        dto.worktree_auto_dropped_path = autoDroppedWorktreePath;
+    }
+    return dto;
+}
+/** Project a subscription ref as seen from one endpoint. */
+export function toSubscriptionDTO(ref) {
+    return {
+        node_id: ref.node_id,
+        active: ref.active,
+        created: ref.created,
+    };
+}
+/** The NAMES of a cron's snapshotted extra env vars. Keys only — the values
+ *  stay server-side because a chosen env can carry a credential. A malformed
+ *  stored value reads as no extra env rather than crashing a list. */
+function envKeys(envJson) {
+    if (envJson === null || envJson === '')
+        return [];
+    try {
+        const parsed = JSON.parse(envJson);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? Object.keys(parsed) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Project a cron row into its DTO — a straight column projection minus the
+ *  internal lease plumbing (run_pid/run_lease_owner/env_json/last_output_hash/
+ *  queued stay server-side); the sink JSON is rendered back to its display
+ *  spec. `lastRun` is the most recent settled run — the recent health every
+ *  cron projection carries so `cron list` needs no `cron show` per row. */
+export function toCronDTO(c, lastRun) {
+    return {
+        cron_id: c.cron_id,
+        name: c.name,
+        created_by: c.created_by,
+        command: c.command,
+        fire_at: c.fire_at,
+        recur: c.recur,
+        tz: c.tz,
+        expires_at: c.expires_at,
+        anchor_node: c.anchor_node,
+        cancel_on_wake: c.cancel_on_wake,
+        cwd: c.cwd,
+        profile: c.profile,
+        scope: c.scope,
+        env_keys: envKeys(c.env_json),
+        run_timeout_s: c.run_timeout_s,
+        overlap: c.overlap,
+        on_output: c.on_output,
+        sink: sinkDisplay(c.sink),
+        tier: c.tier,
+        state: c.state,
+        run_state: c.run_state,
+        last_run: lastRun === undefined || lastRun === null
+            ? null
+            : { finished: lastRun.finished, exit_code: lastRun.exit_code, delivered: lastRun.delivered },
+        created: c.created,
+        updated: c.updated,
+    };
+}
+/** Project one settled run-log record into its DTO — a straight projection
+ *  minus the redundant cron_id (the route already names the cron). */
+export function toCronRunDTO(r) {
+    return {
+        run_id: r.run_id,
+        started: r.started,
+        finished: r.finished,
+        duration_ms: r.duration_ms,
+        exit_code: r.exit_code,
+        stdout_head: r.stdout_head,
+        stderr_head: r.stderr_head,
+        delivered: r.delivered,
+    };
+}
+/** Project a profile-manifest entry into its DTO. `default_dir` (the directory
+ *  this profile is pinned as default for) is a reverse lookup not carried on the
+ *  entry, so it is left null here — a caller that needs it resolves it
+ *  separately. */
+export function toProfileDTO(entry) {
+    return {
+        id: entry.profileId,
+        name: entry.manifest.name,
+        projects: [...entry.manifest.projects],
+        default_dir: null,
+    };
+}
+/** Project a `consult_outbox` (human-work) row into a consult-outbox entry DTO
+ *  (the canvas half of a human consult/visual request). `work_kind` is the same
+ *  `'follow_up' | 'visual'` union as `ConsultKindDTO`; `created` carries the
+ *  row's last-touch timestamp (the table has no separate creation column). */
+export function toConsultOutboxEntryDTO(row) {
+    return {
+        request_id: row.request_id,
+        node_id: row.node_id,
+        kind: row.work_kind,
+        dir: row.dir,
+        created: row.updated_at,
+    };
+}
+const _exitIntentParity = true;
+void _exitIntentParity;
+// ---------------------------------------------------------------------------
+// Error → HTTP status mapping (spec §8)
+// ---------------------------------------------------------------------------
+/** The single error-mapping function (spec §8). Projects any thrown value into
+ *  `{ status, code }`:
+ *   - a CrtrError → status by its `exitCode` class, `code` its machine code;
+ *   - a feed `FinalizationError` → 409 `already_finalized` /
+ *     `finalization_forbidden`, or 404 `node_not_found`;
+ *   - a `NodeIdConflictError` (a `--node-id`/`node_id` spawn at an id that
+ *     already exists) → 409 `node_id_exists`;
+ *   - `reviveNode`'s finalization-latch throw → 409 `already_finalized`;
+ *   - an "unknown node" throw (reviveNode / transition / getNode-null handler) →
+ *     404 `node_not_found`;
+ *   - a `transition` illegal-move throw → 409 `illegal_transition`;
+ *   - anything already carrying a numeric `status` + string `code` (an
+ *     `ApiError`-shaped throw) → used verbatim;
+ *   - anything else → 500 `internal`.
+ *  The recognized plain-`Error` cases match on the throw sites' messages (the
+ *  only signal those sites carry); the source sites are named above so a message
+ *  change there is caught by the A-11 tests. */
+export function errorToStatus(err) {
+    // An already-shaped API-style throw (e.g. a re-thrown ApiError) — trust it.
+    if (typeof err === 'object' &&
+        err !== null &&
+        typeof err.status === 'number' &&
+        typeof err.code === 'string') {
+        return {
+            status: err.status,
+            code: err.code,
+        };
+    }
+    if (err instanceof FinalizationError) {
+        if (err.code === 'unknown_node')
+            return { status: 404, code: 'node_not_found' };
+        if (err.code === 'already_finalized')
+            return { status: 409, code: 'already_finalized' };
+        return { status: 409, code: 'finalization_forbidden' };
+    }
+    if (err instanceof NodeIdConflictError) {
+        return { status: 409, code: 'node_id_exists' };
+    }
+    if (err instanceof CrtrError) {
+        return { status: statusForExitCode(err.exitCode), code: err.code };
+    }
+    if (err instanceof Error) {
+        const m = err.message;
+        if (/unknown node/i.test(m))
+            return { status: 404, code: 'node_not_found' };
+        if (/finalization latch/i.test(m))
+            return { status: 409, code: 'already_finalized' };
+        if (/illegal lifecycle transition/i.test(m)) {
+            return { status: 409, code: 'illegal_transition' };
+        }
+    }
+    return { status: 500, code: 'internal' };
+}
+function statusForExitCode(exitCode) {
+    switch (exitCode) {
+        case ExitCode.NOT_FOUND:
+            return 404;
+        case ExitCode.USAGE:
+            return 400;
+        case ExitCode.AMBIGUOUS:
+            return 400;
+        case ExitCode.NETWORK:
+            return 503;
+        case ExitCode.GENERAL:
+            return 400;
+        default:
+            return 500;
+    }
+}
+/** The single-line, length-bounded cause a 500 body may safely carry. A curated
+ *  `Error.message` is a diagnostic, not a raw stack trace: surfacing its first
+ *  line (capped) turns an opaque `internal error` into an actionable one while
+ *  still refusing to leak multi-line traces. The router logs the FULL error
+ *  (with stack) server-side alongside this. */
+function boundedCause(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const firstLine = raw.split('\n', 1)[0].trim();
+    if (firstLine === '')
+        return 'internal error';
+    return firstLine.length > 500 ? `${firstLine.slice(0, 497)}…` : firstLine;
+}
+/** Build the uniform JSON error body (spec §8) for a thrown value, using
+ *  `errorToStatus` for the status/code. Structured `details` are surfaced for a
+ *  CrtrError (they let the client reconstruct the error verbatim). A 500 still
+ *  omits `details` for hygiene, but NO LONGER strips the message to a bare
+ *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
+ *  is never left with a causeless internal, while the router logs the full
+ *  error (with stack) server-side. */
+export function toErrorBody(err) {
+    const { status, code } = errorToStatus(err);
+    if (status >= 500) {
+        return { status, body: { error: { code, message: boundedCause(err) } } };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const details = err instanceof CrtrError && err.details !== undefined ? err.details : undefined;
+    const body = { error: { code, message } };
+    if (details !== undefined)
+        body.error.details = details;
+    return { status, body };
+}

package/dist/daemon/api/router.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** The request view a handler receives: the resolved route params, parsed
+ *  query, parsed JSON body, and the raw req/res for the rare handler that needs
+ *  them (streaming, headers). Everything a handler mutates it does through the
+ *  returned `HandlerResult`, not by writing `res` directly — keeping the
+ *  error-wrap total. */
+export interface RequestContext {
+    method: string;
+    /** The request pathname (no query string). */
+    path: string;
+    /** Captured `:name` path params. */
+    params: Record<string, string>;
+    /** Parsed query string. */
+    query: URLSearchParams;
+    /** Parsed JSON request body, or `undefined` when there was no body. */
+    body: unknown;
+    req: IncomingMessage;
+    res: ServerResponse;
+}
+/** What a handler returns. `body` is JSON-serialized; omit it (or use 204) for
+ *  an empty response. `headers` are merged over the default `content-type`. */
+export interface HandlerResult {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** A route handler — sync or async. A throw is caught and mapped by the router
+ *  (map.ts §8); a handler never writes an error response itself. */
+export type RouteHandler = (ctx: RequestContext) => HandlerResult | Promise<HandlerResult>;
+/** One entry in the route table. `pattern` is a `:name`-style path template. */
+export interface RouteDef {
+    method: string;
+    pattern: string;
+    handler: RouteHandler;
+}
+/** The flat route table the handler authors (A-7) build up and hand to the
+ *  server (A-9). */
+export type RouteTable = RouteDef[];
+export declare class Router {
+    private readonly routes;
+    /** Register one route. Returns `this` for chaining. */
+    register(def: RouteDef): this;
+    /** Register a whole table at once. */
+    registerAll(table: RouteTable): this;
+    /** Match a method + pathname against the table, extracting `:name` params.
+     *  Returns null when nothing matches (the caller responds 404). */
+    match(method: string, path: string): {
+        handler: RouteHandler;
+        params: Record<string, string>;
+    } | null;
+    /** Resolve the JSON body, dispatch to the matched handler, and write the
+     *  response. Every failure path — no route, bad JSON, a handler throw — is
+     *  turned into a JSON `ErrorBody` (map.ts §8); this method never throws and
+     *  never leaves the daemon crashed. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}

package/dist/daemon/api/router.js

@@ -0,0 +1,190 @@
+// The crtrd API router (spec §4.2). A tiny hand-rolled method+path matcher — no
+// framework, matching the CLI's no-dependency ethos (`core/command.ts` is a
+// hand-rolled path walker for the same reason).
+//
+// Routes are a flat table of `{ method, pattern, handler }`. A `pattern` like
+// `/v1/nodes/:id/messages` is matched by splitting both it and the request path
+// on '/'; a `:name` segment captures into `params`. `handle(req, res)` resolves
+// the JSON body, dispatches to the matched handler, and wraps EVERY handler so a
+// thrown error becomes a JSON `ErrorBody` with the mapped status (map.ts §8) —
+// a handler throw NEVER crashes the daemon (the belt-and-suspenders 500 mirrors
+// `clients/web/server.ts`'s request-listener boundary).
+//
+// The WS attach upgrade (`GET /nodes/:id/attach` with `Upgrade: websocket`) is
+// NOT routed here — the server (A-9) owns the upgrade handshake and hands it to
+// `bridge.ts` (A-8). This router serves only non-upgrade HTTP requests.
+import { toErrorBody } from './map.js';
+import { emitEvent } from '../../core/events/emit.js';
+const MAX_BODY_BYTES = 4 * 1024 * 1024; // 4 MiB — generous for JSON control bodies.
+export class Router {
+    routes = [];
+    /** Register one route. Returns `this` for chaining. */
+    register(def) {
+        this.routes.push({
+            method: def.method.toUpperCase(),
+            segments: splitPath(def.pattern),
+            handler: def.handler,
+        });
+        return this;
+    }
+    /** Register a whole table at once. */
+    registerAll(table) {
+        for (const def of table)
+            this.register(def);
+        return this;
+    }
+    /** Match a method + pathname against the table, extracting `:name` params.
+     *  Returns null when nothing matches (the caller responds 404). */
+    match(method, path) {
+        const wanted = method.toUpperCase();
+        const parts = splitPath(path);
+        for (const route of this.routes) {
+            if (route.method !== wanted)
+                continue;
+            const params = matchSegments(route.segments, parts);
+            if (params !== null)
+                return { handler: route.handler, params };
+        }
+        return null;
+    }
+    /** Resolve the JSON body, dispatch to the matched handler, and write the
+     *  response. Every failure path — no route, bad JSON, a handler throw — is
+     *  turned into a JSON `ErrorBody` (map.ts §8); this method never throws and
+     *  never leaves the daemon crashed. */
+    async handle(req, res) {
+        try {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const method = (req.method ?? 'GET').toUpperCase();
+            const matched = this.match(method, url.pathname);
+            if (matched === null) {
+                writeError(res, 404, 'not_found', `no route for ${method} ${url.pathname}`);
+                return;
+            }
+            let body;
+            try {
+                body = await readJsonBody(req);
+            }
+            catch (err) {
+                const code = err instanceof BodyTooLargeError ? 'payload_too_large' : 'invalid_request';
+                writeError(res, code === 'payload_too_large' ? 413 : 400, code, err.message);
+                return;
+            }
+            const ctx = {
+                method,
+                path: url.pathname,
+                params: matched.params,
+                query: url.searchParams,
+                body,
+                req,
+                res,
+            };
+            const result = await matched.handler(ctx);
+            writeResult(res, result);
+        }
+        catch (err) {
+            // The handler (or something in dispatch) threw — map it and respond. A
+            // request-listener that throws would crash the whole daemon; never allow
+            // it (mirrors server.ts's belt-and-suspenders 500).
+            const { status, body } = toErrorBody(err);
+            // A 500 body carries only a bounded cause (map.ts:boundedCause); the FULL
+            // error — stack included — lives ONLY here, so it must be logged or the
+            // real cause is lost. (map.ts long claimed "logged server-side"; nothing
+            // actually did until this.) <500 named errors already carry their cause
+            // in the response, so they need no extra log line.
+            if (status >= 500) {
+                emitEvent({
+                    event: 'api.request.failed',
+                    level: 'error',
+                    error: err instanceof Error ? err : new Error(String(err)),
+                    fields: { method: (req.method ?? 'GET').toUpperCase(), path: req.url ?? '' },
+                });
+            }
+            writeJson(res, status, body);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+/** Split a path/pattern into non-empty segments (leading/trailing '/' ignored). */
+function splitPath(p) {
+    return p.split('/').filter((s) => s.length > 0);
+}
+/** Match a compiled pattern's segments against a request path's segments,
+ *  returning captured `:name` params, or null when the shapes differ. */
+function matchSegments(pattern, actual) {
+    if (pattern.length !== actual.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < pattern.length; i++) {
+        const seg = pattern[i];
+        const got = actual[i];
+        if (seg.startsWith(':')) {
+            params[seg.slice(1)] = decodeURIComponent(got);
+        }
+        else if (seg !== got) {
+            return null;
+        }
+    }
+    return params;
+}
+// ---------------------------------------------------------------------------
+// Body + response I/O
+// ---------------------------------------------------------------------------
+class BodyTooLargeError extends Error {
+}
+/** Read and JSON-parse the request body. Returns `undefined` for an empty body.
+ *  Throws `BodyTooLargeError` past the cap and a plain `Error` on malformed
+ *  JSON (both mapped to 4xx by the caller). */
+async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > MAX_BODY_BYTES) {
+            throw new BodyTooLargeError(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+        }
+        chunks.push(buf);
+    }
+    if (total === 0)
+        return undefined;
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    if (text === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('request body is not valid JSON');
+    }
+}
+/** Write a handler result: JSON body (if any) at its status, merging headers.
+ *  A 204 or an absent body writes no payload. */
+function writeResult(res, result) {
+    if (res.headersSent)
+        return;
+    const headers = { ...(result.headers ?? {}) };
+    if (result.status === 204 || result.body === undefined) {
+        res.writeHead(result.status, headers);
+        res.end();
+        return;
+    }
+    if (headers['content-type'] === undefined) {
+        headers['content-type'] = 'application/json; charset=utf-8';
+    }
+    res.writeHead(result.status, headers);
+    res.end(JSON.stringify(result.body));
+}
+function writeJson(res, status, body) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+function writeError(res, status, code, message) {
+    const body = { error: { code, message } };
+    writeJson(res, status, body);
+}

package/dist/daemon/api/server.d.ts

@@ -0,0 +1,23 @@
+export interface CreateApiServerOptions {
+    /** Opt-in TCP listener as `host:port` (or `:port` for all interfaces).
+     *  Falls back to `CRTRD_TCP` when unset. Absent → unix socket only. */
+    tcp?: string;
+}
+export interface ApiServer {
+    /** Tear down both listeners and unlink the socket file. Double-close safe. */
+    close(): Promise<void>;
+}
+/** Create and start the crtrd API server (A-9). Returns immediately with a
+ *  `close()` handle; the listeners bind asynchronously (a unix socket's file is
+ *  created on `listen`, so its 0600 chmod happens in the listen callback). A
+ *  bind failure or a post-listen accept error is emitted and swallowed — it must
+ *  NEVER become an unhandled 'error' that crashes the daemon.
+ *
+ *  NOTE (correction to the plan's "one http.Server bound twice"): a Node
+ *  `net.Server`/`http.Server` binds exactly ONE handle — a second `.listen()`
+ *  on the same instance throws `ERR_SERVER_ALREADY_LISTEN`. So the two listeners
+ *  are two `http.Server` instances SHARING the same request + upgrade handler
+ *  functions (the standard way to bind one logical API to two transports). The
+ *  Router and attach bridge are process-wide singletons, so both servers route
+ *  into identical state. */
+export declare function createApiServer(opts?: CreateApiServerOptions): ApiServer;