@zswarm/core 0.1.9 → 0.2.1

package/dist/host/cli.js

@@ -0,0 +1,214 @@
+import { readFileSync } from "node:fs";
+import { ZellijError } from "../errors.js";
+import { crewCheck, crewDown, crewStart, crewStatus, crewUp } from "./crew.js";
+import { hostDoctor, hostInstall, hostInstallArgs, hostScriptPath } from "./host.js";
+import { pruneRelays, runRelayDir, startRelay, waitForRelay } from "./relay.js";
+import { runSlot } from "./slot.js";
+/**
+ * Host commands: CLI-only (not MCP ops), because they run long, pass argv
+ * through or print plain text. `zswarm <command> --help` prints the usage.
+ */
+/** `--flag value` pairs and positionals; boolean flags are listed in `bools`. */
+export function parseHostArgs(argv, bools = []) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--")) {
+            rest.push(a);
+            continue;
+        }
+        if (bools.includes(a)) {
+            flags[a] = true;
+            continue;
+        }
+        const v = argv[++i];
+        if (v === undefined)
+            throw new ZellijError("usage", `${a} needs a value`);
+        flags[a] = v;
+    }
+    return { flags, rest };
+}
+function str(v) {
+    return typeof v === "string" ? v : undefined;
+}
+/** Print a JSON result the way the other ops do; exit 0 on ok. */
+async function json(work) {
+    try {
+        const data = await work();
+        process.stdout.write(`${JSON.stringify({ ok: true, data }, null, 2)}\n`);
+        return 0;
+    }
+    catch (err) {
+        const e = err instanceof ZellijError ? { code: err.code, message: err.message, details: err.details } : { code: "failed", message: String(err) };
+        process.stdout.write(`${JSON.stringify({ ok: false, error: e }, null, 2)}\n`);
+        return 1;
+    }
+}
+async function crew(argv) {
+    const [sub, ...args] = argv;
+    const { flags, rest } = parseHostArgs(args);
+    const session = rest[0] ?? str(flags["--session"]) ?? "";
+    const runAs = str(flags["--run-as"]);
+    switch (sub) {
+        case "up":
+            return json(() => {
+                const layout = str(flags["--layout"]);
+                if (!layout)
+                    throw new ZellijError("usage", "crew up needs --layout <file.kdl>");
+                return crewUp({
+                    session,
+                    layout,
+                    config: str(flags["--config"]),
+                    envFile: str(flags["--env-file"]),
+                    firstPane: str(flags["--first-pane"]),
+                    runAs,
+                });
+            });
+        case "down":
+            return json(() => crewDown({ session, runAs }));
+        case "status":
+            return json(() => crewStatus({ session, runAs }));
+        case "start":
+            return crewStart(session);
+        case "check":
+            return crewCheck(session);
+        default:
+            process.stderr.write(`${COMMANDS.crew.usage}\n`);
+            return 2;
+    }
+}
+async function relay(argv) {
+    const { flags } = parseHostArgs(argv, ["--foreground", "--prune"]);
+    const run = str(flags["--run"]);
+    if (run)
+        return runRelayDir(run);
+    const waitId = str(flags["--wait"]);
+    if (waitId) {
+        const message = await waitForRelay(waitId, { timeoutMin: Number(str(flags["--timeout-min"]) ?? 240) });
+        if (message === null) {
+            process.stderr.write(`relay ${waitId}: no message before the timeout\n`);
+            return 3;
+        }
+        process.stdout.write(message);
+        return 0;
+    }
+    if (flags["--prune"]) {
+        return json(() => ({ removed: pruneRelays(Number(str(flags["--days"]) ?? 14)) }));
+    }
+    return json(() => startRelay({
+        id: str(flags["--id"]),
+        serve: str(flags["--serve"]),
+        session: str(flags["--session"]),
+        to: str(flags["--to"]) ?? "",
+        bodyFile: str(flags["--body-file"]),
+        from: str(flags["--from"]),
+        done: str(flags["--done"]) ?? "",
+        replyTo: str(flags["--reply-to"]) ?? "",
+        replySession: str(flags["--reply-session"]),
+        check: str(flags["--check"]),
+        message: str(flags["--message"]),
+        timeoutMin: flags["--timeout-min"] ? Number(str(flags["--timeout-min"])) : undefined,
+        foreground: flags["--foreground"] === true,
+    }));
+}
+async function host(argv) {
+    const [sub, ...args] = argv;
+    const { flags } = parseHostArgs(args, ["--script", "--sudo"]);
+    const install = {
+        ssh: str(flags["--ssh"]),
+        sudo: flags["--sudo"] === true,
+        prefix: str(flags["--prefix"]),
+        binDir: str(flags["--bin-dir"]),
+        node: str(flags["--node"]),
+        zellij: str(flags["--zellij"]),
+        zswarm: str(flags["--zswarm"]),
+    };
+    switch (sub) {
+        case "install":
+            if (flags["--script"]) {
+                // For a caller with its own root channel: sh -s -- <args> < script
+                process.stdout.write(readFileSync(hostScriptPath("host-install.sh"), "utf8"));
+                process.stderr.write(`args: ${hostInstallArgs(install).join(" ")}\n`);
+                return 0;
+            }
+            return json(() => hostInstall(install));
+        case "doctor": {
+            const res = await hostDoctor({ ssh: install.ssh, session: str(flags["--session"]), serve: str(flags["--serve"]) }).catch((err) => ({ error: err }));
+            if ("error" in res)
+                return json(() => Promise.reject(res.error));
+            process.stdout.write(`${JSON.stringify({ ok: res.ok, data: res }, null, 2)}\n`);
+            return res.ok ? 0 : 1;
+        }
+        default:
+            process.stderr.write(`${COMMANDS.host.usage}\n`);
+            return 2;
+    }
+}
+const COMMANDS = {
+    slot: {
+        usage: [
+            "zswarm slot [--project NAME] [--] COMMAND [ARG ...]   run COMMAND inside a build slot",
+            "zswarm slot --status                                 show the host's slots and holders",
+            "zswarm slot --setup --slots N [--jobs J] [--group G]  create slots.conf and lock files (root)",
+            "zswarm slot --setup-project NAME --cap M [--group G]  cap a project below the host count (root)",
+            "zswarm slot --path                                   print the bundled slot.py path",
+        ].join("\n"),
+        run: (argv) => runSlot(argv),
+    },
+    crew: {
+        usage: [
+            "zswarm crew up <session> --layout L.kdl [--config C.kdl] [--env-file F] [--first-pane NAME] [--run-as USER]",
+            "                                  keep the session running from its layout (service + 2-min watchdog)",
+            "zswarm crew status <session> [--run-as USER]   services, session, panes",
+            "zswarm crew down <session> [--run-as USER]     remove the services and kill the session",
+            "zswarm crew start|check <session>              what the service and the watchdog run",
+        ].join("\n"),
+        run: crew,
+    },
+    relay: {
+        usage: [
+            "zswarm relay --to PANE --done REGEX --reply-to PANE [--serve TARGET] [--session S] [--body-file F]",
+            "             [--reply-session S] [--from NAME] [--check SCRIPT] [--message TEMPLATE] [--id ID]",
+            "             [--timeout-min 240] [--foreground]",
+            "      send the body to PANE over serve (ZSWARM_SERVE / ZSWARM_SERVE_TOKEN), then a detached relay",
+            "      waits for REGEX (and SCRIPT exit 0) and pastes a message into the local --reply-to pane",
+            "zswarm relay --wait ID [--timeout-min 240]   block until relay ID has its message, print it (pull path)",
+            "zswarm relay --prune [--days 14]   remove old relay dirs and undelivered messages",
+        ].join("\n"),
+        run: relay,
+    },
+    host: {
+        usage: [
+            "zswarm host install --ssh DEST [--sudo] [--prefix /usr/local/lib/zswarm] [--bin-dir /usr/local/bin]",
+            "                    [--node V] [--zellij V] [--zswarm V]   Node.js, zswarm and Zellij on a Linux/macOS host",
+            "zswarm host install --script [same options]   print the script (run it as: sh -s -- <args printed on stderr>)",
+            "zswarm host doctor [--ssh DEST] [--serve TARGET] [--session S]   tools, disk, services, serve, session, panes",
+        ].join("\n"),
+        run: host,
+    },
+};
+export const HOST_COMMANDS = Object.keys(COMMANDS);
+export function hostUsage() {
+    return Object.values(COMMANDS).map((c) => c.usage).join("\n") + "\n";
+}
+/** Run a host command; resolves to the process exit code. */
+export async function runHostCommand(argv) {
+    const [name, ...rest] = argv;
+    const command = name ? COMMANDS[name] : undefined;
+    if (!command) {
+        process.stderr.write(`unknown host command ${name ?? ""}\n${hostUsage()}`);
+        return 2;
+    }
+    if (rest[0] === "-h" || rest[0] === "--help") {
+        process.stdout.write(`${command.usage}\n`);
+        return 0;
+    }
+    try {
+        return await command.run(rest);
+    }
+    catch (err) {
+        process.stderr.write(`zswarm ${name}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+}

package/dist/host/crew.d.ts

@@ -0,0 +1,81 @@
+import { type Runner, type ServiceAccount, type ServiceHost, type ServiceSpec } from "./services.js";
+export declare const CREW_WATCH_SEC = 120;
+export type CrewDeps = {
+    env?: NodeJS.ProcessEnv;
+    /** The crew directory; defaults to ~/.zswarm/crews/<session>. */
+    dir?: string;
+    /** Runs zellij; injected in tests. */
+    zellij?: (args: string[], env: NodeJS.ProcessEnv) => {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+    /** Live session names; injected in tests. */
+    sessions?: (env: NodeJS.ProcessEnv) => Promise<string[]>;
+    /** Pane titles (with exited flags) of a session; injected in tests. */
+    panes?: (session: string, env: NodeJS.ProcessEnv) => Promise<Array<{
+        title: string;
+        exited: boolean;
+    }>>;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+    /** Restarts a systemd user unit (the watchdog on Linux); injected in tests. */
+    restartUnit?: (unit: string) => number;
+};
+/** Env the Linux watchdog unit carries: restart this unit instead of starting Zellij itself. */
+export declare const CREW_UNIT_ENV = "ZSWARM_CREW_UNIT";
+export declare function checkCrewSession(session: string | undefined): string;
+export declare function crewDir(account: ServiceAccount, session: string, env?: NodeJS.ProcessEnv): string;
+/** The first `pane ... name="X"` in a KDL layout: the pane whose presence proves the layout took. */
+export declare function firstLayoutPane(kdl: string): string | undefined;
+/** KEY=VALUE lines (optional `export`, quotes, comments) into an object. */
+export declare function parseEnvFile(text: string): Record<string, string>;
+/** Start the session from its layout and prove the first pane exists; up to three tries. */
+export declare function crewStart(session: string, deps?: CrewDeps): Promise<number>;
+/** Watchdog: restart the session if its server died or its first pane is gone. */
+export declare function crewCheck(session: string, deps?: CrewDeps): Promise<number>;
+export type CrewUpInput = {
+    session: string;
+    layout: string;
+    config?: string;
+    envFile?: string;
+    firstPane?: string;
+    runAs?: string;
+    env?: NodeJS.ProcessEnv;
+    account?: ServiceAccount;
+    run?: Runner;
+    fs?: ServiceHost["fs"];
+    launch?: {
+        execPath: string;
+        scriptPath: string;
+    };
+    /** Copies crew files into the crew dir; injected in tests. */
+    copy?: (account: ServiceAccount, from: string, to: string, secret: boolean) => void;
+    writeMeta?: (account: ServiceAccount, path: string, text: string) => void;
+};
+export declare function crewServiceSpecs(input: {
+    account: ServiceAccount;
+    session: string;
+    launch: {
+        execPath: string;
+        scriptPath: string;
+    };
+    env: NodeJS.ProcessEnv;
+}): ServiceSpec[];
+export declare function crewUp(input: CrewUpInput): Record<string, unknown>;
+export declare function crewStatus(input: {
+    session: string;
+    runAs?: string;
+    env?: NodeJS.ProcessEnv;
+    account?: ServiceAccount;
+    run?: Runner;
+    deps?: CrewDeps;
+}): Promise<Record<string, unknown>>;
+export declare function crewDown(input: {
+    session: string;
+    runAs?: string;
+    env?: NodeJS.ProcessEnv;
+    account?: ServiceAccount;
+    run?: Runner;
+    fs?: ServiceHost["fs"];
+}): Record<string, unknown>;

package/dist/host/crew.js

@@ -0,0 +1,279 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { posix } from "node:path";
+import { ZellijError } from "../errors.js";
+import { dispatchZswarm } from "../ops/dispatch.js";
+import { resolveServeCliLaunch } from "../ops/serve-install.js";
+import { defaultStateDir } from "../state.js";
+import { resolveZellijBinary } from "../zellij/binary.js";
+import { defaultRunner, ensureAccountDir, installServices, removeServices, serviceAccount, serviceStates, writeAccountFile, writeSecretFile, } from "./services.js";
+// Service accounts are Linux or macOS accounts: their paths are POSIX paths
+// even when this code runs (in tests) on Windows.
+const { join } = posix;
+/**
+ * `zswarm crew`: keep a Zellij session built from a layout running on a host.
+ *
+ *   up      copy the layout (and optional config and env file) into
+ *           ~/.zswarm/crews/<session>/, install a oneshot service that starts
+ *           the session and a watchdog that restarts it every two minutes if
+ *           its server died or its layout did not take
+ *   start   what the service runs: start the session, prove the first layout
+ *           pane exists, retry up to three times
+ *   check   what the watchdog runs: start again only if needed
+ *   status  services, session and panes
+ *   down    remove the services and kill the session
+ *
+ * Zellij now and then starts `attach --create-background --layout` as a
+ * plain one-pane session; the first-pane check is what catches that.
+ */
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const FOREIGN_PATH = "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin";
+export const CREW_WATCH_SEC = 120;
+/** Env the Linux watchdog unit carries: restart this unit instead of starting Zellij itself. */
+export const CREW_UNIT_ENV = "ZSWARM_CREW_UNIT";
+export function checkCrewSession(session) {
+    const s = session?.trim() ?? "";
+    if (!SESSION.test(s))
+        throw new ZellijError("bad_arg", `invalid session name ${JSON.stringify(s)}`);
+    return s;
+}
+export function crewDir(account, session, env = process.env) {
+    const base = !account.foreign && env.ZSWARM_STATE_DIR?.trim() ? defaultStateDir(env) : join(account.home, ".zswarm");
+    return join(base, "crews", session);
+}
+/** The first `pane ... name="X"` in a KDL layout: the pane whose presence proves the layout took. */
+export function firstLayoutPane(kdl) {
+    for (const line of kdl.split("\n")) {
+        const code = line.replace(/\/\/.*$/, "");
+        if (!/^\s*pane\b/.test(code))
+            continue;
+        const m = /\bname\s*=?\s*"([^"]+)"/.exec(code);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/** KEY=VALUE lines (optional `export`, quotes, comments) into an object. */
+export function parseEnvFile(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line);
+        if (!m)
+            continue;
+        let value = m[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[m[1]] = value;
+    }
+    return out;
+}
+function readCrewFiles(dir) {
+    const meta = join(dir, "crew.json");
+    if (!existsSync(meta))
+        throw new ZellijError("usage", `no crew in ${dir}; run zswarm crew up first`);
+    return JSON.parse(readFileSync(meta, "utf8"));
+}
+async function defaultSessions(env) {
+    const res = await dispatchZswarm({ op: "sessions" }, undefined, { env });
+    if (!res.ok)
+        return [];
+    return (res.data.sessions ?? []).map((s) => s.name ?? "");
+}
+async function defaultPanes(session, env) {
+    const res = await dispatchZswarm({ op: "list", session }, undefined, { env });
+    if (!res.ok)
+        return [];
+    const panes = res.data.panes ?? [];
+    return panes.map((p) => ({ title: p.title ?? "", exited: p.exited === true }));
+}
+function defaultZellij(args, env) {
+    const res = spawnSync(resolveZellijBinary(env), args, { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000 });
+    return { status: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+function crewEnv(dir, files, env) {
+    const extra = files.env ? parseEnvFile(readFileSync(join(dir, files.env), "utf8")) : {};
+    // No bus inside the start/check helpers: they list panes once and exit.
+    return { ...env, TERM: env.TERM || "xterm-256color", ...extra, ZSWARM_BUS: "0" };
+}
+/** Start the session from its layout and prove the first pane exists; up to three tries. */
+export async function crewStart(session, deps = {}) {
+    const env0 = deps.env ?? process.env;
+    const dir = deps.dir ?? crewDir(serviceAccount(undefined), checkCrewSession(session), env0);
+    const files = readCrewFiles(dir);
+    const env = crewEnv(dir, files, env0);
+    const zellij = deps.zellij ?? defaultZellij;
+    const sessions = deps.sessions ?? defaultSessions;
+    const panes = deps.panes ?? defaultPanes;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const log = deps.log ?? ((line) => process.stdout.write(`${new Date().toISOString()} ${line}\n`));
+    const config = files.config ? ["--config", join(dir, files.config)] : [];
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        zellij(["delete-session", session], env); // clears only a dead session of this name
+        zellij([...config, "--layout", join(dir, files.layout), "attach", "--create-background", session], env);
+        for (let i = 0; i < 20 && !(await sessions(env)).includes(session); i++)
+            await sleep(500);
+        await sleep(2_000);
+        if ((await panes(session, env)).some((p) => p.title === files.first)) {
+            log(`session ${session} up with its layout (attempt ${attempt})`);
+            return 0;
+        }
+        log(`session ${session} came up without its layout (attempt ${attempt}); recreating`);
+        zellij(["kill-session", session], env);
+        await sleep(1_000);
+    }
+    log(`session ${session} never took its layout`);
+    return 1;
+}
+/** Watchdog: restart the session if its server died or its first pane is gone. */
+export async function crewCheck(session, deps = {}) {
+    const env0 = deps.env ?? process.env;
+    const dir = deps.dir ?? crewDir(serviceAccount(undefined), checkCrewSession(session), env0);
+    const files = readCrewFiles(dir);
+    const env = crewEnv(dir, files, env0);
+    const sessions = deps.sessions ?? defaultSessions;
+    const panes = deps.panes ?? defaultPanes;
+    const log = deps.log ?? ((line) => process.stdout.write(`${new Date().toISOString()} ${line}\n`));
+    if ((await sessions(env)).includes(session) && (await panes(session, env)).some((p) => p.title === files.first)) {
+        return 0;
+    }
+    log(`session ${session} is gone or lost its layout; restarting`);
+    (deps.zellij ?? defaultZellij)(["kill-session", session], env);
+    const unit = env0[CREW_UNIT_ENV]?.trim();
+    if (unit) {
+        // Under systemd a server started here would live in the watchdog's cgroup
+        // and die when this check exits; the crew unit owns the session instead.
+        const restart = deps.restartUnit ?? ((u) => spawnSync("systemctl", ["--user", "restart", u], { stdio: "inherit" }).status ?? 1);
+        return restart(unit);
+    }
+    return await crewStart(session, deps);
+}
+function copyForAccount(account, from, to, secret) {
+    ensureAccountDir(account, to.slice(0, to.lastIndexOf("/")));
+    if (secret) {
+        writeSecretFile(account, to, readFileSync(from, "utf8"));
+        return;
+    }
+    // Read as the caller, write as the account (no chown through a planted symlink).
+    writeAccountFile(account, to, readFileSync(from), 0o644);
+}
+export function crewServiceSpecs(input) {
+    const { account, session, launch } = input;
+    const base = account.foreign
+        ? { PATH: FOREIGN_PATH }
+        : { PATH: input.env.PATH ?? FOREIGN_PATH };
+    for (const key of ["ZSWARM_BIN", "ZSWARM_STATE_DIR"]) {
+        const v = input.env[key]?.trim();
+        if (v && !(account.foreign && key === "ZSWARM_STATE_DIR"))
+            base[key] = v;
+    }
+    const cli = [launch.execPath, launch.scriptPath, "crew"];
+    return [
+        {
+            name: `crew-${session}`,
+            description: `zswarm crew: Zellij session ${session} from its layout`,
+            kind: "oneshot",
+            argv: [...cli, "start", session],
+            env: base,
+            workingDir: account.home,
+            // The forked Zellij server and its panes outlive a stop or restart of the
+            // unit (a rerun of crew up must not kill working agents); crew down
+            // kills the session itself.
+            killMode: "process",
+        },
+        {
+            name: `crew-${session}-watch`,
+            description: `zswarm crew: restart session ${session} if it died`,
+            kind: "interval",
+            intervalSec: CREW_WATCH_SEC,
+            argv: [...cli, "check", session],
+            env: account.platform === "linux" ? { ...base, [CREW_UNIT_ENV]: `zswarm-crew-${session}.service` } : base,
+            workingDir: account.home,
+        },
+    ];
+}
+export function crewUp(input) {
+    const env = input.env ?? process.env;
+    const run = input.run ?? defaultRunner;
+    const account = input.account ?? serviceAccount(input.runAs, run);
+    const session = checkCrewSession(input.session);
+    if (!existsSync(input.layout))
+        throw new ZellijError("usage", `layout ${input.layout} not found`);
+    const kdl = readFileSync(input.layout, "utf8");
+    const first = input.firstPane?.trim() || firstLayoutPane(kdl);
+    if (!first) {
+        throw new ZellijError("usage", "the layout names no pane; give panes a name or pass --first-pane");
+    }
+    const launch = input.launch ?? resolveServeCliLaunch({ env });
+    const dir = crewDir(account, session, env);
+    const copy = input.copy ?? copyForAccount;
+    const files = { layout: "layout.kdl", first };
+    copy(account, input.layout, join(dir, "layout.kdl"), false);
+    if (input.config) {
+        copy(account, input.config, join(dir, "config.kdl"), false);
+        files.config = "config.kdl";
+    }
+    if (input.envFile) {
+        copy(account, input.envFile, join(dir, "env"), true);
+        files.env = "env";
+    }
+    // crew.json is written last, so a half-copied crew never starts.
+    (input.writeMeta ?? writeSecretFile)(account, join(dir, "crew.json"), `${JSON.stringify(files, null, 1)}\n`);
+    const specs = crewServiceSpecs({ account, session, launch, env });
+    const done = installServices({ account, run, fs: input.fs }, specs);
+    const states = serviceStates({ account, run }, specs);
+    return {
+        session,
+        user: account.user,
+        dir,
+        firstPane: first,
+        services: states,
+        ready: states.every((s) => s.active),
+        actions: done.lines,
+        notes: done.notes,
+    };
+}
+export async function crewStatus(input) {
+    const env = input.env ?? process.env;
+    const run = input.run ?? defaultRunner;
+    const account = input.account ?? serviceAccount(input.runAs, run);
+    const session = checkCrewSession(input.session);
+    const specs = crewServiceSpecs({ account, session, launch: { execPath: "", scriptPath: "" }, env });
+    const services = serviceStates({ account, run }, specs);
+    const out = { session, user: account.user, services };
+    if (account.foreign) {
+        out.note = `session and panes belong to ${account.user}: run zswarm crew status ${session} as that user`;
+        return out;
+    }
+    const files = existsSync(join(crewDir(account, session, env), "crew.json"))
+        ? readCrewFiles(crewDir(account, session, env))
+        : undefined;
+    const live = (await (input.deps?.sessions ?? defaultSessions)(env)).includes(session);
+    const panes = live ? await (input.deps?.panes ?? defaultPanes)(session, { ...env, ZSWARM_BUS: "0" }) : [];
+    out.live = live;
+    out.firstPane = files?.first ?? null;
+    out.layoutTook = files ? panes.some((p) => p.title === files.first) : null;
+    out.panes = panes;
+    out.healthy = services.every((s) => s.active) && live && out.layoutTook !== false && panes.every((p) => !p.exited);
+    return out;
+}
+export function crewDown(input) {
+    const env = input.env ?? process.env;
+    const run = input.run ?? defaultRunner;
+    const account = input.account ?? serviceAccount(input.runAs, run);
+    const session = checkCrewSession(input.session);
+    const specs = crewServiceSpecs({ account, session, launch: { execPath: "", scriptPath: "" }, env });
+    const lines = removeServices({ account, run, fs: input.fs }, specs);
+    // The Zellij server belongs to the account: kill it as that user.
+    const zellij = env.ZSWARM_BIN?.trim() || "zellij";
+    const kill = account.foreign
+        ? account.platform === "linux"
+            ? run("runuser", ["-u", account.user, "--", "env", `XDG_RUNTIME_DIR=/run/user/${account.uid}`, `PATH=${FOREIGN_PATH}`, zellij, "kill-session", session])
+            : run("sudo", ["-u", account.user, "-H", "env", `PATH=${FOREIGN_PATH}`, zellij, "kill-session", session])
+        : run(zellij, ["kill-session", session]);
+    lines.push(kill.status === 0 ? `session ${session} killed` : `session ${session} was not running`);
+    return { session, user: account.user, actions: lines };
+}

package/dist/host/host.d.ts

@@ -0,0 +1,55 @@
+import type { OpsResult } from "../ops/types.js";
+/**
+ * `zswarm host install` puts Node.js, zswarm and Zellij on a Linux or macOS
+ * host over SSH (or prints the script, for callers with their own root
+ * channel). `zswarm host doctor` checks a host: tools, disk, sessions and
+ * services over SSH, then serve, the session and its panes through the
+ * normal transport.
+ */
+export declare function hostScriptPath(name: "host-install.sh" | "host-report.sh"): string;
+export type SshRunner = (dest: string, remoteCommand: string[], stdin: string) => {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare const defaultSsh: SshRunner;
+export type HostInstallInput = {
+    ssh?: string;
+    sudo?: boolean;
+    prefix?: string;
+    binDir?: string;
+    node?: string;
+    zellij?: string;
+    zswarm?: string;
+    run?: SshRunner;
+};
+export declare function hostInstallArgs(input: HostInstallInput): string[];
+export declare function hostInstall(input: HostInstallInput): {
+    steps: Record<string, string>;
+    output: string;
+};
+export type HostCheck = {
+    id: string;
+    state: "pass" | "warn" | "fail";
+    detail: string;
+};
+/** KEY=VALUE lines from host-report.sh; `service=` lines are collected. */
+export declare function parseHostReport(text: string): {
+    facts: Record<string, string>;
+    services: string[];
+};
+export declare function hostChecks(facts: Record<string, string>, services: string[], session?: string): HostCheck[];
+export type HostDoctorInput = {
+    ssh?: string;
+    session?: string;
+    serve?: string;
+    env?: NodeJS.ProcessEnv;
+    run?: SshRunner;
+    call?: (args: Record<string, unknown>, env: NodeJS.ProcessEnv) => Promise<OpsResult>;
+};
+export declare function hostDoctor(input: HostDoctorInput): Promise<{
+    ok: boolean;
+    checks: HostCheck[];
+    facts?: Record<string, string>;
+    transport?: unknown;
+}>;