@crouter/api 0.3.387 → 0.3.388

package/dist/daemon/manage.d.ts

@@ -0,0 +1,176 @@
+import { type HealthDTO, type StartupPhaseDTO } from '../api/index.js';
+/** Env keys that must NEVER reach the daemon process. Restarting crtrd is
+ *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
+ *  daemon stop && start`), which inherits that node's FULL env — its identity
+ *  (`CRTR_NODE_ID`/`CRTR_KIND`/…, the `nodeEnv()` shape in `core/runtime/
+ *  nodes.ts`), its front-door recursion-guard flag, and any pi-engine
+ *  resolution seam a prior test/dev session left exported. The daemon is a
+ *  singleton supervisor, never "a node" itself, so none of this belongs in its
+ *  env regardless of whether today's code happens to read it — and at least one
+ *  of these IS actively read: `host.ts`'s broker-engine resolution falls back to
+ *  `envBrokerEngine()`'s raw `CRTR_BROKER_ENGINE` read verbatim (nodeEnv() never
+ *  sets that key, so nothing overrides it per child launch), so a daemon that inherits a
+ *  stale/dev override throws inside `headlessBrokerHost.launch()` on EVERY
+ *  relaunch it ever attempts, for its whole lifetime — the 2026-07-06 diagnosis
+ *  root cause behind 19 nodes killed with "failed to relaunch and is now dead". */
+export declare const DAEMON_ENV_STRIP_KEYS: readonly string[];
+/** A copy of `process.env` with every `DAEMON_ENV_STRIP_KEYS` entry removed.
+ *  Deliberate global config the user actually wants the daemon to see —
+ *  `CRTR_HOME`, `CRTR_SUBTREE`, `CRTR_LOG`, `CRTR_DEBUG`, etc. — passes through
+ *  untouched; only the node-identity/engine-poisoning surface is stripped. */
+export declare function sanitizedDaemonEnv(): NodeJS.ProcessEnv;
+/** A crtrd declares its owning canvas in argv, so ownership is an exact match
+ *  on this process's canvas home. Untagged daemons retain their own
+ *  supervision and are never counted or killed here. */
+export declare function daemonCommandDeclaresCanvasHome(command: string, home: string): boolean;
+/** Every crtrd process on this host that declares ownership of this process's
+ *  canvas home, by pid. The `daemon/crtrd` argv segment distinguishes daemons
+ *  from brokers. `ps` is best-effort: failures return no matches, and the
+ *  current process is always excluded. */
+export declare function findDaemonPids(): number[];
+/** SIGTERM (then SIGKILL after a short grace) every crtrd daemon process EXCEPT
+ *  `keepPid`. This is the backstop the pidfile alone cannot provide: a daemon
+ *  that survived a prior stop (ignored SIGTERM, or released its ownership lock
+ *  without exiting) keeps running a supervise loop — reviving brokers and
+ *  contending for canvas state — while never appearing in the pidfile again, so
+ *  `stop`'s single recorded-pid signal can never reach it. Returns the pids it
+ *  reaped. Best-effort throughout: a pid that dies between enumeration and signal
+ *  just no-ops. */
+export declare function sweepStrayDaemons(keepPid: number | null): number[];
+/** Replace PID 1 with the selected daemon generation. Docker keeps a container
+ *  alive only while PID 1 lives, so a handover there must preserve its pid. */
+export declare function execDaemon(): Promise<never>;
+export interface SpawnDaemonOptions {
+    /** The phase that proves a daemon launched by this call is available. */
+    targetPhase?: 'ready' | 'prepared';
+}
+export interface SpawnDaemonResult {
+    /** True when a new daemon process was spawned. */
+    started: boolean;
+    /** PID of the newly spawned process, if started. */
+    pid?: number;
+    /** PID of the already-running daemon, if it was already up. */
+    existing_pid?: number;
+    /** Present only when a live pidfile owner does not answer `/healthz`. */
+    running?: true;
+    /** Present with `running:true` when the Unix API socket is not serving. */
+    serving?: false;
+    /** The final `/healthz` probe failure when a live owner misses readiness. */
+    probe_error?: string;
+    /** The observed phase when the daemon was available. */
+    startup_phase?: StartupPhaseDTO;
+}
+/** Make one `/healthz` observation without client-side recovery. The caller owns the availability window, so this probe cannot extend it. */
+export declare function probeDaemonHealth(timeoutMs?: number): Promise<HealthDTO>;
+export declare function probeErrorMessage(error: unknown): string;
+/** True only when one mandatory Unix API socket probe answers the existing ready health contract. */
+export declare function probeDaemonServing(timeoutMs?: number): Promise<void>;
+/** True only when one mandatory Unix API socket probe answers `/healthz`.
+ * A pidfile identifies an owner; it is never readiness. */
+export declare function isDaemonServing(): Promise<boolean>;
+export interface DaemonWaitDeps {
+    readPidfile?: () => number | null;
+    isPidAlive?: (pid: number) => boolean;
+    sleepMs?: (ms: number) => Promise<void> | void;
+    now?: () => number;
+}
+export interface DaemonStartupDeps extends DaemonWaitDeps {
+    childExited?: () => {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
+    /** What the exited child wrote to its error log, attached to the typed exit error. */
+    childStderrTail?: () => string;
+    isDaemonServing?: () => Promise<boolean>;
+    probeDaemonServing?: (timeoutMs: number) => Promise<void>;
+    probeDaemonHealth?: (timeoutMs: number) => Promise<HealthDTO>;
+}
+/** The spawned daemon process died before it ever became ready — a startup
+ *  failure, not a progressing migration (a live daemon never raises this).
+ *  `stderrTail` is what that run wrote to crtrd.err, so the CLI can say why. */
+export declare class DaemonExitedBeforeReadyError extends Error {
+    readonly stderrTail: string;
+    constructor(message: string, stderrTail: string);
+}
+/** A live daemon has bound its repair socket but cannot serve normal work
+ *  until its corpus migration succeeds. */
+export declare class DaemonStartupBlockedError extends Error {
+    constructor(pid: number, message: string);
+}
+/** A preparation request cannot succeed unless the live daemon explicitly reports prepared. */
+export declare class DaemonNotPreparedError extends Error {
+    constructor(pid: number, startupPhase: StartupPhaseDTO | undefined);
+}
+/** Tiny bounded post-spawn guard: wait for the daemon pidfile and live pid to
+ *  appear before reporting success. This catches the "started:true but not yet
+ *  plausibly alive" race without turning startup into a retry loop.
+ *
+ *  One deadline, owner-first polling. A signal or non-zero child exit fails
+ *  immediately. A clean code-0 exit is treated only as a possible ownership-
+ *  claim loser (never readiness on its own): polling continues on the SAME
+ *  deadline for a different live pidfile owner — the winner may publish its
+ *  pidfile deliberately late — and fails at that deadline if none appears. No
+ *  deadline extension and no retry spawn.
+ *
+ *  Returns null when the spawned pid owns the pidfile; returns a different live
+ *  daemon pid when startup lost the race to an already-running daemon. */
+export declare function verifyDaemonStartup(pid: number, timeoutMs?: number, deps?: DaemonStartupDeps, targetPhase?: 'ready' | 'prepared'): Promise<number | null>;
+/** Wait until a signaled daemon has exited and relinquished its pidfile. This
+ *  makes a following start safe to claim the singleton rather than racing its
+ *  previous owner. */
+export declare function waitForDaemonExit(pid: number, timeoutMs?: number, deps?: DaemonWaitDeps): Promise<void>;
+/** Stop the RECORDED daemon: SIGTERM, and if it does not exit within the wait
+ *  window, escalate to SIGKILL exactly as `sweepStrayDaemons` does for a stray.
+ *
+ *  The escalation is the point. Without it — SIGTERM, wait, throw on timeout,
+ *  never reaching the stray sweep — the one daemon `stop` is actually aimed at
+ *  would be the only crtrd process exempt from the SIGKILL backstop, and a
+ *  daemon whose shutdown hangs (or outruns the window) becomes permanently
+ *  unstoppable from the CLI: every retry re-sends a SIGTERM it is already
+ *  ignoring, and `start` keeps refusing as "already running".
+ *
+ *  A SIGKILL'd daemon runs no exit handler, so it leaves its pidfile behind
+ *  pointing at a dead pid. That is a stale record, not an owner: `readPidfile`
+ *  callers gate on `isPidAlive`, and the next `start` overwrites it. So this
+ *  waits on process death alone after a kill, never on pidfile release.
+ *
+ *  Returns how the daemon went down, for a truthful report. */
+export declare function stopDaemonProcess(pid: number, timeoutMs?: number, deps?: DaemonWaitDeps): Promise<'terminated' | 'killed'>;
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export declare function spawnDaemon(opts?: SpawnDaemonOptions): Promise<SpawnDaemonResult>;
+/** Whether autostart is suppressed for this invocation. `--no-autostart` or
+ *  `CRTR_NO_DAEMON_AUTOSTART=1` forces fail-loud on a cold socket (spec §7.1) —
+ *  for environments that manage crtrd externally and want the diagnostic, and
+ *  for test lanes, which point `CRTR_HOME` at a throwaway directory: an
+ *  autostarted daemon there is detached and resident, so it outlives both the
+ *  test process and the deleted temp home with nothing left to stop it.
+ *
+ *  This is the ONE gate. `ensureDaemon` below is the only path that spawns a
+ *  daemon implicitly, so the check belongs here rather than at each caller —
+ *  `cliClient()` reads it too, but the in-process spawn/recycle/promote callers
+ *  reach `ensureDaemon` without going through the CLI client at all. An
+ *  explicit `crtr sys daemon start` calls `spawnDaemon` directly and is
+ *  deliberately unaffected. */
+export declare function autostartDisabled(): boolean;
+/** Reset in-process spawn backoff after a daemon is observed alive. */
+export declare function resetDaemonAutostart(): void;
+export interface EnsureDaemonDeps {
+    isDaemonRunning?: () => boolean;
+    spawnDaemon?: () => Promise<SpawnDaemonResult>;
+    now?: () => number;
+}
+/** Why the daemon this process autostarted died before becoming ready, or
+ *  undefined while it is starting, running, or exited cleanly (a clean exit may
+ *  be a lost singleton race, so only a non-zero/signal exit counts). A client
+ *  waiting for that daemon polls this so a startup failure ends the wait now
+ *  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,
+ *  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). */
+export declare function ensureDaemon(deps?: EnsureDaemonDeps): void;