@north-light/crouter-api 0.3.303 → 0.3.305

package/dist/api/__tests__/integration/client.test.js

@@ -1,30 +1,12 @@
-// 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.log). `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.
+// Client availability recovery regressions.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createServer } from 'node:http';
 import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { coldStartTimeoutMessage, CrtrClient, safeColdStartDiagnostic } from '../../client.js';
+import { CrtrClient, safeColdStartDiagnostic } from '../../client.js';
 import { ApiError } from '../../errors.js';
-test('coldStartTimeoutMessage appends a present diagnostic to the base message', () => {
-    const msg = coldStartTimeoutMessage('crtrd.log (tail):\nError: bind EADDRINUSE');
-    assert.match(msg, /crtrd did not start/);
-    assert.match(msg, /crtrd\.log \(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.log.');
-    assert.equal(coldStartTimeoutMessage(''), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.log.');
-});
 function startDelayedHealthzServer(socketPath, delayMs) {
     const server = createServer((_req, res) => {
         res.writeHead(200, { 'content-type': 'application/json' });
@@ -33,11 +15,7 @@ function startDelayedHealthzServer(socketPath, delayMs) {
     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.
+// A dropped response is distinct from a refused connect. Its cause is unknown, so reads may wait and retry but mutations never replay.
 function startHandoverServer(socketPath) {
     let dropped = false;
     const server = createServer((req, res) => {
@@ -68,7 +46,7 @@ test('a hang-up mid-request rides out the daemon handover and replays the idempo
         rmSync(dir, { recursive: true, force: true });
     }
 });
-test('a hang-up mid-mutation reports daemon_restarting, not daemon_unavailable', async () => {
+test('an interrupted mutation is not replayed or labelled a daemon handover', async () => {
     const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
     const socketPath = join(dir, 'crtrd.sock');
     const { server, ready } = startHandoverServer(socketPath);
@@ -78,7 +56,7 @@ test('a hang-up mid-mutation reports daemon_restarting, not daemon_unavailable',
         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');
+        (err) => err instanceof ApiError && err.code === 'daemon_request_interrupted');
     }
     finally {
         server.close();
@@ -127,24 +105,47 @@ test('cliClient-style cold start fails loud when the injected poll window is sho
         rmSync(dir, { recursive: true, force: true });
     }
 });
-test('cliClient-style cold start succeeds when the injected poll window covers the (valid) startup delay', async () => {
+test('a disabled-autostart client waits for an externally managed listener without invoking its spawn hook', async () => {
     const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
     const socketPath = join(dir, 'crtrd.sock');
-    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 100);
+    let spawnAttempts = 0;
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: false,
+            onColdSocket: async () => { spawnAttempts += 1; },
+            coldStartPollWindowMs: 1_000,
+        });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true });
+        assert.equal(spawnAttempts, 0, 'disabled autostart only waits; it never invokes the spawn hook');
+    }
+    finally {
+        cancel();
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('availability expiry keeps the final transport failure inside one wall-clock budget', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const server = createServer((_req, _res) => { });
+    let listenTimer;
     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
+            timeoutMs: 5_000,
+            coldStartPollWindowMs: 250,
+            onColdSocket: async () => { listenTimer = setTimeout(() => server.listen(socketPath), 10); },
         });
-        const health = await client.healthz();
-        assert.deepEqual(health, { ok: true });
+        const started = Date.now();
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError && error.code === 'request_timeout' && error.message.includes('request timed out'));
+        assert.ok(Date.now() - started < 500, 'a probe cannot extend the 250ms availability budget');
     }
     finally {
-        cancel(); // already fired by the time we get here; harmless no-op
+        if (listenTimer !== undefined)
+            clearTimeout(listenTimer);
         server.close();
         rmSync(dir, { recursive: true, force: true });
     }

package/dist/api/client.d.ts

@@ -47,28 +47,25 @@ export interface CrtrClientOptions {
      *  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":
-     *  `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. */
+    /** Strict wall-clock window (ms) for local API availability after a cold
+     * socket or interrupted response. Each probe is capped to the remaining
+     * budget. Defaults to `HEALTHZ_POLL_WINDOW_MS`. */
     coldStartPollWindowMs?: number;
-    /** Injected check for a STANDING reason the daemon will never come up — one
-     *  that the poll window cannot outlast because nothing about it changes with
-     *  time. Consulted on each `/healthz` poll; a returned string ends the wait
-     *  immediately and becomes the error message.
-     *
-     *  Without this the caller waits out the whole cold-start window to report
-     *  "not reachable", even when the reason it is unreachable — and the repair
-     *  for it — were both known before the first poll. Must be synchronous and
-     *  cheap; it runs on every poll tick. */
+    /** Injected check for a standing startup block. After an attempted spawn,
+     * its result supplements the observed transport failure with the known repair. */
     coldStartAbort?: () => string | null;
 }
+/** One strict wall-clock availability window shared by local API clients and
+ * daemon management. Each probe gets only the budget remaining at its start. */
+export declare function waitForDaemonAvailability({ windowMs, probe, initialError, pollIntervalMs, retry, now, sleep, }: {
+    windowMs: number;
+    probe: (timeoutMs: number) => Promise<void>;
+    initialError?: unknown;
+    pollIntervalMs?: number;
+    retry?: (error: unknown) => boolean;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void> | void;
+}): Promise<void>;
 export declare class CrtrClient {
     private readonly socketPath?;
     private readonly baseUrl?;
@@ -79,7 +76,7 @@ export declare class CrtrClient {
     private readonly coldStartDiagnostic?;
     private readonly coldStartPollWindowMs;
     private readonly coldStartAbort?;
-    /** Guards against re-entering the autostart path more than once per client. */
+    /** Guards against invoking the daemon-start hook more than once per client. */
     private coldStartAttempted;
     constructor(opts: CrtrClientOptions);
     /** Construct a client bound to the default local socket with autostart on. Pass
@@ -87,6 +84,9 @@ export declare class CrtrClient {
      *  socket fails loud with `daemon_unavailable`. */
     static forLocalSocket(opts?: Omit<CrtrClientOptions, 'socketPath' | 'baseUrl'>): CrtrClient;
     healthz(): Promise<HealthDTO>;
+    /** One `/healthz` observation without cold-socket recovery. Availability
+     * waiters own retry policy and pass their remaining wall-clock budget here. */
+    probeHealthz(timeoutMs: number): 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
@@ -314,8 +314,8 @@ export declare class CrtrClient {
     /** 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>;
-    /** The unparsed request: autostart + handover recovery, no JSON parse. Every
-     *  wrapper goes through here; only the non-JSON routes call it directly. */
+    /** The unparsed request: cold-socket and interrupted-response recovery, no
+     * JSON parse. Every wrapper goes through here; only non-JSON routes call it directly. */
     private send;
     private nodePath;
     /** Validate a human interaction id before route construction. Reply-bearing
@@ -348,39 +348,16 @@ export declare class CrtrClient {
     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. */
+     * pipe). It establishes only that the response was interrupted, not why. */
+    private isInterruptedSocketError;
+    /** Wait for the local API after an interrupted response. GET/HEAD can retry
+     * because they are idempotent. A mutation may already have been applied, so
+     * it never replays. */
+    private rideOutInterruptedRequest;
+    private awaitAvailability;
+    /** Optionally start the daemon, then observe availability before retrying the
+     * request. Waiting is independent from permission to spawn: externally
+     * managed daemons still get the same bounded readiness window. */
     private handleColdSocket;
 }
-/** Compose the cold-start `/healthz`-timeout `daemon_unavailable` message,
- *  appending the injected diagnostic 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;

package/dist/api/client.js

@@ -4,8 +4,8 @@
 // (`node:http`, `node:https`, `node:os`, `node:path`) plus `src/api/*`. Never
 // `core/*` / `node:sqlite` / TUI. The daemon-spawn logic lives in `core`/
 // `daemon`, which this module may not import — so autostart is delegated to an
-// injectable `onColdSocket` hook the CLI wires in (spec §7.1). Absent the hook,
-// a cold socket throws `daemon_unavailable` immediately.
+// injectable `onColdSocket` hook the CLI wires in (spec §7.1). A cold socket
+// always gets one bounded availability observation; the hook only permits spawning.
 //
 // TRANSPORT (spec O-1): `node:http`/`node:https` `request()` — NO `undici`.
 // unix socket via `{ socketPath }`; TCP/remote via a parsed `baseUrl`.
@@ -39,6 +39,30 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  *  `onColdSocket`, when the caller does not pass `coldStartPollWindowMs`. */
 const HEALTHZ_POLL_WINDOW_MS = 10_000;
 const HEALTHZ_POLL_INTERVAL_MS = 200;
+/** One strict wall-clock availability window shared by local API clients and
+ * daemon management. Each probe gets only the budget remaining at its start. */
+export async function waitForDaemonAvailability({ windowMs, probe, initialError, pollIntervalMs = HEALTHZ_POLL_INTERVAL_MS, retry = () => true, now = Date.now, sleep = sleepMs, }) {
+    const deadline = now() + windowMs;
+    let lastError = initialError;
+    for (;;) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw lastError ?? new Error('crtrd availability window expired without a probe failure');
+        try {
+            await probe(remaining);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (!retry(error))
+                throw error;
+        }
+        const afterProbe = deadline - now();
+        if (afterProbe <= 0)
+            throw lastError;
+        await sleep(Math.min(pollIntervalMs, afterProbe));
+    }
+}
 export class CrtrClient {
     socketPath;
     baseUrl;
@@ -49,7 +73,7 @@ export class CrtrClient {
     coldStartDiagnostic;
     coldStartPollWindowMs;
     coldStartAbort;
-    /** Guards against re-entering the autostart path more than once per client. */
+    /** Guards against invoking the daemon-start hook more than once per client. */
     coldStartAttempted = false;
     constructor(opts) {
         const hasSocket = opts.socketPath !== undefined && opts.socketPath !== '';
@@ -82,6 +106,11 @@ export class CrtrClient {
     healthz() {
         return this.request('GET', routes.healthz());
     }
+    /** One `/healthz` observation without cold-socket recovery. Availability
+     * waiters own retry policy and pass their remaining wall-clock budget here. */
+    async probeHealthz(timeoutMs) {
+        return parse(await this.transport('GET', routes.healthz(), undefined, undefined, timeoutMs));
+    }
     status() {
         return this.request('GET', routes.status());
     }
@@ -583,19 +612,24 @@ export class CrtrClient {
     async request(method, path, body) {
         return parse(await this.send(method, path, body));
     }
-    /** The unparsed request: autostart + handover recovery, no JSON parse. Every
-     *  wrapper goes through here; only the non-JSON routes call it directly. */
+    /** The unparsed request: cold-socket and interrupted-response recovery, no
+     * JSON parse. Every wrapper goes through here; only non-JSON routes call it directly. */
     async send(method, path, body, extraHeaders) {
         try {
             return await this.transport(method, path, body, extraHeaders);
         }
         catch (err) {
             if (this.isColdSocketError(err)) {
-                await this.handleColdSocket();
-                return await this.transport(method, path, body, extraHeaders);
+                try {
+                    await this.handleColdSocket(err);
+                    return await this.transport(method, path, body, extraHeaders);
+                }
+                catch (recoveryError) {
+                    throw toTransportApiError(recoveryError);
+                }
             }
-            if (this.isHandoverHangup(err))
-                return await this.rideOutHandover(method, path, body, extraHeaders);
+            if (this.isInterruptedSocketError(err))
+                return await this.rideOutInterruptedRequest(method, path, body, extraHeaders);
             throw toTransportApiError(err);
         }
     }
@@ -663,7 +697,7 @@ export class CrtrClient {
         }
         return id;
     }
-    transport(method, path, body, extraHeaders) {
+    transport(method, path, body, extraHeaders, timeoutMs = this.timeoutMs) {
         const usingHttps = this.baseUrl?.protocol === 'https:';
         const doRequest = usingHttps ? httpsRequest : httpRequest;
         const payload = body === undefined ? undefined : JSON.stringify(body);
@@ -676,7 +710,7 @@ export class CrtrClient {
             method,
             path,
             headers,
-            timeout: this.timeoutMs,
+            timeout: timeoutMs,
         };
         if (this.socketPath !== undefined) {
             options.socketPath = this.socketPath;
@@ -717,29 +751,25 @@ export class CrtrClient {
         return code === 'ECONNREFUSED' || code === 'ENOENT' || code === 'ENOTSOCK';
     }
     /** 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. */
-    isHandoverHangup(err) {
+     * pipe). It establishes only that the response was interrupted, not why. */
+    isInterruptedSocketError(err) {
         if (this.socketPath === undefined)
             return false;
         const code = err?.code;
         return code === 'ECONNRESET' || code === 'EPIPE';
     }
-    /** 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). */
-    async rideOutHandover(method, path, body, extraHeaders) {
-        if (!(await this.awaitHandover())) {
-            throw new ApiError(503, 'daemon_unavailable', `crtrd went away mid-request and did not come back within ${this.coldStartPollWindowMs}ms.`);
+    /** Wait for the local API after an interrupted response. GET/HEAD can retry
+     * because they are idempotent. A mutation may already have been applied, so
+     * it never replays. */
+    async rideOutInterruptedRequest(method, path, body, extraHeaders) {
+        try {
+            await this.awaitAvailability();
+        }
+        catch (error) {
+            throw toTransportApiError(error);
         }
         if (method !== 'GET' && method !== 'HEAD') {
-            throw new ApiError(503, 'daemon_restarting', `crtrd handed over to a new runtime generation mid-request; this ${method} may or may not have been applied.`);
+            throw new ApiError(503, 'daemon_request_interrupted', `crtrd connection ended before this ${method} response; the request may or may not have been applied.`);
         }
         try {
             return await this.transport(method, path, body, extraHeaders);
@@ -748,65 +778,42 @@ export class CrtrClient {
             throw toTransportApiError(err);
         }
     }
-    /** 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. */
-    async awaitHandover() {
-        const deadline = Date.now() + this.coldStartPollWindowMs;
-        for (;;) {
-            try {
-                const res = await this.transport('GET', routes.healthz());
-                if (res.status >= 200 && res.status < 300)
-                    return true;
-            }
-            catch (err) {
-                if (!this.isColdSocketError(err) && !this.isHandoverHangup(err))
-                    throw toTransportApiError(err);
-            }
-            if (Date.now() >= deadline)
-                return false;
-            await sleep(HEALTHZ_POLL_INTERVAL_MS);
-        }
+    async awaitAvailability(initialError) {
+        await waitForDaemonAvailability({
+            windowMs: this.coldStartPollWindowMs,
+            initialError,
+            probe: async (timeoutMs) => {
+                const response = await this.transport('GET', routes.healthz(), undefined, undefined, timeoutMs);
+                if (response.status < 200 || response.status >= 300) {
+                    throw new ApiError(response.status, 'daemon_health_unavailable', `crtrd health check returned HTTP ${response.status}: ${response.text.slice(0, 500)}`);
+                }
+            },
+        });
     }
-    /** 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. */
-    async handleColdSocket() {
-        if (!this.autostart || this.onColdSocket === undefined) {
-            throw new ApiError(503, 'daemon_unavailable', 'crtrd is not running and autostart is disabled; run `crtr sys daemon start`.');
+    /** Optionally start the daemon, then observe availability before retrying the
+     * request. Waiting is independent from permission to spawn: externally
+     * managed daemons still get the same bounded readiness window. */
+    async handleColdSocket(initialError) {
+        const startedHere = this.autostart && this.onColdSocket !== undefined && !this.coldStartAttempted;
+        if (startedHere) {
+            this.coldStartAttempted = true;
+            await this.onColdSocket();
         }
-        if (this.coldStartAttempted) {
-            throw new ApiError(503, 'daemon_unavailable', 'crtrd did not become reachable after autostart.');
+        try {
+            await this.awaitAvailability(initialError);
         }
-        this.coldStartAttempted = true;
-        await this.onColdSocket();
-        const deadline = Date.now() + this.coldStartPollWindowMs;
-        for (;;) {
-            try {
-                const res = await this.transport('GET', routes.healthz());
-                if (res.status >= 200 && res.status < 300)
-                    return;
-            }
-            catch (err) {
-                if (!this.isColdSocketError(err))
-                    throw toTransportApiError(err);
-            }
-            // Waiting cannot clear a standing block, and the repair is already known.
-            let standingBlock = null;
-            try {
-                standingBlock = this.coldStartAbort?.() ?? null;
-            }
-            catch {
-                standingBlock = null;
-            }
-            if (standingBlock !== null) {
-                throw new ApiError(503, 'daemon_unavailable', `crtrd cannot start: ${standingBlock}`);
-            }
-            if (Date.now() >= deadline) {
+        catch (error) {
+            if (startedHere) {
+                const standingBlock = safeColdStartAbort(this.coldStartAbort);
+                if (standingBlock !== null)
+                    throw new ApiError(503, 'daemon_unavailable', `crtrd cannot start: ${standingBlock}`);
                 const diagnostic = safeColdStartDiagnostic(this.coldStartDiagnostic);
-                throw new ApiError(503, 'daemon_unavailable', coldStartTimeoutMessage(diagnostic));
+                if (diagnostic !== undefined) {
+                    const transportError = toTransportApiError(error);
+                    throw new ApiError(transportError.status, transportError.code, `${transportError.message}\n${diagnostic}`);
+                }
             }
-            await sleep(HEALTHZ_POLL_INTERVAL_MS);
+            throw error;
         }
     }
 }
@@ -854,7 +861,7 @@ function toTransportApiError(err) {
         return err;
     const code = err?.code;
     const message = err instanceof Error ? err.message : String(err);
-    if (code === 'ECONNREFUSED' || code === 'ENOENT') {
+    if (code === 'ECONNREFUSED' || code === 'ENOENT' || code === 'ENOTSOCK') {
         return new ApiError(503, 'daemon_unavailable', `crtrd is not reachable: ${message}`);
     }
     if (code === 'ETIMEDOUT') {
@@ -864,25 +871,22 @@ function toTransportApiError(err) {
     }
     return new ApiError(503, 'transport_error', message);
 }
-function sleep(ms) {
+function sleepMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/** Compose the cold-start `/healthz`-timeout `daemon_unavailable` message,
- *  appending the injected diagnostic 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 function coldStartTimeoutMessage(diagnostic) {
-    const base = 'crtrd did not start; run `crtr sys daemon start` and check crtrd.log.';
-    return diagnostic !== undefined && diagnostic !== '' ? `${base}\n${diagnostic}` : base;
-}
 /** 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. */
+ * as an absent/undefined result — the contract `CrtrClientOptions` documents
+ * ("a thrown/undefined result is treated as 'no diagnostic'"). */
+function safeColdStartAbort(hook) {
+    if (hook === undefined)
+        return null;
+    try {
+        return hook();
+    }
+    catch {
+        return null;
+    }
+}
 export function safeColdStartDiagnostic(hook) {
     if (hook === undefined)
         return undefined;

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

@@ -55,12 +55,13 @@ export interface MessageResultDTO {
     node_id: NodeIdDTO;
     /** Whether an inbox entry was appended now. */
     delivered: boolean;
-    /** Whether a dormant target was revived to receive the message. */
+    /** Whether this request synchronously launched the target. Ordinary durable
+     *  delivery to an active or idle dormant target always reports false: the
+     *  lifecycle reconciler launches it from the durable inbox entry later. */
     revived: boolean;
-    /** Present only when a wake was attempted and did not happen:
-     *  `capacity_frozen` means no broker slot was free, so the target's row is
-     *  frozen and the daemon relaunches it when one frees. The entry is durably
-     *  appended either way, and delivery follows that relaunch. */
+    /** Present only when this request attempted a synchronous wake and no broker
+     *  slot was free. The target's row is frozen and the daemon relaunches it
+     *  when one frees; the entry was durably appended either way. */
     not_revived_reason?: 'capacity_frozen';
     /** Present only when the entry was appended ABOVE the requested tier: a
      *  terminal target never takes the later cycle `normal`/`deferred` wait for,

package/dist/api/errors.d.ts

@@ -15,5 +15,8 @@ export declare class ApiError extends Error {
     readonly details?: unknown;
     constructor(status: number, code: string, message: string, details?: unknown);
 }
+/** A local API transport failure has stable status/code identity, independent
+ * of message prose. */
+export declare function isDaemonTransportApiError(error: unknown): error is ApiError;
 /** Type guard for an `ErrorBody`-shaped parsed payload. */
 export declare function isErrorBody(value: unknown): value is ErrorBody;

package/dist/api/errors.js

@@ -18,6 +18,16 @@ export class ApiError extends Error {
             this.details = details;
     }
 }
+/** A local API transport failure has stable status/code identity, independent
+ * of message prose. */
+export function isDaemonTransportApiError(error) {
+    if (!(error instanceof ApiError))
+        return false;
+    return (error.status === 503 && (error.code === 'daemon_unavailable'
+        || error.code === 'transport_error'
+        || error.code === 'daemon_request_interrupted')) || (error.status === 504 && error.code === 'request_timeout')
+        || (error.status >= 500 && error.code === 'daemon_health_unavailable');
+}
 /** Type guard for an `ErrorBody`-shaped parsed payload. */
 export function isErrorBody(value) {
     if (typeof value !== 'object' || value === null)

package/dist/api/index.d.ts

@@ -1,4 +1,4 @@
-export { CrtrClient } from './client.js';
+export { CrtrClient, waitForDaemonAvailability } from './client.js';
 export type { CrtrClientOptions } from './client.js';
 export { ApiError, isErrorBody } from './errors.js';
 export type { ErrorBody } from './errors.js';

package/dist/api/index.js

@@ -1,7 +1,7 @@
 // `@north-light/crouter/api` — the single source of truth for crtrd's API DTOs,
 // route constants, error contract, and the typed `CrtrClient`. Dependency-light
 // by design (spec §3.1): Node built-ins + `src/api/*` only.
-export { CrtrClient } from './client.js';
+export { CrtrClient, waitForDaemonAvailability } from './client.js';
 export { ApiError, isErrorBody } from './errors.js';
 export { API_VERSION, routes } from './routes.js';
 export * from '../shared/generated-context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.303",
+  "version": "0.3.305",
   "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",