@amd-gaia/gaia 0.1.0 → 0.2.0

package/dist/lifecycle.js

@@ -0,0 +1,613 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+/**
+ * Process lifecycle for the two binaries this package installs.
+ *
+ * **Sidecar** — locate the frozen binary, spawn it, poll `GET /health`, check the
+ * contract version via `GET /version`, and shut it down killing the whole process
+ * tree. Tree-kill matters: a PyInstaller one-file build spawns a child uvicorn
+ * process that `child.kill()` on the parent does NOT reap, leaving the port held.
+ *
+ * **TUI** — exec it with stdio inherited and propagate its exit code, so the
+ * terminal UI owns the terminal completely.
+ *
+ * Note on who spawns the sidecar in the normal `gaia` flow: the GAIA daemon does.
+ * The TUI reaches agents through the daemon's relay and deliberately never holds a
+ * sidecar bearer token, so `gaia run` stages the *verified* sidecar binary into the
+ * daemon's cache and lets the daemon own its process. The helpers below are the
+ * direct path — used by `gaia serve` and by programmatic integrators who want the
+ * REST surface without a daemon.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { BinaryNotFoundError, HealthTimeoutError, HttpError, IntegrityError, MalformedResponseError, PortInUseError, SidecarExitedError, VersionMismatchError, } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { currentPlatformKey, isPlaceholderSha, loadLock, resolveEntry, } from "./platform.js";
+const log = createLogger("lifecycle");
+export const DEFAULT_HOST = "127.0.0.1";
+/** Matches `gaia_agent.server.DEFAULT_PORT`. NEVER 4001 (repo-reserved). */
+export const DEFAULT_PORT = 8141;
+/** Repo-wide reserved port. Nothing here may ever bind it. */
+export const RESERVED_PORT = 4001;
+/** The apiVersion this package is built against (`server.py: API_VERSION`). */
+export const API_VERSION = "2.12";
+/** The agent id in the sidecar's route prefix (`/v1/gaia/...`). */
+export const AGENT_ID = "gaia";
+/** Basename the sidecar executable is written as (matches the lock). */
+export function sidecarExecutableName(platform = process.platform) {
+    return platform === "win32" ? "gaia-agent.exe" : "gaia-agent";
+}
+/**
+ * Basename the TUI executable is written as. Deliberately `gaia-tui`, not
+ * `gaia`: npm installs its own `gaia` bin shim, and a same-named executable in a
+ * cache dir on PATH would shadow it.
+ */
+export function tuiExecutableName(platform = process.platform) {
+    return platform === "win32" ? "gaia-tui.exe" : "gaia-tui";
+}
+/** SHA-256 of a file, read in chunks so a ~200MB binary is not buffered whole. */
+function fileSha256Sync(filePath) {
+    const hash = crypto.createHash("sha256");
+    const buf = Buffer.allocUnsafe(1 << 20);
+    const fd = fs.openSync(filePath, "r");
+    try {
+        for (;;) {
+            const n = fs.readSync(fd, buf, 0, buf.length, null);
+            if (n === 0)
+                break;
+            hash.update(buf.subarray(0, n));
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return hash.digest("hex");
+}
+/**
+ * Re-verify an on-disk binary against the lock. `fetch.ts` calls the SHA verify
+ * "the security boundary"; this keeps that true for the resolve→spawn path,
+ * which is exported and whose cache path is guessable.
+ */
+function verifyAgainstLock(full, component, lock) {
+    const platformKey = currentPlatformKey();
+    const entry = resolveEntry(lock ?? loadLock(), component, platformKey);
+    if (isPlaceholderSha(entry.sha256)) {
+        throw new IntegrityError(`binaries.lock.json has a placeholder sha256 for ${component}/'${platformKey}', ` +
+            `so ${full} cannot be verified and must not be spawned. Install a released ` +
+            "@amd-gaia/gaia, or pass { verify: false } if you built this binary yourself.");
+    }
+    const actual = fileSha256Sync(full);
+    if (actual.toLowerCase() !== entry.sha256.toLowerCase()) {
+        throw new IntegrityError(`SHA-256 mismatch for the ${component} binary at ${full}:\n` +
+            `  expected ${entry.sha256}\n` +
+            `  actual   ${actual}\n` +
+            "Refusing to spawn a binary that does not match binaries.lock.json. " +
+            "Re-run `npx @amd-gaia/gaia fetch --force` to reinstall it; if it persists, " +
+            "report it at https://github.com/amd/gaia/issues.");
+    }
+}
+/** Resolve a fetched binary's path, failing loudly if it is not there. */
+function resolveIn(opts, component, fallback, what) {
+    if (!opts?.resourcesDir) {
+        throw new TypeError("resolve requires { resourcesDir }");
+    }
+    const full = path.resolve(opts.resourcesDir, opts.executable ?? fallback);
+    if (!fs.existsSync(full)) {
+        throw new BinaryNotFoundError(`${what} binary not found at ${full} (platform ${currentPlatformKey()}). ` +
+            "Run the fetch step first: `npx @amd-gaia/gaia fetch`.");
+    }
+    if (opts.verify ?? true)
+        verifyAgainstLock(full, component, opts.lock);
+    return full;
+}
+export function resolveSidecarPath(opts) {
+    return resolveIn(opts, "sidecar", sidecarExecutableName(), "gaia-agent sidecar");
+}
+export function resolveTuiPath(opts) {
+    return resolveIn(opts, "tui", tuiExecutableName(), "gaia-tui");
+}
+// --- Auto-cleanup: reap orphaned sidecars when the parent process goes away ---
+// The sidecar is spawned detached (its own process group), so a parent Ctrl+C,
+// crash, or plain exit does NOT propagate to it — without this it keeps running
+// and holds its port. Handlers are installed once and SIGKILL the tree
+// synchronously on the way out. A hard SIGKILL of the parent is the one case no
+// in-process handler can catch.
+const liveSidecars = new Set();
+let cleanupInstalled = false;
+const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/** stderr from an exit handler: console.error can be async on a piped stderr. */
+function writeStderrSync(msg) {
+    try {
+        fs.writeSync(2, msg.endsWith("\n") ? msg : `${msg}\n`);
+    }
+    catch {
+        /* stderr unavailable */
+    }
+}
+function killTreeSync(sidecar) {
+    const { child } = sidecar;
+    if (child.pid === undefined)
+        return;
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        if (process.platform === "win32") {
+            const r = spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], {
+                stdio: ["ignore", "ignore", "pipe"],
+                encoding: "utf8",
+            });
+            // A refusal ("Access is denied") leaves the port held; say so now rather
+            // than let it surface as an unexplained bind failure on the next run.
+            if (r.error || r.status !== 0) {
+                writeStderrSync(`[gaia:lifecycle] ERROR taskkill /PID ${child.pid} /T /F failed ` +
+                    `(${r.error ? r.error.message : `exit ${String(r.status)}`}): ` +
+                    `${(r.stderr ?? "").trim() || "(no output)"}. ` +
+                    `Kill pid ${child.pid} manually or port ${sidecar.port} stays bound.`);
+            }
+        }
+        else {
+            process.kill(-child.pid, "SIGKILL");
+        }
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ESRCH")
+            return; // already gone — the outcome we wanted
+        writeStderrSync(`[gaia:lifecycle] ERROR could not kill the sidecar process group ` +
+            `${String(child.pid)}: ${e.message}. ` +
+            `Kill it manually or port ${sidecar.port} stays bound.`);
+    }
+}
+function reapAllSync() {
+    for (const s of liveSidecars)
+        killTreeSync(s);
+    liveSidecars.clear();
+}
+function crashHandler(err) {
+    reapAllSync();
+    try {
+        // Synchronous write — console.error can truncate on a piped stderr before
+        // process.exit flushes.
+        fs.writeSync(2, `${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    }
+    catch {
+        /* stderr unavailable */
+    }
+    process.exit(1);
+}
+/**
+ * True when ours is the only listener for `event`, i.e. nothing else in this
+ * process handles it and the process is therefore going down.
+ *
+ * Reaping is only ours to do in that case: a host with its own handler keeps
+ * running, and killing its sidecar would turn an exception it handled into an
+ * unexplained ECONNREFUSED on its next request.
+ */
+function weOwnTheExit(event) {
+    return process.listenerCount(event) === 1;
+}
+function installCleanupHandlers() {
+    if (cleanupInstalled)
+        return;
+    cleanupInstalled = true;
+    // The backstop: whatever route the process takes out, this runs.
+    process.on("exit", reapAllSync);
+    // crashHandler reaps before it exits, so the guard is the whole handler.
+    process.on("uncaughtException", (err) => {
+        if (weOwnTheExit("uncaughtException"))
+            crashHandler(err);
+    });
+    process.on("unhandledRejection", (err) => {
+        if (weOwnTheExit("unhandledRejection"))
+            crashHandler(err);
+    });
+    for (const sig of CLEANUP_SIGNALS) {
+        const handler = () => {
+            if (!weOwnTheExit(sig))
+                return;
+            reapAllSync();
+            // Restore the default disposition and re-raise so we still terminate.
+            process.removeListener(sig, handler);
+            process.kill(process.pid, sig);
+        };
+        process.on(sig, handler);
+    }
+}
+function registerForCleanup(sidecar) {
+    installCleanupHandlers();
+    liveSidecars.add(sidecar);
+    sidecar.child.once("exit", () => liveSidecars.delete(sidecar));
+}
+/**
+ * Spawn the frozen sidecar. Does NOT wait for readiness — call `waitForHealth`
+ * (or `startSidecar`, which does both).
+ */
+export function spawnSidecar(opts) {
+    if (!opts?.binaryPath) {
+        throw new TypeError("spawnSidecar requires { binaryPath }");
+    }
+    if (!fs.existsSync(opts.binaryPath)) {
+        throw new BinaryNotFoundError(`binary does not exist: ${opts.binaryPath}`);
+    }
+    const host = opts.host ?? DEFAULT_HOST;
+    const port = opts.port ?? DEFAULT_PORT;
+    if (port === RESERVED_PORT) {
+        throw new RangeError(`port ${RESERVED_PORT} is reserved and must never be used`);
+    }
+    const args = ["--host", host, "--port", String(port)];
+    if (opts.extraArgs?.length)
+        args.push(...opts.extraArgs);
+    log.info(`spawning ${opts.binaryPath} ${args.join(" ")}`);
+    const child = spawn(opts.binaryPath, args, {
+        // detached on POSIX → the child leads its own process group so we can signal
+        // the whole tree. Windows has different detach semantics; we use taskkill /T.
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, ...(opts.env ?? {}) },
+    });
+    child.stdout?.on("data", (d) => log.debug(`[sidecar stdout] ${String(d).trimEnd()}`));
+    child.stderr?.on("data", (d) => log.debug(`[sidecar stderr] ${String(d).trimEnd()}`));
+    child.on("exit", (code, signal) => log.debug(`sidecar exited code=${code} signal=${signal}`));
+    child.on("error", (e) => log.error(`sidecar process error: ${e.message}`));
+    const sidecar = { child, host, port, baseUrl: `http://${host}:${port}` };
+    if (opts.autoCleanup !== false)
+        registerForCleanup(sidecar);
+    return sidecar;
+}
+async function getJson(url, timeoutMs, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    // Link the caller's signal so an in-flight probe aborts the moment the
+    // process being probed dies, rather than at the next poll.
+    const onAbort = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const res = await fetch(url, {
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new HttpError(res.status, url, text);
+        try {
+            return JSON.parse(text);
+        }
+        catch (e) {
+            // A proxy or captive portal answering 200 with HTML lands here; a bare
+            // SyntaxError would escape the CLI's GaiaError branch as a raw stack.
+            throw new MalformedResponseError(`${url} returned HTTP ${res.status} but its body is not JSON ` +
+                `(${e.message}). First 200 bytes: ${JSON.stringify(text.slice(0, 200))}. ` +
+                "Something other than the gaia sidecar is answering that address — " +
+                "check for a proxy on the port, or point at the right host/port.");
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+}
+/** `GET /health` — liveness only; it does not mean a model is loaded. */
+export function health(baseUrl, timeoutMs = 1000, signal) {
+    return getJson(`${baseUrl}/health`, timeoutMs, signal);
+}
+/** `GET /version` — the contract probe (`{ apiVersion, agentVersion }`). */
+export function version(baseUrl, timeoutMs = 5000) {
+    return getJson(`${baseUrl}/version`, timeoutMs);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Poll `GET /health` until the sidecar reports ok, or throw `HealthTimeoutError`.
+ * Never silently assumes ready.
+ */
+export async function waitForHealth(baseUrl, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const intervalMs = opts.intervalMs ?? 250;
+    const deadline = Date.now() + timeoutMs;
+    let lastErr = "";
+    let attempts = 0;
+    // Re-checked after every await, not just at the top of the loop: a probe that
+    // races the process's death would otherwise report a foreign server's health.
+    const throwIfAborted = () => {
+        if (!opts.signal?.aborted)
+            return;
+        throw new HealthTimeoutError(`health wait for ${baseUrl} was aborted after ${attempts} probe(s) ` +
+            "(the process being probed exited).");
+    };
+    while (Date.now() < deadline) {
+        throwIfAborted();
+        attempts++;
+        try {
+            const h = await health(baseUrl, intervalMs * 4, opts.signal);
+            throwIfAborted();
+            if (h.status === "ok") {
+                log.debug(`sidecar healthy after ${attempts} probe(s)`);
+                return;
+            }
+            lastErr = `unexpected health status: ${JSON.stringify(h)}`;
+        }
+        catch (e) {
+            throwIfAborted();
+            lastErr = e.message;
+        }
+        await sleep(intervalMs);
+        throwIfAborted();
+    }
+    throw new HealthTimeoutError(`the gaia sidecar at ${baseUrl} did not become healthy within ${timeoutMs}ms ` +
+        `(${attempts} probes). Last error: ${lastErr}. ` +
+        "Re-run with DEBUG=gaia to see the sidecar's own output, and check the port is free.");
+}
+/** Parse "2.12" → 2 (major). Throws on a non-numeric major. */
+function majorOf(v) {
+    const major = Number.parseInt(String(v).split(".")[0] ?? "", 10);
+    if (Number.isNaN(major)) {
+        throw new VersionMismatchError(`cannot parse apiVersion major from '${v}'`);
+    }
+    return major;
+}
+/**
+ * Fetch `/version` and refuse a sidecar whose apiVersion MAJOR differs from what
+ * this package expects. A major bump is a breaking contract change; a higher
+ * minor (same major) is a backward-compatible addition and is accepted.
+ */
+export async function checkVersion(baseUrl, opts = {}) {
+    const expected = opts.expectedApiVersion ?? API_VERSION;
+    const info = await version(baseUrl);
+    const expectedMajor = majorOf(expected);
+    const actualMajor = majorOf(info.apiVersion);
+    if (actualMajor !== expectedMajor) {
+        throw new VersionMismatchError(`incompatible gaia sidecar apiVersion: it reports '${info.apiVersion}' ` +
+            `(major ${actualMajor}) but this package expects major ${expectedMajor} ` +
+            `('${expected}'). A major bump is a breaking contract change. ` +
+            "Upgrade @amd-gaia/gaia to a version matching the sidecar.");
+    }
+    log.debug(`version OK: apiVersion=${info.apiVersion} agentVersion=${info.agentVersion}`);
+    return info;
+}
+/**
+ * Shut the sidecar down, killing the whole process tree. Resolves once the
+ * process has exited (or immediately if it already had).
+ */
+export async function shutdown(sidecar, timeoutMs = 5000) {
+    const { child } = sidecar;
+    if (child.exitCode !== null || child.signalCode !== null || child.pid === undefined) {
+        liveSidecars.delete(sidecar);
+        log.debug("shutdown: sidecar already exited");
+        return;
+    }
+    const pid = child.pid;
+    log.info(`shutting down sidecar pid=${pid} (tree-kill)`);
+    const exited = new Promise((resolve) => {
+        child.once("exit", () => resolve());
+    });
+    // Why the kill was refused, kept for the throw below — "Access is denied" is
+    // the difference between "retry" and "run this elevated".
+    let killDiagnostic = "";
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        let taskkillErr = "";
+        killer.stderr?.on("data", (d) => {
+            taskkillErr += String(d);
+        });
+        killer.on("error", (e) => {
+            killDiagnostic = `taskkill could not be launched: ${e.message}`;
+            log.error(killDiagnostic);
+        });
+        killer.on("exit", (code) => {
+            if (code === 0)
+                return;
+            killDiagnostic =
+                `taskkill /PID ${pid} /T /F exited ${String(code)}: ` +
+                    `${taskkillErr.trim() || "(no output)"}`;
+            log.error(killDiagnostic);
+        });
+    }
+    else {
+        try {
+            process.kill(-pid, "SIGTERM"); // negative pid → the whole process group
+        }
+        catch (e) {
+            log.debug(`SIGTERM to group failed (${e.message}); trying direct`);
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    const raceExit = async (ms) => {
+        let t;
+        const timer = new Promise((resolve) => {
+            t = setTimeout(() => resolve("timeout"), ms);
+        });
+        return Promise.race([exited.then(() => "exited"), timer]).finally(() => clearTimeout(t));
+    };
+    if ((await raceExit(timeoutMs)) === "timeout") {
+        log.warn(`sidecar did not exit within ${timeoutMs}ms; forcing`);
+        if (process.platform !== "win32") {
+            try {
+                process.kill(-pid, "SIGKILL");
+            }
+            catch {
+                /* gone */
+            }
+        }
+        // Bound the final wait too. On Windows there is no second escalation after
+        // taskkill, so an unbounded await here would hang Ctrl+C forever.
+        if ((await raceExit(timeoutMs)) === "timeout") {
+            // Deliberately still registered: the process-exit reaper is the last
+            // chance to reap a survivor, and de-registering here would orphan it.
+            throw new Error(`the gaia sidecar (pid ${pid}) did not exit after a forced kill` +
+                (killDiagnostic ? ` (${killDiagnostic})` : "") +
+                ". Kill it manually — " +
+                (process.platform === "win32"
+                    ? `taskkill /PID ${pid} /T /F`
+                    : `kill -9 -${pid}`) +
+                ` — or port ${sidecar.port} stays bound.`);
+        }
+    }
+    liveSidecars.delete(sidecar);
+    log.info("sidecar shut down");
+}
+/**
+ * Refuse a handle whose own child is dead. A healthy `/health` proves *something*
+ * owns the port — this proves it is ours. Without it a second `gaia serve` would
+ * print a ready URL for a server it cannot shut down.
+ */
+function assertOurs(sidecar) {
+    const { child } = sidecar;
+    if (child.exitCode === null && child.signalCode === null)
+        return;
+    throw new SidecarExitedError(`the gaia sidecar we spawned exited (code=${String(child.exitCode)} ` +
+        `signal=${String(child.signalCode)}) while ${sidecar.baseUrl}/health still ` +
+        `answered — another process is already bound to port ${sidecar.port}, most ` +
+        "likely an instance you started earlier. Stop it (" +
+        (process.platform === "win32"
+            ? `netstat -ano | findstr :${sidecar.port}`
+            : `lsof -i :${sidecar.port}`) +
+        ") or start on a different port with --port. Re-run with DEBUG=gaia to see " +
+        "the sidecar's own output.");
+}
+/**
+ * Decide what a dead child actually means, by asking who owns the port now.
+ *
+ * The health wait aborts the instant our child exits, so on a fast machine that
+ * abort can beat a healthy reply from an incumbent — and then a port conflict
+ * reports as a plain timeout. Re-probing settles which failure this is instead
+ * of letting the race name it. Silent when our child is alive, or when nothing
+ * answers: that is a genuine timeout and the caller rethrows it.
+ */
+async function assertNotAForeignServer(sidecar) {
+    const { child } = sidecar;
+    if (child.exitCode === null && child.signalCode === null)
+        return;
+    try {
+        if ((await health(sidecar.baseUrl, 1_000)).status !== "ok")
+            return;
+    }
+    catch {
+        return; // nothing is listening — our sidecar simply died
+    }
+    assertOurs(sidecar); // something else owns the port; throws SidecarExitedError
+}
+/**
+ * True when something is already listening on host:port.
+ *
+ * A TCP connect, not a `/health` probe: ANY listener makes our bind fail, and
+ * the incumbent need not be a GAIA sidecar. Unreachable-in-time counts as free —
+ * this exists to turn a confusing failure into a clear one early, and the
+ * spawn + health wait remains the actual gate.
+ */
+function portInUse(host, port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        const settle = (inUse) => {
+            socket.destroy();
+            resolve(inUse);
+        };
+        socket.setTimeout(timeoutMs, () => settle(false));
+        socket.once("connect", () => settle(true));
+        socket.once("error", () => settle(false)); // ECONNREFUSED — nothing there
+    });
+}
+/**
+ * Spawn → wait for health → assert the child is still ours → (optionally)
+ * version-check. On any failure the sidecar is shut down before rethrowing, so a
+ * failed start never leaks a process.
+ *
+ * The port is checked BEFORE the spawn. Without that, the frozen sidecar spends
+ * seconds unpacking before it even attempts its bind, while an incumbent answers
+ * `/health` in milliseconds — so the health wait succeeds, the still-unpacking
+ * child looks alive, and we would hand back a handle for a server we do not own.
+ * `assertOurs` / `assertNotAForeignServer` stay as backstops for the narrower
+ * race where something binds after this check.
+ */
+export async function startSidecar(opts) {
+    const host = opts.host ?? DEFAULT_HOST;
+    const port = opts.port ?? DEFAULT_PORT;
+    if (await portInUse(host, port)) {
+        throw new PortInUseError(`port ${port} on ${host} is already in use, so the gaia sidecar cannot bind ` +
+            "it. Most likely an instance you started earlier is still running. Find it " +
+            "with " +
+            (process.platform === "win32"
+                ? `\`netstat -ano | findstr :${port}\``
+                : `\`lsof -i :${port}\``) +
+            `, then stop it — or start on a different port with --port. Nothing was ` +
+            "spawned.");
+    }
+    const sidecar = spawnSidecar(opts);
+    // A sidecar that dies immediately (missing runtime lib, port already bound)
+    // must not make the caller wait out the full health timeout.
+    const died = new AbortController();
+    sidecar.child.once("exit", () => died.abort());
+    try {
+        try {
+            await waitForHealth(sidecar.baseUrl, {
+                timeoutMs: opts.healthTimeoutMs,
+                signal: died.signal,
+            });
+        }
+        catch (e) {
+            await assertNotAForeignServer(sidecar);
+            throw e;
+        }
+        assertOurs(sidecar);
+        if (opts.verifyVersion ?? true) {
+            await checkVersion(sidecar.baseUrl, {
+                expectedApiVersion: opts.expectedApiVersion,
+            });
+            assertOurs(sidecar);
+        }
+        return sidecar;
+    }
+    catch (e) {
+        log.error(`startSidecar failed (${e.message}); shutting down`);
+        await shutdown(sidecar).catch(() => undefined);
+        throw e;
+    }
+}
+/**
+ * Run the TUI in the foreground with stdio inherited and resolve with its exit
+ * code. A signal-terminated TUI resolves as 128 + signum, the shell convention,
+ * so a Ctrl+C is distinguishable from a clean exit 0.
+ */
+export function runTui(opts) {
+    if (!opts?.binaryPath) {
+        throw new TypeError("runTui requires { binaryPath }");
+    }
+    if (!fs.existsSync(opts.binaryPath)) {
+        throw new BinaryNotFoundError(`gaia-tui binary does not exist: ${opts.binaryPath}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(opts.binaryPath, opts.args ?? [], {
+            stdio: "inherit",
+            env: { ...process.env, ...(opts.env ?? {}) },
+        });
+        child.on("error", (e) => reject(new BinaryNotFoundError(`could not launch the TUI at ${opts.binaryPath}: ${e.message}`)));
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                resolve(128 + (SIGNUM[signal] ?? 0));
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}
+// Only the signals a foreground TUI realistically dies from; anything else maps
+// to 128, which still reads as "terminated by a signal".
+const SIGNUM = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGKILL: 9,
+    SIGTERM: 15,
+};
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal namespaced logger. Debug output is OFF by default and enabled via the
+ * `DEBUG` env var (substring match on `gaia`, or `*`). Everything goes to stderr
+ * so it never corrupts stdout — which the TUI owns once it is exec'd.
+ */
+export interface Logger {
+    debug(msg: string, ...rest: unknown[]): void;
+    info(msg: string, ...rest: unknown[]): void;
+    warn(msg: string, ...rest: unknown[]): void;
+    error(msg: string, ...rest: unknown[]): void;
+}
+export declare function createLogger(namespace: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAOH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC9C;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBtD"}