@north-light/api 0.3.434 → 0.3.436

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.js

@@ -313,7 +313,7 @@ export function apiErrorToCliError(err, next) {
         ? d
         : {
             error: STATUS_TO_CLI_CODE[err.status] ?? err.code,
-            message: violations.length > 0 ? `${err.message}: ${violations.join('; ')}` : err.message,
+            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).'

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.434",
+  "version": "0.3.436",
   "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",