@spinabot/brigade 0.1.2 → 1.0.0

package/dist/core/gateway-probe.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Gateway probe helpers — small utilities for `brigade status`, `brigade doctor`,
+ * and `brigade gateway status|stop` to find out whether the gateway is up and,
+ * if so, where its process lives so we can ask it to shut down.
+ *
+ * Two facets here:
+ *
+ *   1. **WS probe** (`probeGateway`): connect to ws://host:port, wait for
+ *      the server's automatic `state` event on connect, return a friendly
+ *      snapshot. Uses Brigade's state-on-connect event instead of an RPC
+ *      method.
+ *
+ *   2. **PID file** (`readPidFile`, `writePidFile`, `clearPidFile`): the
+ *      gateway writes `~/.brigade/gateway.pid` on boot and unlinks it on
+ *      clean shutdown. `brigade gateway stop` reads that file, sends SIGTERM,
+ *      and waits for the file to disappear (or times out). Brigade v1 has no
+ *      service installer, so no OS-service-manager + netstat-pid-discovery
+ *      stack is needed — this PID-file flow is the entire mechanism.
+ */
+import type { SessionStateSnapshot } from "../protocol.js";
+export declare const GATEWAY_PID_PATH: string;
+/**
+ * Out-of-process supervisor heartbeat. The gateway writes the file every
+ * tick (atomic via write-tempfile + rename) and an external supervisor
+ * (`brigade supervisor`) reads its mtime to detect a wedged process — one
+ * where the OS thinks the gateway is alive (PID file still present) but
+ * the Node event loop is starved or deadlocked and can't update the file.
+ *
+ * The PID file proves the process EXISTS; the heartbeat proves it's
+ * ALIVE and SERVICING. Both together let an external watcher distinguish
+ * "crashed clean" from "hung process".
+ */
+export declare const GATEWAY_HEARTBEAT_PATH: string;
+/**
+ * Maximum age (ms) the heartbeat file can have before the supervisor
+ * considers the gateway wedged. Default 90s gives the gateway up to two
+ * missed tick intervals (TICK_INTERVAL_MS is 30s) before triggering a
+ * restart — generous enough to absorb GC pauses + disk hiccups, tight
+ * enough to recover within ~1.5 min of a real hang.
+ */
+export declare const GATEWAY_HEARTBEAT_STALE_MS = 90000;
+/** Payload shape written to GATEWAY_HEARTBEAT_PATH on every tick. */
+export interface GatewayHeartbeat {
+    /** Epoch ms when the gateway last wrote the file. */
+    ts: number;
+    /** Gateway's process PID; cross-check against gateway.pid. */
+    pid: number;
+    /** Process uptime in ms (process.uptime() * 1000) when written. */
+    uptimeMs: number;
+}
+/**
+ * Atomically write the heartbeat file. Tempfile + rename so a partial
+ * write on a crashed process can never leave a half-parsed file behind.
+ */
+export declare function writeHeartbeatFile(): Promise<void>;
+/**
+ * Synchronously read the heartbeat file. Returns `undefined` when missing
+ * or unparseable — callers (supervisor + doctor) treat both as "no heartbeat".
+ * `pathOverride` is for tests; production callers leave it omitted so the
+ * canonical `~/.brigade/gateway.heartbeat` is consulted.
+ */
+/** Mode-aware heartbeat read — convex consults the gatewayCoord row,
+ *  filesystem reads the file. `pathOverride` (tests) forces the file. */
+export declare function readHeartbeat(pathOverride?: string): Promise<GatewayHeartbeat | undefined>;
+export declare function readHeartbeatFile(pathOverride?: string): GatewayHeartbeat | undefined;
+/** Delete the heartbeat file. Called on graceful shutdown. */
+export declare function clearHeartbeatFile(): Promise<void>;
+/**
+ * Categorised reason a probe failed — callers (status, doctor, error
+ * formatters) can surface specific recovery hints instead of dumping a
+ * raw error string.
+ */
+export type GatewayProbeFailureKind = 
+/** Connection refused — nothing listening on host:port. */
+"refused"
+/** TCP/WS handshake didn't complete in time. */
+ | "timeout"
+/** Hostname couldn't be resolved (bad --host). */
+ | "dns"
+/** Server replied to the upgrade with a 4xx/5xx (auth or routing failure). */
+ | "auth"
+/** TLS / certificate errors. */
+ | "tls"
+/** Network unreachable / route missing. */
+ | "network"
+/** Anything else — the message field carries the raw text. */
+ | "other";
+export interface GatewayProbeResult {
+    reachable: boolean;
+    url: string;
+    /** Initial state snapshot from the server (only set when reachable). */
+    state?: SessionStateSnapshot;
+    /** Human-readable error when unreachable. */
+    error?: string;
+    /** Categorised failure reason, set when `reachable === false`. */
+    errorKind?: GatewayProbeFailureKind;
+    /** Round-trip ms from connect-attempt to first frame, when reachable. */
+    rttMs?: number;
+}
+/**
+ * Best-effort categorisation of an Error/string into a probe-failure kind.
+ * The match list reflects the actual messages Node + `ws` produce on each
+ * platform — verified against the real failure modes that surface in
+ * `brigade gateway status`.
+ */
+export declare function classifyProbeFailure(err: unknown): GatewayProbeFailureKind;
+export interface GatewayProbeOptions {
+    host?: string;
+    port?: number;
+    /** Total wallclock budget. Default 1500ms — enough for a local boot, fast enough to keep `brigade status` snappy. */
+    timeoutMs?: number;
+}
+/**
+ * Open a WebSocket to the gateway and read its state-on-connect frame.
+ * Resolves whether the gateway is up; never throws on connection refused
+ * (returns `{ reachable: false, error }`). Throws only on programmer errors.
+ */
+export declare function probeGateway(opts?: GatewayProbeOptions): Promise<GatewayProbeResult>;
+/**
+ * Write the current process's PID to `~/.brigade/gateway.pid`. Called by
+ * the gateway on boot. The directory is assumed to exist (the brigade dir
+ * is created by `loadBrigadeConfig` on first read).
+ */
+export declare function writePidFile(): Promise<void>;
+/**
+ * Remove the PID file. Called by the gateway on clean shutdown so the
+ * next `brigade gateway status` doesn't report a dead PID. Silent on
+ * missing file.
+ */
+export declare function clearPidFile(): Promise<void>;
+/**
+ * Read the PID file. Returns `undefined` when the file is missing or
+ * unparseable — callers fall back to "no gateway running" without
+ * surfacing an error. `pathOverride` is for tests; production leaves it
+ * omitted so the canonical `~/.brigade/gateway.pid` is consulted.
+ */
+export declare function readPidFile(pathOverride?: string): number | undefined;
+/** Mode-aware pid read — convex consults the gatewayCoord row, filesystem
+ *  reads the file. `pathOverride` (tests) forces the file. */
+export declare function readPid(pathOverride?: string): Promise<number | undefined>;
+/**
+ * Best-effort check whether `pid` is alive. Sends signal 0, which Node uses
+ * for liveness probes (no actual signal delivered). On success the process
+ * is alive; ESRCH means it's dead. EPERM (signal allowed but caller can't
+ * deliver) still means the process exists, so we treat that as alive.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+//# sourceMappingURL=gateway-probe.d.ts.map

package/dist/core/gateway-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-probe.d.ts","sourceRoot":"","sources":["../../src/core/gateway-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,eAAO,MAAM,gBAAgB,QAAwC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,QAA8C,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAwBxD;AAED;;;;;GAKG;AACH;yEACyE;AACzE,wBAAsB,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAYhG;AAED,wBAAgB,iBAAiB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAkBrF;AAED,8DAA8D;AAC9D,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAoBxD;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB;AACjC,2DAA2D;AACzD,SAAS;AACX,gDAAgD;GAC9C,SAAS;AACX,kDAAkD;GAChD,KAAK;AACP,8EAA8E;GAC5E,MAAM;AACR,gCAAgC;GAC9B,KAAK;AACP,2CAA2C;GACzC,SAAS;AACX,8DAA8D;GAC5D,OAAO,CAAC;AAEZ,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,uBAAuB,CAa1E;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qHAAqH;IACrH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkD9F;AAED;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAclD;AAED;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAoBlD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQrE;AAED;8DAC8D;AAC9D,wBAAsB,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAYhF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD"}

package/dist/core/gateway-probe.js

@@ -0,0 +1,319 @@
+/**
+ * Gateway probe helpers — small utilities for `brigade status`, `brigade doctor`,
+ * and `brigade gateway status|stop` to find out whether the gateway is up and,
+ * if so, where its process lives so we can ask it to shut down.
+ *
+ * Two facets here:
+ *
+ *   1. **WS probe** (`probeGateway`): connect to ws://host:port, wait for
+ *      the server's automatic `state` event on connect, return a friendly
+ *      snapshot. Uses Brigade's state-on-connect event instead of an RPC
+ *      method.
+ *
+ *   2. **PID file** (`readPidFile`, `writePidFile`, `clearPidFile`): the
+ *      gateway writes `~/.brigade/gateway.pid` on boot and unlinks it on
+ *      clean shutdown. `brigade gateway stop` reads that file, sends SIGTERM,
+ *      and waits for the file to disappear (or times out). Brigade v1 has no
+ *      service installer, so no OS-service-manager + netstat-pid-discovery
+ *      stack is needed — this PID-file flow is the entire mechanism.
+ */
+import * as fs from "node:fs";
+import * as fsAsync from "node:fs/promises";
+import * as path from "node:path";
+import { WebSocket } from "ws";
+import { BRIGADE_DIR } from "./config.js";
+import { tryGetRuntimeContext } from "../storage/runtime-context.js";
+export const GATEWAY_PID_PATH = path.join(BRIGADE_DIR, "gateway.pid");
+/**
+ * Out-of-process supervisor heartbeat. The gateway writes the file every
+ * tick (atomic via write-tempfile + rename) and an external supervisor
+ * (`brigade supervisor`) reads its mtime to detect a wedged process — one
+ * where the OS thinks the gateway is alive (PID file still present) but
+ * the Node event loop is starved or deadlocked and can't update the file.
+ *
+ * The PID file proves the process EXISTS; the heartbeat proves it's
+ * ALIVE and SERVICING. Both together let an external watcher distinguish
+ * "crashed clean" from "hung process".
+ */
+export const GATEWAY_HEARTBEAT_PATH = path.join(BRIGADE_DIR, "gateway.heartbeat");
+/**
+ * Maximum age (ms) the heartbeat file can have before the supervisor
+ * considers the gateway wedged. Default 90s gives the gateway up to two
+ * missed tick intervals (TICK_INTERVAL_MS is 30s) before triggering a
+ * restart — generous enough to absorb GC pauses + disk hiccups, tight
+ * enough to recover within ~1.5 min of a real hang.
+ */
+export const GATEWAY_HEARTBEAT_STALE_MS = 90_000;
+/**
+ * Atomically write the heartbeat file. Tempfile + rename so a partial
+ * write on a crashed process can never leave a half-parsed file behind.
+ */
+export async function writeHeartbeatFile() {
+    const payload = {
+        ts: Date.now(),
+        pid: process.pid,
+        uptimeMs: Math.round(process.uptime() * 1000),
+    };
+    // Convex mode — the heartbeat is a gatewayCoord row, never a file.
+    // (The supervisor + doctor read it back through the same store.)
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        try {
+            await rctx.store.instance.writeHeartbeat(payload);
+        }
+        catch {
+            // Heartbeat write failures degrade to "stale heartbeat" on the
+            // supervisor side — same posture as a failed file write.
+        }
+        return;
+    }
+    await fsAsync.mkdir(path.dirname(GATEWAY_HEARTBEAT_PATH), { recursive: true });
+    const tmp = `${GATEWAY_HEARTBEAT_PATH}.tmp`;
+    await fsAsync.writeFile(tmp, JSON.stringify(payload), "utf8");
+    await fsAsync.rename(tmp, GATEWAY_HEARTBEAT_PATH);
+}
+/**
+ * Synchronously read the heartbeat file. Returns `undefined` when missing
+ * or unparseable — callers (supervisor + doctor) treat both as "no heartbeat".
+ * `pathOverride` is for tests; production callers leave it omitted so the
+ * canonical `~/.brigade/gateway.heartbeat` is consulted.
+ */
+/** Mode-aware heartbeat read — convex consults the gatewayCoord row,
+ *  filesystem reads the file. `pathOverride` (tests) forces the file. */
+export async function readHeartbeat(pathOverride) {
+    if (pathOverride === undefined) {
+        const rctx = tryGetRuntimeContext();
+        if (rctx?.mode === "convex") {
+            try {
+                return (await rctx.store.instance.readHeartbeat());
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return readHeartbeatFile(pathOverride);
+}
+export function readHeartbeatFile(pathOverride) {
+    try {
+        const raw = fs.readFileSync(pathOverride ?? GATEWAY_HEARTBEAT_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.ts === "number" &&
+            typeof parsed.pid === "number" &&
+            typeof parsed.uptimeMs === "number" &&
+            Number.isFinite(parsed.ts) &&
+            Number.isFinite(parsed.pid) &&
+            Number.isFinite(parsed.uptimeMs)) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Delete the heartbeat file. Called on graceful shutdown. */
+export async function clearHeartbeatFile() {
+    // Convex mode — clear the gatewayCoord row's heartbeat columns so the next
+    // status/supervise probe doesn't see a stale beat from a stopped gateway.
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        try {
+            await rctx.store.instance.clearHeartbeat();
+        }
+        catch {
+            // Best-effort; a stale heartbeat ages out of the freshness window.
+        }
+        return;
+    }
+    try {
+        await fsAsync.unlink(GATEWAY_HEARTBEAT_PATH);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+/**
+ * Best-effort categorisation of an Error/string into a probe-failure kind.
+ * The match list reflects the actual messages Node + `ws` produce on each
+ * platform — verified against the real failure modes that surface in
+ * `brigade gateway status`.
+ */
+export function classifyProbeFailure(err) {
+    const msg = (err instanceof Error ? err.message : String(err ?? "")).toLowerCase();
+    // Order matters: more-specific patterns first so e.g. "ENOTFOUND … timeout"
+    // doesn't classify as a generic timeout.
+    if (msg.includes("econnrefused"))
+        return "refused";
+    if (msg.includes("enotfound") || msg.includes("eai_again") || msg.includes("getaddrinfo"))
+        return "dns";
+    if (msg.includes("ehostunreach") || msg.includes("enetunreach"))
+        return "network";
+    if (msg.includes("certificate") || msg.includes("self signed") || msg.includes("ssl") || msg.includes("tls")) {
+        return "tls";
+    }
+    if (msg.includes("unexpected server response"))
+        return "auth";
+    if (msg.includes("timed out") || msg.includes("etimedout") || msg.includes("handshake"))
+        return "timeout";
+    return "other";
+}
+const DEFAULT_TIMEOUT_MS = 1500;
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 7777;
+/**
+ * Open a WebSocket to the gateway and read its state-on-connect frame.
+ * Resolves whether the gateway is up; never throws on connection refused
+ * (returns `{ reachable: false, error }`). Throws only on programmer errors.
+ */
+export async function probeGateway(opts = {}) {
+    const host = opts.host ?? DEFAULT_HOST;
+    const port = opts.port ?? DEFAULT_PORT;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const url = `ws://${host}:${port}`;
+    const start = Date.now();
+    return await new Promise((resolve) => {
+        let settled = false;
+        const ws = new WebSocket(url, { handshakeTimeout: timeoutMs });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                ws.removeAllListeners();
+                ws.close();
+            }
+            catch {
+                // Best-effort; the listener cleanup runs anyway.
+            }
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ reachable: false, url, error: `timed out after ${timeoutMs}ms`, errorKind: "timeout" });
+        }, timeoutMs);
+        ws.on("error", (err) => {
+            clearTimeout(timer);
+            finish({ reachable: false, url, error: err.message, errorKind: classifyProbeFailure(err) });
+        });
+        ws.on("message", (data) => {
+            // Server pushes a state event on connect (server.ts broadcast). Read
+            // that, return, and close. We don't validate frame schema strictly —
+            // any structured message proves the WS handshake completed and the
+            // server responded.
+            clearTimeout(timer);
+            try {
+                const parsed = JSON.parse(typeof data === "string" ? data : data.toString());
+                if (parsed?.type === "event" && parsed?.event === "state" && parsed?.payload) {
+                    finish({
+                        reachable: true,
+                        url,
+                        state: parsed.payload,
+                        rttMs: Date.now() - start,
+                    });
+                    return;
+                }
+            }
+            catch {
+                // Non-JSON frame — still treat as reachable since the WS is up.
+            }
+            finish({ reachable: true, url, rttMs: Date.now() - start });
+        });
+    });
+}
+/**
+ * Write the current process's PID to `~/.brigade/gateway.pid`. Called by
+ * the gateway on boot. The directory is assumed to exist (the brigade dir
+ * is created by `loadBrigadeConfig` on first read).
+ */
+export async function writePidFile() {
+    // Convex mode — the pid is a gatewayCoord row, never a file.
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        try {
+            await rctx.store.instance.writePid(process.pid);
+        }
+        catch {
+            // Degrades to "no pid visible" — same posture as a failed file write.
+        }
+        return;
+    }
+    await fsAsync.mkdir(path.dirname(GATEWAY_PID_PATH), { recursive: true });
+    await fsAsync.writeFile(GATEWAY_PID_PATH, String(process.pid), "utf8");
+}
+/**
+ * Remove the PID file. Called by the gateway on clean shutdown so the
+ * next `brigade gateway status` doesn't report a dead PID. Silent on
+ * missing file.
+ */
+export async function clearPidFile() {
+    // Convex mode — clear the gatewayCoord row's pid so the next
+    // `brigade gateway status` doesn't report a dead PID as running.
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        try {
+            await rctx.store.instance.clearPid();
+        }
+        catch {
+            // Best-effort; a stale pid is reconciled by the next liveness probe.
+        }
+        return;
+    }
+    try {
+        await fsAsync.unlink(GATEWAY_PID_PATH);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+/**
+ * Read the PID file. Returns `undefined` when the file is missing or
+ * unparseable — callers fall back to "no gateway running" without
+ * surfacing an error. `pathOverride` is for tests; production leaves it
+ * omitted so the canonical `~/.brigade/gateway.pid` is consulted.
+ */
+export function readPidFile(pathOverride) {
+    try {
+        const raw = fs.readFileSync(pathOverride ?? GATEWAY_PID_PATH, "utf8").trim();
+        const pid = Number(raw);
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Mode-aware pid read — convex consults the gatewayCoord row, filesystem
+ *  reads the file. `pathOverride` (tests) forces the file. */
+export async function readPid(pathOverride) {
+    if (pathOverride === undefined) {
+        const rctx = tryGetRuntimeContext();
+        if (rctx?.mode === "convex") {
+            try {
+                return await rctx.store.instance.readPid();
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return readPidFile(pathOverride);
+}
+/**
+ * Best-effort check whether `pid` is alive. Sends signal 0, which Node uses
+ * for liveness probes (no actual signal delivered). On success the process
+ * is alive; ESRCH means it's dead. EPERM (signal allowed but caller can't
+ * deliver) still means the process exists, so we treat that as alive.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+//# sourceMappingURL=gateway-probe.js.map

package/dist/core/gateway-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-probe.js","sourceRoot":"","sources":["../../src/core/gateway-probe.ts"],"names":[],"mappings":"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"}

package/dist/core/gateway-spawn.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Gateway auto-spawn — ensure a Brigade gateway daemon is running, starting a
+ * detached one if not.
+ *
+ * `brigade chat` is a thin WebSocket client to the gateway (the single
+ * per-turn runtime). When the user runs `brigade chat` and no gateway is up,
+ * we spawn one as a DETACHED background process so it survives the chat
+ * session — later `brigade chat` / `brigade connect` reattach to the same
+ * daemon instantly. Native apps and the TUI are always clients of a
+ * long-lived gateway subprocess; the TUI is never the agent host.
+ *
+ * The spawned daemon is independent: we `unref()` it so the parent (chat)
+ * can exit without tearing it down. Stopping it is explicit:
+ * `brigade gateway stop`.
+ */
+export interface EnsureGatewayOptions {
+    host?: string;
+    port?: number;
+    /** Max ms to wait for a freshly-spawned gateway to accept connections. */
+    spawnTimeoutMs?: number;
+    /** Surface boot progress (e.g. to stderr) while we wait for readiness. */
+    onStatus?: (message: string) => void;
+}
+export interface EnsureGatewayResult {
+    /** True when a gateway was already running (we did NOT spawn one). */
+    alreadyRunning: boolean;
+    host: string;
+    port: number;
+}
+/**
+ * Ensure a gateway is reachable at host:port. If one is already up, return
+ * immediately. Otherwise spawn a detached daemon and poll until it accepts
+ * connections (or the timeout elapses). Throws a friendly error on timeout.
+ *
+ * The caller is expected to have already verified a provider/model is
+ * configured — a gateway with no config exits on boot, which would surface
+ * here as a readiness timeout.
+ */
+export declare function ensureGatewayRunning(opts?: EnsureGatewayOptions): Promise<EnsureGatewayResult>;
+//# sourceMappingURL=gateway-spawn.d.ts.map

package/dist/core/gateway-spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-spawn.d.ts","sourceRoot":"","sources":["../../src/core/gateway-spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,MAAM,WAAW,oBAAoB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IACnC,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAmED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,GAAE,oBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqExG"}