@north-light/crouter-api 0.3.156

package/README.md

@@ -0,0 +1,51 @@
+# @north-light/crouter-api
+
+The typed contract for **crtrd**'s `/v1` HTTP API — DTOs, route builders, the
+error contract, and the `CrtrClient` transport. This is the client-side surface
+external consumers (e.g. Northlight Core) use to talk to a crtrd instance
+without depending on the full `@crouton-kit/crouter` runtime.
+
+Zero runtime dependencies: the built package is Node built-ins (`node:http`,
+`node:https`, `node:os`, `node:path`) plus its own modules only. No install
+scripts.
+
+> Private package (`"access": "restricted"`) published under the `@north-light`
+> org. Not a general-purpose SDK.
+
+## Install
+
+```sh
+npm install @north-light/crouter-api
+```
+
+## Usage
+
+```ts
+import { CrtrClient, type NodeSummaryDTO } from '@north-light/crouter-api';
+
+// Talk to a remote crtrd over TCP (e.g. a Blaxel preview edge).
+const client = new CrtrClient({ baseUrl: 'https://my-crtrd.example.com' });
+
+const nodes: NodeSummaryDTO[] = await client.listNodes();
+```
+
+`CrtrClient` also drives a local crtrd over its unix socket; see the
+`CrtrClientOptions` type for `socketPath`, auth headers, and the `onColdSocket`
+autostart hook.
+
+## What's exported
+
+- **`CrtrClient`** — typed HTTP client wrapping every `/v1` route.
+- **DTOs** — request/response types for nodes, lifecycle, messages, reports,
+  subscriptions, focuses, triggers, config, attach, profiles, model-auth,
+  canvas, worktree, and human-in-the-loop.
+- **`routes` / `API_VERSION`** — pure path builders for the `/v1` surface.
+- **`ApiError` / `ErrorBody` / `isErrorBody`** — the error contract.
+
+## Source of truth & releases
+
+The source lives in the [`crouter`](https://github.com/vallum-security/crouter)
+repo at `src/api/`; this package is a build-and-publish mirror of that subtree
+(it carries no source of its own). It is published by the `publish-api.yml`
+GitHub Action when a tag matching `api-vX.Y.Z` is pushed — the tag version must
+match this package's `version`.

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/client.test.js

@@ -0,0 +1,274 @@
+// client.test.ts — regression for issue #516: a cold-start `/healthz` timeout
+// used to throw a bare `daemon_unavailable` message that discarded the actual
+// startup failure (the tail of crtrd.err). `coldStartTimeoutMessage` is the
+// pure composition `handleColdSocket` uses on timeout; this proves an injected
+// diagnostic is appended (not dropped) and that a missing/empty diagnostic
+// still falls back to the original bare message unchanged. `safeColdStartDiagnostic`
+// is the guard `handleColdSocket` applies before that composition; this proves a
+// THROWING hook is treated as absent (per the documented `CrtrClientOptions`
+// contract) instead of propagating and replacing the typed `daemon_unavailable`
+// error.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { coldStartTimeoutMessage, CrtrClient, safeColdStartDiagnostic } from '../client.js';
+import { ApiError } from '../errors.js';
+test('coldStartTimeoutMessage appends a present diagnostic to the base message', () => {
+    const msg = coldStartTimeoutMessage('crtrd.err (tail):\nError: bind EADDRINUSE');
+    assert.match(msg, /crtrd did not start/);
+    assert.match(msg, /crtrd\.err \(tail\):\nError: bind EADDRINUSE/);
+});
+test('coldStartTimeoutMessage falls back to the bare message when no diagnostic is available', () => {
+    assert.equal(coldStartTimeoutMessage(undefined), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.');
+    assert.equal(coldStartTimeoutMessage(''), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.');
+});
+function startDelayedHealthzServer(socketPath, delayMs) {
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    });
+    const timer = setTimeout(() => server.listen(socketPath), delayMs);
+    return { server, cancel: () => clearTimeout(timer) };
+}
+// REGRESSION: `crtr sys daemon restart` acks, then tears the old server down and
+// hands over to a successor — a request crossing that window dies with a hang-up
+// (ECONNRESET), not a refused connect. That used to surface as
+// `daemon_unavailable: socket hang up` telling the caller to run
+// `crtr sys daemon start` against a daemon that was already coming back up.
+function startHandoverServer(socketPath) {
+    let dropped = false;
+    const server = createServer((req, res) => {
+        if (!dropped) {
+            dropped = true; // model the old server dying mid-request
+            req.socket.destroy();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, method: req.method }));
+    });
+    return {
+        server,
+        ready: new Promise((resolvePromise) => server.listen(socketPath, resolvePromise)),
+    };
+}
+test('a hang-up mid-request rides out the daemon handover and replays the idempotent call', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true, method: 'GET' });
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a hang-up mid-mutation reports daemon_restarting, not daemon_unavailable', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        await assert.rejects(() => client.request('POST', '/v1/nodes', {}), 
+        // Replaying is unsafe (the daemon may have applied it), so this one is the
+        // caller's call — but it must not be reported as a daemon that is down.
+        (err) => err instanceof ApiError && err.code === 'daemon_restarting');
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start fails loud when the injected poll window is shorter than the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 100, // shorter than the 300ms the daemon actually needs
+        });
+        await assert.rejects(() => client.healthz(), (err) => err instanceof ApiError && err.code === 'daemon_unavailable');
+    }
+    finally {
+        cancel(); // the client already timed out at 100ms; never let listen() fire at 300ms
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start succeeds when the injected poll window covers the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 2_000, // long enough to see the 300ms-delayed daemon come up
+        });
+        const health = await client.healthz();
+        assert.deepEqual(health, { ok: true });
+    }
+    finally {
+        cancel(); // already fired by the time we get here; harmless no-op
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('safeColdStartDiagnostic returns undefined for an absent hook', () => {
+    assert.equal(safeColdStartDiagnostic(undefined), undefined);
+});
+test('safeColdStartDiagnostic returns the hook result when it succeeds', () => {
+    assert.equal(safeColdStartDiagnostic(() => 'crtrd.err (tail):\nboom'), 'crtrd.err (tail):\nboom');
+});
+test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated error', () => {
+    assert.equal(safeColdStartDiagnostic(() => {
+        throw new Error('custom hook blew up');
+    }), undefined);
+});
+/** Spin a loopback server on a temp unix socket that records every request and
+ *  replies with `respond(req)`. `respond` returning `undefined` means "handler
+ *  not reached for this call" and is never exercised by these tests. */
+async function startCapturingServer(respond) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-inbox-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const requests = [];
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            const body = raw.trim() === '' ? undefined : JSON.parse(raw);
+            const captured = { method: req.method ?? '', path: req.url ?? '', body };
+            requests.push(captured);
+            const { status, body: resBody } = respond(captured);
+            res.writeHead(status, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(resBody));
+        });
+    });
+    await new Promise((resolvePromise) => server.listen(socketPath, resolvePromise));
+    const client = new CrtrClient({ socketPath, autostart: false });
+    return {
+        client,
+        requests,
+        close: () => new Promise((resolvePromise, rejectPromise) => {
+            server.close((err) => (err ? rejectPromise(err) : resolvePromise()));
+        }).finally(() => rmSync(dir, { recursive: true, force: true })),
+    };
+}
+const SAMPLE_TICKET_ID = 'a'.repeat(64);
+test('listHumanInbox sends GET /v1/human/inbox with no body and returns the parsed list', async () => {
+    const inboxList = { tickets: [{ ticket_id: SAMPLE_TICKET_ID, kind: 'deck', title: 'Approve deploy', blocked_since: '2026-01-01T00:00:00Z', source: {} }] };
+    const srv = await startCapturingServer(() => ({ status: 200, body: inboxList }));
+    try {
+        const result = await srv.client.listHumanInbox();
+        assert.deepEqual(result, inboxList);
+        assert.equal(srv.requests.length, 1);
+        assert.equal(srv.requests[0]?.method, 'GET');
+        assert.equal(srv.requests[0]?.path, '/v1/human/inbox');
+        assert.equal(srv.requests[0]?.body, undefined);
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('getHumanInboxDeck sends GET /v1/human/inbox/:ticket_id with no body and returns the parsed deck', async () => {
+    const deck = { ticket_id: SAMPLE_TICKET_ID, kind: 'deck', deck: { title: 'Approve deploy', interactions: [] } };
+    const srv = await startCapturingServer(() => ({ status: 200, body: deck }));
+    try {
+        const result = await srv.client.getHumanInboxDeck(SAMPLE_TICKET_ID);
+        assert.deepEqual(result, deck);
+        assert.equal(srv.requests[0]?.method, 'GET');
+        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}`);
+        assert.equal(srv.requests[0]?.body, undefined);
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('respondHumanInboxDeck sends POST with the exact responses body and returns the canonical result unchanged', async () => {
+    const request = { responses: [{ id: 'notify', selectedOptionId: 'ok' }] };
+    const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: request.responses, summary: 'Acknowledged', completedAt: '2026-01-01T00:00:00Z' };
+    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
+    try {
+        const got = await srv.client.respondHumanInboxDeck(SAMPLE_TICKET_ID, request);
+        assert.deepEqual(got, result);
+        assert.equal(srv.requests[0]?.method, 'POST');
+        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}/respond`);
+        assert.deepEqual(srv.requests[0]?.body, request);
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('cancelHumanInboxTicket sends POST with the reason body when a request is passed', async () => {
+    const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2026-01-01T00:00:00Z', reason: 'no longer needed', actor: 'human' };
+    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
+    try {
+        const got = await srv.client.cancelHumanInboxTicket(SAMPLE_TICKET_ID, { reason: 'no longer needed' });
+        assert.deepEqual(got, result);
+        assert.equal(srv.requests[0]?.method, 'POST');
+        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}/cancel`);
+        assert.deepEqual(srv.requests[0]?.body, { reason: 'no longer needed' });
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('cancelHumanInboxTicket sends an empty object body when no request is passed', async () => {
+    const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2026-01-01T00:00:00Z' };
+    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
+    try {
+        const got = await srv.client.cancelHumanInboxTicket(SAMPLE_TICKET_ID);
+        assert.deepEqual(got, result);
+        assert.deepEqual(srv.requests[0]?.body, {});
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('a non-2xx inbox error body decodes to a typed ApiError (status/code/message)', async () => {
+    const srv = await startCapturingServer(() => ({
+        status: 409,
+        body: { error: { code: 'ticket_kind_unsupported', message: 'review tickets have no v1 response operation' } },
+    }));
+    try {
+        await assert.rejects(() => srv.client.respondHumanInboxDeck(SAMPLE_TICKET_ID, { responses: [] }), (err) => {
+            assert.ok(err instanceof ApiError);
+            assert.equal(err.status, 409);
+            assert.equal(err.code, 'ticket_kind_unsupported');
+            assert.match(err.message, /review tickets have no v1 response operation/);
+            return true;
+        });
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('a malformed local ticket id throws a synchronous TypeError and never reaches the transport', async () => {
+    const srv = await startCapturingServer(() => {
+        throw new Error('handler must never be invoked for a locally-rejected ticket id');
+    });
+    try {
+        assert.throws(() => srv.client.getHumanInboxDeck('not-a-valid-hash'), TypeError);
+        assert.throws(() => srv.client.respondHumanInboxDeck('short', { responses: [] }), TypeError);
+        assert.throws(() => srv.client.cancelHumanInboxTicket('UPPERCASE'.repeat(7)), TypeError);
+        assert.equal(srv.requests.length, 0);
+    }
+    finally {
+        await srv.close();
+    }
+});

package/dist/client.d.ts

@@ -0,0 +1,246 @@
+import type { DaemonRestartDTO, HealthDTO, StatusDTO } from './dto/health.js';
+import type { ArtifactListDTO, ArtifactsQuery, ContextListDTO, CreateNodeRequest, ListNodesQuery, NodeDetailDTO, NodeSnapshotDTO, NodeSummaryDTO, TranscriptDTO, TranscriptQuery } from './dto/nodes.js';
+import type { InterruptResultDTO, MessageResultDTO, SendMessageRequest } from './dto/messages.js';
+import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery } from './dto/reports.js';
+import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
+import type { SubscribeRequest, SubscriptionDTO } from './dto/subscriptions.js';
+import type { FocusDTO, RegisterFocusRequest, SetFocusPaneRequest } from './dto/focus.js';
+import { type ArmCronRequest, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery } from './dto/crons.js';
+import type { NodeConfigPatch } from './dto/config.js';
+import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js';
+import type { EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
+import type { FilePeekDTO } from './dto/files.js';
+import type { CredentialResultDTO, InstallCredentialRequest } from './dto/modelauth.js';
+import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanConsultResultDTO, HumanDeliverResultDTO, HumanVisualResultDTO } from './dto/human.js';
+import type { CancelInboxTicketRequest, CanceledTicketResultDTO, DeckTicketResultDTO, InboxDeckDTO, InboxListDTO, InboxTicketIdDTO, RespondInboxDeckRequest } from './dto/inbox.js';
+import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
+import type { CloseWorktreeResultDTO } from './dto/worktree.js';
+export interface CrtrClientOptions {
+    /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
+    socketPath?: string;
+    /** `http(s)://host:port` for TCP/remote transport. */
+    baseUrl?: string;
+    /** Extra headers (e.g. an edge auth token on TCP; crtrd ignores it). */
+    headers?: Record<string, string>;
+    /** Autostart on a cold socket (default true for socketPath, false for baseUrl). */
+    autostart?: boolean;
+    /** Per-request timeout in ms (default 30_000). */
+    timeoutMs?: number;
+    /** Injected daemon-start hook (spec §7.1). Called once on a cold socket when
+     *  autostart is on; after it resolves, the client polls `/healthz` and retries
+     *  the original request once. Absent → a cold socket throws `daemon_unavailable`. */
+    onColdSocket?: () => Promise<void>;
+    /** Injected cold-start diagnostic (issue #516). Called ONLY when the bounded
+     *  `/healthz` poll times out after `onColdSocket`, so the caller can attach
+     *  operator-useful context (e.g. a bounded tail of crtrd's stderr log) to the
+     *  `daemon_unavailable` error instead of it staying a bare message. Must
+     *  return synchronously and cheaply — it runs on the failure path, not the
+     *  happy path. A thrown/undefined result is treated as "no diagnostic". */
+    coldStartDiagnostic?: () => string | undefined;
+    /** Bounded window (ms) to poll `/healthz` after `onColdSocket` resolves
+     *  before giving up with `daemon_unavailable`. Defaults to
+     *  `HEALTHZ_POLL_WINDOW_MS`. This must NOT silently drift from whatever
+     *  window actually governs "did the daemon start" (issue #508 follow-up):
+     *  `onColdSocket` is fire-and-forget, so this poll is the ONLY deadline that
+     *  determines whether the CLI reports success. A caller whose `onColdSocket`
+     *  hook triggers a differently-windowed startup verifier (e.g. the CLI's
+     *  `ensureDaemon`/`verifyDaemonStartup`) must pass that same window here so
+     *  a slow-but-valid cold start cannot pass the authoritative verifier while
+     *  this poll times out first. */
+    coldStartPollWindowMs?: number;
+}
+export declare class CrtrClient {
+    private readonly socketPath?;
+    private readonly baseUrl?;
+    private readonly headers;
+    private readonly autostart;
+    private readonly timeoutMs;
+    private readonly onColdSocket?;
+    private readonly coldStartDiagnostic?;
+    private readonly coldStartPollWindowMs;
+    /** Guards against re-entering the autostart path more than once per client. */
+    private coldStartAttempted;
+    constructor(opts: CrtrClientOptions);
+    /** Construct a client bound to the default local socket with autostart on. Pass
+     *  `onColdSocket` to enable the daemon-spawn hook (spec §7.1); without it a cold
+     *  socket fails loud with `daemon_unavailable`. */
+    static forLocalSocket(opts?: Omit<CrtrClientOptions, 'socketPath' | 'baseUrl'>): CrtrClient;
+    healthz(): Promise<HealthDTO>;
+    status(): Promise<StatusDTO>;
+    /** Ask the daemon to replace itself with a successor running the currently
+     *  selected runtime generation. Answers before the handover starts, so a
+     *  caller living inside a node the handover will tear down still gets a
+     *  settled result. */
+    restartDaemon(): Promise<DaemonRestartDTO>;
+    createNode(req: CreateNodeRequest): Promise<NodeDetailDTO>;
+    listNodes(q?: ListNodesQuery): Promise<NodeSummaryDTO[]>;
+    getNode(id: string): Promise<NodeDetailDTO>;
+    sendMessage(id: string, req: SendMessageRequest): Promise<MessageResultDTO>;
+    /** First-class interrupt (the human Esc): cancels pending undelivered
+     *  human-send inbox entries, then aborts a live in-flight turn. NEVER
+     *  revives a dormant target. */
+    interruptNode(id: string): Promise<InterruptResultDTO>;
+    pushReport(id: string, req: PushReportRequest): Promise<PushReportResultDTO>;
+    forkNode(id: string): Promise<NodeDetailDTO>;
+    reviveNode(id: string, req?: ReviveRequest): Promise<ReviveResultDTO>;
+    relaunchRoot(id: string): Promise<RelaunchRootResultDTO>;
+    closeNode(id: string, req?: CloseRequest): Promise<CloseResultDTO>;
+    recycleNode(id: string): Promise<NodeDetailDTO>;
+    demoteNode(id: string): Promise<NodeDetailDTO>;
+    promoteNode(id: string, req: PromoteRequest): Promise<NodeDetailDTO>;
+    yieldNode(id: string, req: YieldRequest): Promise<NodeDetailDTO>;
+    waitNode(id: string, req: WaitRequest): Promise<NodeDetailDTO>;
+    patchConfig(id: string, patch: NodeConfigPatch): Promise<NodeDetailDTO>;
+    /** Land + close the node's managed git worktree (spec §6.2). Server-side
+     *  because it interleaves a canvas WRITE with a git land transaction and
+     *  crtrd is the repo host (same principle as spawnChild's creation git). */
+    closeWorktree(id: string): Promise<CloseWorktreeResultDTO>;
+    subscribe(id: string, req: SubscribeRequest): Promise<SubscriptionDTO>;
+    listFocuses(): Promise<FocusDTO[]>;
+    focusOf(nodeId: string): Promise<FocusDTO | null>;
+    focusByPane(pane: string): Promise<FocusDTO | null>;
+    registerFocus(req: RegisterFocusRequest): Promise<FocusDTO | null>;
+    setFocusPane(focusId: string, req: SetFocusPaneRequest): Promise<void>;
+    closeFocus(focusId: string): Promise<void>;
+    unsubscribe(id: string, target: string): Promise<void>;
+    /** Arm one cron (`POST /v1/crons`) — the server mints the cron_id. */
+    armCron(req: ArmCronRequest): Promise<CronDTO>;
+    /** Crons visible to the caller (`GET /v1/crons`). With `q.profile` that is
+     *  that profile's crons plus every global one; omit it only for a
+     *  canvas-home-wide provenance read ("which crons did node X arm"). */
+    listCrons(q?: ListCronsQuery): Promise<CronDTO[]>;
+    /** One cron with its run-log ring (`GET /v1/crons/:cronId`). */
+    showCron(cronId: string, q?: CronScopeQuery): Promise<CronShowDTO>;
+    /** Pause one cron (`POST /v1/crons/:cronId/pause`) — stops firing, keeps config+history. */
+    pauseCron(cronId: string, q?: CronScopeQuery): Promise<CronDTO>;
+    /** Resume one paused cron (`POST /v1/crons/:cronId/resume`). */
+    resumeCron(cronId: string, q?: CronScopeQuery): Promise<CronDTO>;
+    /** Run one cron NOW, out of band (`POST /v1/crons/:cronId/run`) — synchronous:
+     *  resolves with the settled run record after the subprocess closes. Does not
+     *  advance the schedule or consume a one-shot; never escalates. */
+    runCron(cronId: string, q?: CronScopeQuery): Promise<CronRunDTO>;
+    /** Cancel one cron (`DELETE /v1/crons/:cronId`, idempotent). */
+    cancelCron(cronId: string, q?: CronScopeQuery): Promise<void>;
+    ensureAttach(id: string, req?: AttachEnsureRequest): Promise<AttachEnsureResultDTO>;
+    getReports(id: string, q?: ReportsQuery): Promise<ReportDTO[]>;
+    getTranscript(id: string, q?: TranscriptQuery): Promise<TranscriptDTO>;
+    getSnapshot(id: string): Promise<NodeSnapshotDTO>;
+    getArtifacts(id: string, q?: ArtifactsQuery): Promise<ArtifactListDTO>;
+    getContext(id: string): Promise<ContextListDTO>;
+    /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
+     *  the browser file-peek panel. */
+    peekFile(path: string): Promise<FilePeekDTO>;
+    ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
+    listProfiles(): Promise<ProfileDTO[]>;
+    getProfile(name: string): Promise<ProfileDTO>;
+    /** Delete one profile by exact id or unique name (`DELETE /v1/profiles/:name`,
+     *  idempotent — a miss is success). */
+    deleteProfile(name: string): Promise<void>;
+    installCredential(provider: string, req: InstallCredentialRequest): Promise<CredentialResultDTO>;
+    /** Create a terminal `kind:'human'` bridge node with NO broker engine
+     *  (`spawnNode` server-side). Distinct from `createNode` (which launches a
+     *  broker) precisely because a human bridge must never have one. */
+    createHumanBridge(req: CreateHumanBridgeRequest): Promise<HumanBridgeResultDTO>;
+    /** Run the registered humanloop completion handler server-side for one
+     *  `humanloop.completion/v1` event. crtrd re-verifies the full trust binding
+     *  before performing any canvas mutation. */
+    deliverHuman(event: unknown): Promise<HumanDeliverResultDTO>;
+    /** Run the registered follow-up handler server-side for one
+     *  `humanloop.followup-request/v1` event. */
+    consultHuman(event: unknown): Promise<HumanConsultResultDTO>;
+    /** Run the registered visual handler server-side for one
+     *  `humanloop.visual-request-event/v1` event. */
+    visualHuman(event: unknown): Promise<HumanVisualResultDTO>;
+    /** Pending deck/review tickets across every available crouter-owned
+     *  humanloop root. */
+    listHumanInbox(): Promise<InboxListDTO>;
+    /** Read one pending deck by its opaque ticket id, with Markdown bodies
+     *  resolved inline. */
+    getHumanInboxDeck(ticketId: InboxTicketIdDTO): Promise<InboxDeckDTO>;
+    /** Submit ordered interaction responses for a pending deck. Single-assignment
+     *  server-side: a competing resolution races to `ticket_already_resolved`. */
+    respondHumanInboxDeck(ticketId: InboxTicketIdDTO, request: RespondInboxDeckRequest): Promise<DeckTicketResultDTO>;
+    /** Cancel a pending deck (terminal response, never deletion). */
+    cancelHumanInboxTicket(ticketId: InboxTicketIdDTO, request?: CancelInboxTicketRequest): Promise<CanceledTicketResultDTO>;
+    /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
+     *  the dashboard is absorbed into those two reads; there is no single route).
+     *  `generated_at` is the client-side capture instant of the composition. */
+    dashboard(q?: DashboardQuery): Promise<DashboardDTO>;
+    attention(): Promise<AttentionDTO>;
+    /** Per-node pending-ticket counts for a bounded viewer slice. */
+    attentionCounts(node_ids: string[]): Promise<AttentionCountsDTO>;
+    /** Ranked/filtered content search over the per-cwd episodic corpus
+     *  (`crtr canvas history search`). Optional query: ranked when present,
+     *  recency browse when omitted. POST-bodied — the query carries arrays and
+     *  free text; the whole search executes server-side (spec §6.3). */
+    historySearch(q: HistorySearchQuery): Promise<HistorySearchResultDTO>;
+    /** Required-pattern line-hit search over the per-cwd episodic corpus
+     *  (`crtr canvas history grep`). Distinct stable schema from `historySearch`
+     *  — POST-bodied for the same reasons. */
+    historyGrep(q: HistoryGrepQuery): Promise<HistoryGrepResultDTO>;
+    /** Resolve one `<node-id>:<relpath>` history ref to its full body
+     *  (`crtr canvas history read`). */
+    historyRead(q: HistoryReadQuery): Promise<HistoryReadResultDTO>;
+    /** The machine-readable browser canvas roster (`crtr canvas snapshot`) —
+     *  distinct from the per-node `getSnapshot`. */
+    canvasSnapshot(): Promise<SnapshotDTO>;
+    /** The lean, set-based topology roster (`GET /v1/canvas/roster`) — exactly
+     *  two indexed queries server-side, no per-row enrichment. The recurring
+     *  poll target for attach/browser topology; use `canvasSnapshot` for the
+     *  enriched on-demand view. */
+    canvasRoster(): Promise<RosterDTO>;
+    prune(req: PruneRequest): Promise<PruneResultDTO>;
+    rebuildIndex(): Promise<RebuildIndexResultDTO>;
+    /** Raw request for routes not yet method-wrapped. Applies the same
+     *  autostart + error-mapping semantics. */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    private nodePath;
+    /** Validate a cron id before route construction — `routes.ts` interpolates
+     *  it raw, so a value carrying `/`, whitespace or `?` would corrupt the
+     *  request line rather than 404 cleanly. Mirrors `nodePath`. */
+    private cronPath;
+    /** Validate an opaque inbox ticket id before route construction. A local
+     *  shape violation is a caller bug, not a server-rejectable request — throws
+     *  `TypeError` (matching the existing safe-segment discipline of a local
+     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
+     *  request the server could plausibly receive and reject itself). */
+    private ticketId;
+    private transport;
+    private isColdSocketError;
+    /** A connection torn down MID-request (Node's "socket hang up" / a broken
+     *  pipe) — as distinct from a refused connect, which means nothing is
+     *  listening. On the local socket that is `crtr sys daemon restart` doing its
+     *  generation handover: the daemon acks, then tears itself down and hands
+     *  over to a successor it spawned. The daemon IS coming back. */
+    private isHandoverHangup;
+    /** Wait for the successor to answer `/healthz`, then replay the request when
+     *  replaying is safe. GET/HEAD are idempotent, so they retry transparently —
+     *  the handover stays invisible, which is the whole point of a restart that
+     *  resumes every node. A mutation may already have been applied server-side
+     *  before the socket dropped, so it fails with `daemon_restarting` (retry),
+     *  never `daemon_unavailable` ("start the daemon" is the wrong advice for a
+     *  daemon that is mid-handover). */
+    private rideOutHandover;
+    /** Poll `/healthz` until the successor daemon answers, bounded by the
+     *  cold-start window. Tolerates both the pre-listen gap (cold socket) and a
+     *  second hang-up from a server still tearing down. */
+    private awaitHandover;
+    /** Trigger the injected daemon-start hook, poll `/healthz`, then let the caller
+     *  retry once. Fail loud with `daemon_unavailable` when autostart is off, no
+     *  hook is wired, or the daemon never becomes reachable. */
+    private handleColdSocket;
+}
+/** Compose the cold-start `/healthz`-timeout `daemon_unavailable` message,
+ *  appending the injected diagnostic (issue #516) when one is present instead
+ *  of discarding the real startup failure behind a bare message. Exported (not
+ *  from the package's public `index.ts` surface, which is dependency-light by
+ *  design) purely so the regression test can assert the composition without
+ *  waiting out the real poll window. */
+export declare function coldStartTimeoutMessage(diagnostic: string | undefined): string;
+/** Invoke the injected `coldStartDiagnostic` hook, treating a THROW the same
+ *  as an absent/undefined result — the contract `CrtrClientOptions` documents
+ *  ("a thrown/undefined result is treated as 'no diagnostic'"). Without this,
+ *  a broken hook would propagate and replace the typed `daemon_unavailable`
+ *  error the caller is entitled to. Exported alongside `coldStartTimeoutMessage`
+ *  for the same direct-unit-test reason. */
+export declare function safeColdStartDiagnostic(hook: (() => string | undefined) | undefined): string | undefined;