@north-light/api 0.3.435 → 0.3.437

package/dist/core/directory/join-lock.d.ts

@@ -0,0 +1,13 @@
+import { InputError } from '../io.js';
+export declare function joinLockPath(): string;
+/** The live process holding the lock, or null when no join is running (no lock, or a holder that died). */
+export declare function joinLockHolder(): number | null;
+/** Whether a join is in progress. The joiner starts its own daemon through `spawnDaemon`, never through the implicit paths that ask this. */
+export declare function joinInProgress(): boolean;
+export declare function joinInProgressError(pid: number | null): InputError;
+/** Resolve once no other live process holds the join lock, or after `timeoutMs`. For a start that must happen
+ *  but must read the settings a join is about to commit (a daemon handover's successor): it waits the join out
+ *  instead of bypassing the lock, so nothing but the join starts a daemon while the lock is held. */
+export declare function awaitJoinLockRelease(timeoutMs: number, pollMs?: number): Promise<void>;
+/** Run `operation` holding the join lock. Throws `join_in_progress` when a live process holds it. */
+export declare function withJoinLock<T>(operation: () => Promise<T>): Promise<T>;

package/dist/core/directory/join-lock.js

@@ -0,0 +1,61 @@
+// The "join in progress" lock. `crtr sys join` stops the daemon, rewrites local
+// identity, and starts the daemon again. Stopping the daemon kills every broker,
+// so every open viewer sees a cold socket and its client would autostart a new
+// daemon within seconds, which makes the join refuse (`daemon_running`). While
+// this lock is held by a live process, `ensureDaemon` and `spawnDaemon` (so also
+// `sys daemon start` and a handover successor) decline to start a daemon.
+//
+// It is the shared token-checked directory lock (`core/exclusive-lock.ts`): the
+// holder's pid is in its marker's name, a dead holder is reclaimed by exactly the
+// marker it observed (so a lagging reclaimer can never strip a live successor),
+// and only the holder's own marker releases it. PURITY: Node built-ins, path
+// builders and the pid probe only, so `daemon/manage.ts` can import it.
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../canvas/paths.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { exclusiveLockOwnerPid, withExclusiveDirectoryLockAsync } from '../exclusive-lock.js';
+import { InputError } from '../io.js';
+/** How long a second joiner waits for the first before it refuses. Long enough to reclaim a dead holder's lock. */
+const ACQUIRE_WAIT_MS = 1_000;
+export function joinLockPath() {
+    return join(crtrHome(), 'join.lock');
+}
+/** The live process holding the lock, or null when no join is running (no lock, or a holder that died). */
+export function joinLockHolder() {
+    const pid = exclusiveLockOwnerPid(joinLockPath());
+    return pid !== null && isPidAlive(pid) ? pid : null;
+}
+/** Whether a join is in progress. The joiner starts its own daemon through `spawnDaemon`, never through the implicit paths that ask this. */
+export function joinInProgress() {
+    return joinLockHolder() !== null;
+}
+export function joinInProgressError(pid) {
+    return new InputError({
+        error: 'join_in_progress',
+        message: pid === null
+            ? '`crtr sys join` is running and holds the daemon down until it finishes'
+            : `\`crtr sys join\` (pid ${pid}) is running and holds the daemon down until it finishes`,
+        next: 'Wait for the join to finish; it starts the daemon again itself. If it is stuck, `crtr sys daemon start --force`.',
+    });
+}
+/** Resolve once no other live process holds the join lock, or after `timeoutMs`. For a start that must happen
+ *  but must read the settings a join is about to commit (a daemon handover's successor): it waits the join out
+ *  instead of bypassing the lock, so nothing but the join starts a daemon while the lock is held. */
+export async function awaitJoinLockRelease(timeoutMs, pollMs = 100) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const holder = joinLockHolder();
+        if (holder === null || holder === process.pid || Date.now() >= deadline)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}
+/** Run `operation` holding the join lock. Throws `join_in_progress` when a live process holds it. */
+export async function withJoinLock(operation) {
+    mkdirSync(crtrHome(), { recursive: true });
+    return withExclusiveDirectoryLockAsync(joinLockPath(), operation, {
+        timeoutMs: ACQUIRE_WAIT_MS,
+        timeoutError: () => joinInProgressError(joinLockHolder()),
+    });
+}

package/dist/core/io.d.ts

@@ -57,6 +57,8 @@ interface ErrorPayloadBase {
      *  of `received` on purpose: `received` names the caller's offending VALUE, and
      *  reporting an HTTP status there is a false claim about what was sent. */
     http_status?: number;
+    /** Seconds the provider asked the caller to wait before retrying (a rate limit). */
+    retry_after_s?: number;
     next: string;
 }
 export type ErrorPayload = ErrorPayloadBase & ({
@@ -109,7 +111,12 @@ export declare function diag(message: string): void;
  *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
  *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
  *      it before the re-plumb, preserving its SPECIFIC code + next.
- *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   3. A provider-origin refusal (`err.origin === 'provider'`) carries the
+ *      provider's own error in `details` (`{code,message,field?,next?,received?}`)
+ *      under the daemon's coarse `provider_*` code and the provider's HTTP
+ *      status. The provider's code, `next`, `field` and `Retry-After` reach the
+ *      caller unchanged; the status→code map would flatten them to `conflict`.
+ *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
 export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
 /** Terminal error handler. Command-level failures (bad input, not-found,

package/dist/core/io.js

@@ -209,6 +209,7 @@ function payloadOf(e) {
         received: d.received,
         field: d.field,
         ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
+        ...(typeof d.retry_after_s === 'number' ? { retry_after_s: d.retry_after_s } : {}),
     };
     return result === undefined
         ? { ...base, next }
@@ -274,7 +275,12 @@ const STATUS_TO_CLI_CODE = {
  *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
  *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
  *      it before the re-plumb, preserving its SPECIFIC code + next.
- *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   3. A provider-origin refusal (`err.origin === 'provider'`) carries the
+ *      provider's own error in `details` (`{code,message,field?,next?,received?}`)
+ *      under the daemon's coarse `provider_*` code and the provider's HTTP
+ *      status. The provider's code, `next`, `field` and `Retry-After` reach the
+ *      caller unchanged; the status→code map would flatten them to `conflict`.
+ *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
 export function apiErrorToCliError(err, next) {
     // A handover is NOT a down daemon: the successor is already up (the client
@@ -297,12 +303,23 @@ export function apiErrorToCliError(err, next) {
     }
     // A responding daemon can relay an unavailable provider or storage service.
     // HTTP 503 alone does not mean that crtrd is down.
+    const d = err.details;
+    const provider = providerSupplied(err, d);
     if (err.status === 503) {
-        return new CrtrError(err.code, err.message, ExitCode.NETWORK, {
-            next: next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
-        });
+        const code = provider.code ?? err.code;
+        const details = {
+            next: provider.next ?? next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
+        };
+        if (provider.code !== undefined) {
+            if (provider.field !== undefined)
+                details['field'] = provider.field;
+            if (provider.received !== undefined)
+                details['received'] = provider.received;
+            if (provider.retryAfterS !== undefined)
+                details['retry_after_s'] = provider.retryAfterS;
+        }
+        return new CrtrError(code, err.message, ExitCode.NETWORK, details);
     }
-    const d = err.details;
     // A `/v1` request validator reports each bad field in `details.violations`;
     // the message alone only says the request was invalid.
     const violations = Array.isArray(d?.violations)
@@ -312,14 +329,20 @@ export function apiErrorToCliError(err, next) {
     const payload = d && typeof d.error === 'string' && typeof d.message === 'string' && typeof d.next === 'string'
         ? d
         : {
-            error: STATUS_TO_CLI_CODE[err.status] ?? err.code,
+            error: provider.code ?? STATUS_TO_CLI_CODE[err.status] ?? err.code,
+            ...(provider.field !== undefined ? { field: provider.field } : {}),
+            ...(provider.received !== undefined ? { received: provider.received } : {}),
+            ...(provider.retryAfterS !== undefined ? { retry_after_s: provider.retryAfterS } : {}),
             message: violations.length > 0 ? `${err.message}: ${violations.join('; ')}` : err.message.trim() !== '' ? err.message : `request refused (HTTP ${err.status}, ${err.code}) with no message`,
-            next: next ??
-                (err.status >= 500
-                    ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
-                    : err.status === 404
-                        ? 'List nodes with `crtr node inspect list`.'
-                        : 'Inspect the error and adjust the call. See -h for the schema.'),
+            next: provider.next ??
+                next ??
+                (provider.retryAfterS !== undefined
+                    ? `Wait ${provider.retryAfterS}s, then retry; do not retry sooner.`
+                    : err.status >= 500
+                        ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
+                        : err.status === 404
+                            ? 'List nodes with `crtr node inspect list`.'
+                            : 'Inspect the error and adjust the call. See -h for the schema.'),
         };
     // Preserve the exit-code class the server leaf carried instead of collapsing
     // every non-503 to USAGE(2): a not-found (404 / `not_found`) surfaces exit 3
@@ -327,6 +350,33 @@ export function apiErrorToCliError(err, next) {
     // (memory/pkg/sys) still emit so the taxonomy stays uniform across the CLI.
     return new InputError(payload, exitForCliCode(payload.error, err.status));
 }
+/** What a provider put in its own error body, as the daemon relays it: the
+ *  provider's code (`details.code`; the envelope `code` is only the daemon's
+ *  coarse `provider_*` bucket), plus `next`, `field`, `received`, and the
+ *  `Retry-After` the daemon lifts into the envelope. Empty for any error that
+ *  did not originate at a provider, so non-provider status→code mapping is
+ *  untouched. A code that is not a snake_case identifier, or that came with no
+ *  provider HTTP status, is ignored. */
+function providerSupplied(err, d) {
+    if (err.origin !== 'provider' || d === undefined || d === null || typeof d !== 'object')
+        return {};
+    const out = {};
+    // `details.status` is the provider's own HTTP status; the runtime's transport
+    // diagnostics (`{status: null, code: 'timeout'}`) are not a provider's code.
+    if (typeof d.status === 'number' && typeof d.code === 'string' && /^[a-z][a-z0-9_]*$/.test(d.code))
+        out.code = d.code;
+    if (typeof d.next === 'string' && d.next.trim() !== '')
+        out.next = d.next;
+    if (typeof d.field === 'string' && d.field !== '')
+        out.field = d.field;
+    else if (err.param !== undefined)
+        out.field = err.param;
+    if (d.received !== undefined && d.received !== null)
+        out.received = d.received;
+    if (typeof err.retryAfterS === 'number')
+        out.retryAfterS = err.retryAfterS;
+    return out;
+}
 /** The `ExitCode` class a reconstructed API error should carry, keyed off the
  *  round-tripped CLI code (and the 404 status as the not-found signal — the
  *  server maps NOT_FOUND's exit class to status 404, but folds AMBIGUOUS and

package/dist/core/render.js

@@ -129,6 +129,8 @@ export function renderError(p) {
     // the value the caller supplied.
     if (p.http_status !== undefined)
         lines.push(`http status: ${p.http_status}`);
+    if (p.retry_after_s !== undefined)
+        lines.push(`retry after: ${p.retry_after_s}s`);
     if ('primaryCompleted' in p && p.primaryCompleted === true) {
         lines.push('primaryCompleted: true');
         lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);

package/dist/daemon/manage.d.ts

@@ -43,6 +43,10 @@ export declare function execDaemon(): Promise<never>;
 export interface SpawnDaemonOptions {
     /** The phase that proves a daemon launched by this call is available. */
     targetPhase?: 'ready' | 'prepared';
+    /** Start even while another process's `crtr sys join` holds the daemon down. */
+    ignoreJoinLock?: boolean;
+    /** While another process's `crtr sys join` holds the daemon down, wait for it to finish, then start. For a handover successor. */
+    waitForJoinLock?: boolean;
 }
 export interface SpawnDaemonResult {
     /** True when a new daemon process was spawned. */
@@ -136,6 +140,14 @@ export declare function waitForDaemonExit(pid: number, timeoutMs?: number, deps?
  *
  *  Returns how the daemon went down, for a truthful report. */
 export declare function stopDaemonProcess(pid: number, timeoutMs?: number, deps?: DaemonWaitDeps): Promise<'terminated' | 'killed'>;
+/** Stop the recorded daemon and sweep every stray crtrd of this canvas home.
+ *  Resolves once none remains. Shared by `crtr sys daemon stop` and `crtr sys join`. */
+export declare function stopAllDaemons(): Promise<{
+    stopped: boolean;
+    pid?: number;
+    strays_killed: number[];
+    force_killed: boolean;
+}>;
 /** Spawn crtrd detached. Returns immediately; the child outlives this process.
  *
  *  If the daemon is already running, returns {started:false, existing_pid}.
@@ -169,7 +181,8 @@ export interface EnsureDaemonDeps {
  *  rather than at the end of the startup window. */
 export declare function daemonAutostartStartupFailure(): string | undefined;
 /** Start the daemon if it is not already running. No-op if already up, if
- *  autostart is suppressed for this invocation, while an attempt is in flight,
+ *  autostart is suppressed for this invocation, while `crtr sys join` holds
+ *  the join lock (see core/directory/join-lock.ts), while an attempt is in flight,
  *  or while backing off from a recent failure.
  *  Silently swallows spawn errors (the canvas still works without the daemon;
  *  nodes just won't be auto-revived). */

package/dist/daemon/manage.js

@@ -19,6 +19,7 @@ import { DAEMON_STARTUP_WINDOW_MS } from './startup-policy.js';
 import { exclusiveLockOwnerPid } from '../core/exclusive-lock.js';
 import { onDiskMigrationLockPath } from '../core/canvas/paths.js';
 import { envNoDaemonAutostart } from '../shared/env.js';
+import { awaitJoinLockRelease, joinInProgress, joinInProgressError, joinLockHolder } from '../core/directory/join-lock.js';
 import { waitForDaemonAvailability } from '../api/index.js';
 import { localClient } from '../api/node-transport.js';
 // Daemon env sanitization
@@ -194,6 +195,8 @@ export async function execDaemon() {
     const launchArgs = await resolveDaemonLaunch();
     return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
 }
+/** How long a handover successor waits for a running join: a registration call (30 s) plus the join's own stop and start. */
+const JOIN_WAIT_WINDOW_MS = 3 * 60_000;
 // Shutdown stays short even though startup may include corpus migration.
 const DAEMON_SHUTDOWN_WINDOW_MS = 20_000;
 const DAEMON_VERIFY_POLL_MS = 10;
@@ -415,6 +418,16 @@ export async function stopDaemonProcess(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_
     }
     throw new Error(`daemon ${pid} survived both SIGTERM and SIGKILL`);
 }
+/** Stop the recorded daemon and sweep every stray crtrd of this canvas home.
+ *  Resolves once none remains. Shared by `crtr sys daemon stop` and `crtr sys join`. */
+export async function stopAllDaemons() {
+    const pid = readPidfile();
+    const recorded = pid !== null && isPidAlive(pid);
+    const forceKilled = recorded && (await stopDaemonProcess(pid)) === 'killed';
+    // The recorded daemon is gone, so keepPid=null sweeps every remaining crtrd of this home.
+    const strays = sweepStrayDaemons(null);
+    return { stopped: recorded || strays.length > 0, ...(recorded ? { pid } : {}), strays_killed: strays, force_killed: forceKilled };
+}
 /** The last `maxBytes` of a log from byte `start` onward, trimmed; '' when it
  *  cannot be read. Bounded so a runaway log can never flood an error message. */
 function readLogTailFrom(path, start, maxBytes = 2_048) {
@@ -496,6 +509,13 @@ export async function spawnDaemon(opts = {}) {
     // is launchd-owned, the plist's ProgramArguments must point at the branded
     // binary too — this path only covers a manual `crtr sys daemon start`.
     const launchArgs = await resolveDaemonLaunch();
+    // The one spawn point every start reaches (autostart, `sys daemon start`, a handover successor): an
+    // autostart begun before a join took its lock lands here after it, and must not start a daemon.
+    if (opts.waitForJoinLock === true)
+        await awaitJoinLockRelease(JOIN_WAIT_WINDOW_MS);
+    const joiner = joinLockHolder();
+    if (joiner !== null && joiner !== process.pid && opts.ignoreJoinLock !== true)
+        throw joinInProgressError(joiner);
     // Route stdout+stderr to an append-mode file instead of discarding them
     // (stdio:'ignore'). This fd is RAW RESIDUE only — third-party/runtime
     // output the daemon doesn't control, plus the narrow set of authorized raw
@@ -624,7 +644,8 @@ export function daemonAutostartStartupFailure() {
     return autostartStartupFailure;
 }
 /** Start the daemon if it is not already running. No-op if already up, if
- *  autostart is suppressed for this invocation, while an attempt is in flight,
+ *  autostart is suppressed for this invocation, while `crtr sys join` holds
+ *  the join lock (see core/directory/join-lock.ts), while an attempt is in flight,
  *  or while backing off from a recent failure.
  *  Silently swallows spawn errors (the canvas still works without the daemon;
  *  nodes just won't be auto-revived). */
@@ -634,6 +655,9 @@ export function ensureDaemon(deps = {}) {
     const now = deps.now ?? Date.now;
     if (autostartDisabled())
         return;
+    // `crtr sys join` holds the daemon down on purpose; a viewer's redial must not bring it back.
+    if (joinInProgress())
+        return;
     if (autostartInFlight)
         return;
     if (now() < autostartNextAttemptAt)

package/package.json

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