@zswarm/core 0.1.9 → 0.2.1

package/dist/host/services.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Background services for host commands (serve, crew): systemd user units
+ * on Linux (with linger, so they run without a login), launchd on macOS (a
+ * LaunchAgent for the current user, or, from root with `runAs`, a
+ * LaunchDaemon that runs as that user, for accounts that never log in).
+ * Secrets never go into unit files or plists: services read them from
+ * mode-600 files named in their environment.
+ */
+export type ServiceKind = 
+/** Long-running; restarted when it exits. */
+"daemon"
+/** Runs once at start (its children may outlive it); counted as up afterwards. */
+ | "oneshot"
+/** Runs every `intervalSec` seconds. */
+ | "interval";
+export type ServiceSpec = {
+    /** Unique within the account: `zswarm-<name>` (systemd) or `zswarm.<name>` (launchd). */
+    name: string;
+    description: string;
+    kind: ServiceKind;
+    argv: string[];
+    env?: Record<string, string>;
+    intervalSec?: number;
+    /** Names of other specs this one starts after (systemd ordering only). */
+    after?: string[];
+    /**
+     * systemd only: "process" leaves children (a forked Zellij server) alive
+     * when the unit stops or restarts; the default kills the whole cgroup.
+     */
+    killMode?: "process";
+    workingDir?: string;
+};
+export type ServiceAccount = {
+    platform: "linux" | "darwin";
+    user: string;
+    uid: number;
+    gid: number;
+    home: string;
+    /** Installing as root for another account (`runAs`). */
+    foreign: boolean;
+};
+export type RunResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export type Runner = (cmd: string, args: string[]) => RunResult;
+export type ServiceState = {
+    name: string;
+    unit: string;
+    state: string;
+    active: boolean;
+};
+export type ServiceHost = {
+    account: ServiceAccount;
+    run: Runner;
+    /** File writes; injected in tests. */
+    fs?: {
+        write(path: string, text: string, mode: number): void;
+        remove(path: string): void;
+        exists(path: string): boolean;
+        mkdir(path: string): void;
+    };
+};
+export declare const defaultRunner: Runner;
+/** The account services are installed for: the current user, or `runAs` when root. */
+export declare function serviceAccount(runAs?: string, run?: Runner): ServiceAccount;
+/**
+ * The argv prefix that runs a command as the account: `runuser` on Linux,
+ * `sudo -u` on macOS. Root writes into the account's home through it, so the
+ * kernel refuses what the account itself could not do (a symlink it planted
+ * towards a root-owned file, say) and new files are the account's own. (Not
+ * seteuid in this process: Node disables it on Linux while io_uring may be
+ * enabled, CVE-2024-22017.)
+ */
+export declare function accountArgv(account: ServiceAccount): string[];
+/** Write a file in the account's home as the account (see accountArgv). */
+export declare function writeAccountFile(account: ServiceAccount, path: string, text: string | Buffer, mode: number): void;
+export declare function systemdUnitName(name: string, kind: ServiceKind): string;
+export declare function systemdUnits(spec: ServiceSpec): Array<{
+    file: string;
+    text: string;
+}>;
+/** Linger keeps the user's services running without a login session. */
+export declare function ensureLinger(host: ServiceHost): {
+    linger: boolean;
+    note?: string;
+};
+export declare function launchdLabel(account: ServiceAccount, name: string): string;
+export declare function launchdPlist(account: ServiceAccount, spec: ServiceSpec): string;
+/** Write, (re)load and start the services. Returns what it did, one line per unit. */
+export declare function installServices(host: ServiceHost, specs: ServiceSpec[]): {
+    lines: string[];
+    notes: string[];
+};
+/** Stop and delete the services; missing ones are fine. */
+export declare function removeServices(host: ServiceHost, specs: Array<Pick<ServiceSpec, "name" | "kind">>): string[];
+export declare function serviceStates(host: ServiceHost, specs: Array<Pick<ServiceSpec, "name" | "kind">>): ServiceState[];
+/** Create dir and any missing parents, owned by the account when installing for it. */
+export declare function ensureAccountDir(account: ServiceAccount, dir: string, mode?: number): void;
+/** Write a mode-600 file for the account, creating its directory (700) as needed. */
+export declare function writeSecretFile(account: ServiceAccount, path: string, text: string): void;
+export declare function readSecretFile(path: string): string | undefined;

package/dist/host/services.js

@@ -0,0 +1,345 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { posix } from "node:path";
+import { ZellijError } from "../errors.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;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
+export const defaultRunner = (cmd, args) => {
+    const res = spawnSync(cmd, args, { encoding: "utf8" });
+    return { status: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? (res.error?.message ?? "") };
+};
+/** The account services are installed for: the current user, or `runAs` when root. */
+export function serviceAccount(runAs, run = defaultRunner) {
+    const platform = process.platform;
+    if (platform !== "linux" && platform !== "darwin") {
+        throw new ZellijError("usage", `host services are for Linux and macOS (this is ${platform}); on Windows use serve --install`);
+    }
+    const me = userInfo();
+    const target = runAs?.trim();
+    if (!target || target === me.username) {
+        return { platform, user: me.username, uid: me.uid, gid: me.gid, home: process.env.HOME || homedir(), foreign: false };
+    }
+    if (me.uid !== 0) {
+        throw new ZellijError("usage", `--run-as ${target} needs root`);
+    }
+    const id = (flag) => {
+        const res = run("id", [flag, target]);
+        if (res.status !== 0)
+            throw new ZellijError("usage", `no such user ${target}`);
+        return Number(res.stdout.trim());
+    };
+    const home = platform === "darwin"
+        ? (run("dscl", [".", "-read", `/Users/${target}`, "NFSHomeDirectory"]).stdout.split(":").pop() ?? "").trim()
+        : (run("getent", ["passwd", target]).stdout.split(":")[5] ?? "").trim();
+    if (!home)
+        throw new ZellijError("usage", `cannot find the home of ${target}`);
+    return { platform, user: target, uid: id("-u"), gid: id("-g"), home, foreign: true };
+}
+/** Root installing for another account (`--run-as`). */
+function installingFor(account) {
+    return account.foreign && typeof process.geteuid === "function" && process.geteuid() === 0;
+}
+/**
+ * The argv prefix that runs a command as the account: `runuser` on Linux,
+ * `sudo -u` on macOS. Root writes into the account's home through it, so the
+ * kernel refuses what the account itself could not do (a symlink it planted
+ * towards a root-owned file, say) and new files are the account's own. (Not
+ * seteuid in this process: Node disables it on Linux while io_uring may be
+ * enabled, CVE-2024-22017.)
+ */
+export function accountArgv(account) {
+    return account.platform === "linux"
+        ? ["runuser", "-u", account.user, "--"]
+        : ["sudo", "-n", "-u", account.user, "-H", "--"];
+}
+function runAsAccount(account, argv, input) {
+    const [cmd, ...rest] = [...accountArgv(account), ...argv];
+    const res = spawnSync(cmd, rest, { input, encoding: "utf8" });
+    if (res.status !== 0) {
+        throw new ZellijError("failed", `${argv[0]} as ${account.user} failed: ${(res.stderr || res.error?.message || "").trim().slice(0, 300)}`);
+    }
+}
+/** Write a file in the account's home as the account (see accountArgv). */
+export function writeAccountFile(account, path, text, mode) {
+    if (!installingFor(account)) {
+        writeFileSync(path, text, { mode });
+        chmodSync(path, mode);
+        return;
+    }
+    runAsAccount(account, ["sh", "-c", 'umask 077 && cat > "$1" && chmod "$2" "$1"', "sh", path, mode.toString(8)], text);
+}
+function realFs(account) {
+    return {
+        write(path, text, mode) {
+            // LaunchDaemons are root's own directory; everything else is in the account's home.
+            if (path.startsWith("/Library/"))
+                writeFileSync(path, text, { mode });
+            else
+                writeAccountFile(account, path, text, mode);
+        },
+        remove(path) {
+            rmSync(path, { force: true });
+        },
+        exists(path) {
+            return existsSync(path);
+        },
+        mkdir(path) {
+            ensureAccountDir(account, path, 0o755);
+        },
+    };
+}
+function checkName(name) {
+    if (!NAME.test(name))
+        throw new ZellijError("bad_arg", `invalid service name ${JSON.stringify(name)}`);
+}
+// ------------------------------------------------------------------ systemd
+export function systemdUnitName(name, kind) {
+    return `zswarm-${name}.${kind === "interval" ? "timer" : "service"}`;
+}
+/** systemd quoting for one ExecStart word or Environment= value. */
+function sdQuote(word) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(word))
+        return word.replace(/%/g, "%%");
+    return `"${word.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%").replace(/\$/g, "$$$$")}"`;
+}
+export function systemdUnits(spec) {
+    checkName(spec.name);
+    const service = `zswarm-${spec.name}.service`;
+    const after = (spec.after ?? []).map((n) => `zswarm-${n}.service`);
+    const lines = ["[Unit]", `Description=${spec.description}`];
+    if (after.length)
+        lines.push(`After=${after.join(" ")}`, `Wants=${after.join(" ")}`);
+    lines.push("", "[Service]");
+    if (spec.kind === "daemon")
+        lines.push("Type=simple", "Restart=on-failure", "RestartSec=5");
+    else
+        lines.push("Type=oneshot");
+    if (spec.kind === "oneshot")
+        lines.push("RemainAfterExit=yes");
+    if (spec.killMode)
+        lines.push(`KillMode=${spec.killMode}`);
+    for (const [key, value] of Object.entries(spec.env ?? {}))
+        lines.push(`Environment=${sdQuote(`${key}=${value}`)}`);
+    if (spec.workingDir)
+        lines.push(`WorkingDirectory=${spec.workingDir}`);
+    lines.push(`ExecStart=${spec.argv.map(sdQuote).join(" ")}`);
+    if (spec.kind !== "interval")
+        lines.push("", "[Install]", "WantedBy=default.target");
+    const out = [{ file: service, text: lines.join("\n") + "\n" }];
+    if (spec.kind === "interval") {
+        const every = Math.max(30, Math.floor(spec.intervalSec ?? 120));
+        out.push({
+            file: `zswarm-${spec.name}.timer`,
+            text: [
+                "[Unit]",
+                `Description=${spec.description} (every ${every}s)`,
+                "",
+                "[Timer]",
+                "OnBootSec=3min",
+                `OnUnitActiveSec=${every}s`,
+                "",
+                "[Install]",
+                "WantedBy=timers.target",
+                "",
+            ].join("\n"),
+        });
+    }
+    return out;
+}
+function systemctl(host, args) {
+    const a = host.account;
+    return a.foreign
+        ? host.run("systemctl", ["--user", "-M", `${a.user}@.host`, ...args])
+        : host.run("systemctl", ["--user", ...args]);
+}
+/** Linger keeps the user's services running without a login session. */
+export function ensureLinger(host) {
+    const a = host.account;
+    const shown = host.run("loginctl", ["show-user", a.user, "-p", "Linger", "--value"]);
+    if (shown.stdout.trim() === "yes")
+        return { linger: true };
+    const res = host.run("loginctl", ["enable-linger", a.user]);
+    if (res.status === 0)
+        return { linger: true };
+    return {
+        linger: false,
+        note: `linger is off for ${a.user} (services stop at logout); run: sudo loginctl enable-linger ${a.user}`,
+    };
+}
+// ------------------------------------------------------------------ launchd
+export function launchdLabel(account, name) {
+    return account.foreign ? `zswarm.${account.user}.${name}` : `zswarm.${name}`;
+}
+function launchdPlistPath(account, label) {
+    return account.foreign
+        ? `/Library/LaunchDaemons/${label}.plist`
+        : join(account.home, "Library", "LaunchAgents", `${label}.plist`);
+}
+function xml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function launchdPlist(account, spec) {
+    checkName(spec.name);
+    const label = launchdLabel(account, spec.name);
+    const log = join(account.home, "Library", "Logs", "zswarm", `${spec.name}.log`);
+    const env = { HOME: account.home, USER: account.user, ...(spec.env ?? {}) };
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        `  <key>Label</key><string>${xml(label)}</string>`,
+    ];
+    if (account.foreign)
+        lines.push(`  <key>UserName</key><string>${xml(account.user)}</string>`);
+    lines.push(`  <key>WorkingDirectory</key><string>${xml(spec.workingDir ?? account.home)}</string>`, "  <key>ProgramArguments</key>", "  <array>", ...spec.argv.map((a) => `    <string>${xml(a)}</string>`), "  </array>", "  <key>EnvironmentVariables</key>", "  <dict>", ...Object.entries(env).map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`), "  </dict>", 
+    // A oneshot that forks (a Zellij server) must not take its children down on exit.
+    "  <key>AbandonProcessGroup</key><true/>");
+    if (spec.kind === "interval") {
+        lines.push(`  <key>StartInterval</key><integer>${Math.max(30, Math.floor(spec.intervalSec ?? 120))}</integer>`);
+    }
+    else {
+        lines.push("  <key>RunAtLoad</key><true/>");
+    }
+    if (spec.kind === "daemon") {
+        lines.push("  <key>KeepAlive</key><true/>", "  <key>ThrottleInterval</key><integer>10</integer>");
+    }
+    lines.push(`  <key>StandardOutPath</key><string>${xml(log)}</string>`, `  <key>StandardErrorPath</key><string>${xml(log)}</string>`, "</dict>", "</plist>", "");
+    return lines.join("\n");
+}
+function launchdDomain(host) {
+    const a = host.account;
+    if (a.foreign)
+        return "system";
+    const gui = `gui/${a.uid}`;
+    return host.run("launchctl", ["print", gui]).status === 0 ? gui : `user/${a.uid}`;
+}
+// ------------------------------------------------------------------ common
+/** Write, (re)load and start the services. Returns what it did, one line per unit. */
+export function installServices(host, specs) {
+    const fs = host.fs ?? realFs(host.account);
+    const a = host.account;
+    const lines = [];
+    const notes = [];
+    if (a.platform === "linux") {
+        const dir = join(a.home, ".config", "systemd", "user");
+        fs.mkdir(join(a.home, ".config"));
+        fs.mkdir(join(a.home, ".config", "systemd"));
+        fs.mkdir(dir);
+        const linger = ensureLinger(host);
+        if (linger.note)
+            notes.push(linger.note);
+        const enable = [];
+        for (const spec of specs) {
+            for (const unit of systemdUnits(spec))
+                fs.write(join(dir, unit.file), unit.text, 0o644);
+            enable.push(systemdUnitName(spec.name, spec.kind));
+        }
+        must(systemctl(host, ["daemon-reload"]), "systemctl --user daemon-reload");
+        for (const unit of enable) {
+            must(systemctl(host, ["enable", unit]), `enable ${unit}`);
+            // restart, not start: a reinstall must pick up changed arguments.
+            must(systemctl(host, ["restart", unit]), `start ${unit}`);
+            lines.push(`${unit} started`);
+        }
+        return { lines, notes };
+    }
+    const domain = launchdDomain(host);
+    fs.mkdir(join(a.home, "Library", "Logs", "zswarm"));
+    if (!a.foreign)
+        fs.mkdir(join(a.home, "Library", "LaunchAgents"));
+    if (domain.startsWith("user/")) {
+        notes.push(`no GUI login for ${a.user}: LaunchAgents load now but only return after a login; install from root with --run-as ${a.user} for a service that survives reboots`);
+    }
+    for (const spec of specs) {
+        const label = launchdLabel(a, spec.name);
+        const path = launchdPlistPath(a, label);
+        fs.write(path, launchdPlist(a, spec), 0o644);
+        host.run("launchctl", ["bootout", `${domain}/${label}`]);
+        must(host.run("launchctl", ["bootstrap", domain, path]), `launchctl bootstrap ${domain} ${label}`);
+        lines.push(`${label} loaded in ${domain}`);
+    }
+    return { lines, notes };
+}
+/** Stop and delete the services; missing ones are fine. */
+export function removeServices(host, specs) {
+    const fs = host.fs ?? realFs(host.account);
+    const a = host.account;
+    const lines = [];
+    if (a.platform === "linux") {
+        const dir = join(a.home, ".config", "systemd", "user");
+        for (const spec of specs) {
+            const unit = systemdUnitName(spec.name, spec.kind);
+            systemctl(host, ["disable", "--now", unit]);
+            if (spec.kind === "interval")
+                systemctl(host, ["stop", `zswarm-${spec.name}.service`]);
+            fs.remove(join(dir, `zswarm-${spec.name}.service`));
+            fs.remove(join(dir, `zswarm-${spec.name}.timer`));
+            lines.push(`${unit} removed`);
+        }
+        systemctl(host, ["daemon-reload"]);
+        return lines;
+    }
+    const domain = launchdDomain(host);
+    for (const spec of specs) {
+        const label = launchdLabel(a, spec.name);
+        host.run("launchctl", ["bootout", `${domain}/${label}`]);
+        fs.remove(launchdPlistPath(a, label));
+        lines.push(`${label} removed`);
+    }
+    return lines;
+}
+export function serviceStates(host, specs) {
+    const a = host.account;
+    if (a.platform === "linux") {
+        return specs.map((spec) => {
+            const unit = systemdUnitName(spec.name, spec.kind);
+            const state = systemctl(host, ["is-active", unit]).stdout.trim() || "unknown";
+            return { name: spec.name, unit, state, active: state === "active" };
+        });
+    }
+    const domain = launchdDomain(host);
+    return specs.map((spec) => {
+        const label = launchdLabel(a, spec.name);
+        const res = host.run("launchctl", ["print", `${domain}/${label}`]);
+        if (res.status !== 0)
+            return { name: spec.name, unit: label, state: "not loaded", active: false };
+        const state = /^\s*state = (.+)$/m.exec(res.stdout)?.[1]?.trim() ?? "loaded";
+        // Oneshot and interval jobs sit "not running" between runs; loaded is up for them.
+        const active = spec.kind === "daemon" ? state === "running" : true;
+        return { name: spec.name, unit: label, state, active };
+    });
+}
+function must(res, what) {
+    if (res.status !== 0) {
+        throw new ZellijError("failed", `${what} failed: ${(res.stderr || res.stdout).trim().slice(0, 300)}`);
+    }
+}
+/** Create dir and any missing parents, owned by the account when installing for it. */
+export function ensureAccountDir(account, dir, mode = 0o700) {
+    const missing = [];
+    for (let d = dir; d && d !== "/" && !existsSync(d); d = d.slice(0, d.lastIndexOf("/")) || "/")
+        missing.unshift(d);
+    for (const d of missing) {
+        if (installingFor(account))
+            runAsAccount(account, ["mkdir", "-m", mode.toString(8), d]);
+        else
+            mkdirSync(d, { mode });
+    }
+}
+/** Write a mode-600 file for the account, creating its directory (700) as needed. */
+export function writeSecretFile(account, path, text) {
+    ensureAccountDir(account, path.slice(0, path.lastIndexOf("/")));
+    writeAccountFile(account, path, text, 0o600);
+}
+export function readSecretFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/host/slot.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `zswarm slot` runs the bundled slot.py: Node has no flock(2), and the
+ * slot's guarantees (locks freed by the kernel when the holder dies,
+ * close-on-exec so leftover daemons never hold a slot) need it. The script
+ * also runs on its own; `zswarm slot --path` prints where it is.
+ */
+export declare function slotScriptPath(): string;
+/** The Python interpreter slot.py runs under: ZSWARM_PYTHON, else python3 (py -3 on Windows). */
+export declare function findPython(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string[] | null;
+/** Run slot.py with argv, forwarding stdio and signals; resolves to its exit code. */
+export declare function runSlot(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/host/slot.js

@@ -0,0 +1,74 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * `zswarm slot` runs the bundled slot.py: Node has no flock(2), and the
+ * slot's guarantees (locks freed by the kernel when the holder dies,
+ * close-on-exec so leftover daemons never hold a slot) need it. The script
+ * also runs on its own; `zswarm slot --path` prints where it is.
+ */
+export function slotScriptPath() {
+    return fileURLToPath(new URL("../../assets/slot.py", import.meta.url));
+}
+/** The Python interpreter slot.py runs under: ZSWARM_PYTHON, else python3 (py -3 on Windows). */
+export function findPython(env = process.env, platform = process.platform) {
+    const explicit = env.ZSWARM_PYTHON?.trim();
+    if (explicit)
+        return [explicit];
+    const candidates = platform === "win32" ? [["py", "-3"], ["python"], ["python3"]] : [["python3"]];
+    for (const cmd of candidates) {
+        const probe = spawnSync(cmd[0], [...cmd.slice(1), "-c", "import sys; sys.exit(sys.version_info < (3, 9))"], {
+            env,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        if (probe.status === 0)
+            return cmd;
+    }
+    return null;
+}
+/** Run slot.py with argv, forwarding stdio and signals; resolves to its exit code. */
+export async function runSlot(argv, env = process.env) {
+    const script = slotScriptPath();
+    if (argv[0] === "--path") {
+        process.stdout.write(`${script}\n`);
+        return 0;
+    }
+    if (!existsSync(script)) {
+        process.stderr.write(`slot: ${script} is missing from this install\n`);
+        return 2;
+    }
+    const python = findPython(env);
+    if (!python) {
+        process.stderr.write("slot: needs Python 3.9+ (python3, or set ZSWARM_PYTHON)\n");
+        return 2;
+    }
+    const child = spawn(python[0], [...python.slice(1), script, ...argv], { env, stdio: "inherit" });
+    const forward = (signal) => () => {
+        child.kill(signal);
+    };
+    const handlers = ["SIGINT", "SIGTERM", "SIGHUP"].map((sig) => {
+        const handler = forward(sig);
+        process.on(sig, handler);
+        return [sig, handler];
+    });
+    try {
+        return await new Promise((resolve) => {
+            child.on("error", (err) => {
+                process.stderr.write(`slot: ${err.message}\n`);
+                resolve(2);
+            });
+            child.on("exit", (code, signal) => {
+                resolve(code ?? (signal ? 128 + (signalNumber(signal) ?? 1) : 1));
+            });
+        });
+    }
+    finally {
+        for (const [sig, handler] of handlers)
+            process.off(sig, handler);
+    }
+}
+function signalNumber(signal) {
+    const table = { SIGHUP: 1, SIGINT: 2, SIGKILL: 9, SIGTERM: 15 };
+    return table[signal];
+}

package/dist/index.d.ts

@@ -29,3 +29,10 @@ export type { DispatchDeps, OpsResult, ServeInstallDeps } from "./ops/types.js";
 export { DEFAULT_DOCTOR_TIMEOUT_MS, DOCTOR_FAILED_CODE, DOCTOR_SCOPE_FIELD, DOCTOR_SCOPE_HOST, DOCTOR_TAILSCALE_MAX_MS, HOST_REPORT_INCOMPLETE_CODE, HOST_REPORT_INVALID_CODE, doctorOp, inspectDoctorHost, coverHostReport, hostDoctorRequest, isRequiredFailure, mergeHostReply, type DoctorCheck, type DoctorCheckScope, type DoctorCheckState, type DoctorReport, type DoctorRoute, type HostInspectInput, } from "./ops/doctor.js";
 export { normalizeKey, normalizeKeys, tokenizeCommand } from "./keys.js";
 export { cliUsage, mcpInputSchema, parseCliArgv, MCP_TOOL_DESCRIPTION, OP_NAMES, PARAMS, TARGET_OPS, type OpName, type ParamSpec, type ParamType, } from "./schema.js";
+export { HOST_COMMANDS, hostUsage, parseHostArgs, runHostCommand } from "./host/cli.js";
+export { findPython, runSlot, slotScriptPath } from "./host/slot.js";
+export { installServeService, serveServiceName, serveServiceSpec, serveTokenFromEnv, serveTokenPath, uninstallServeService, SERVE_AWAIT_SESSION_ENV, SERVE_TOKEN_FILE_ENV, type ServeServiceInput, } from "./host/serve-service.js";
+export { accountArgv, installServices, launchdLabel, launchdPlist, removeServices, serviceAccount, serviceStates, systemdUnitName, systemdUnits, writeAccountFile, type Runner, type ServiceAccount, type ServiceHost, type ServiceKind, type ServiceSpec, type ServiceState, } from "./host/services.js";
+export { crewCheck, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, parseEnvFile, CREW_UNIT_ENV, CREW_WATCH_SEC, type CrewDeps, type CrewUpInput, } from "./host/crew.js";
+export { deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, prepareRelay, pruneRelays, relayLoop, relaysDir, runRelayDir, scrubRelayToken, startRelay, waitForRelay, type RelayConfig, type RelayDeps, type RelayStartInput, type RelayStatus, } from "./host/relay.js";
+export { hostChecks, hostDoctor, hostInstall, hostInstallArgs, hostScriptPath, parseHostReport, type HostCheck, type HostDoctorInput, type HostInstallInput, type SshRunner, } from "./host/host.js";

package/dist/index.js

@@ -27,3 +27,10 @@ export { normalizeScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT
 export { DEFAULT_DOCTOR_TIMEOUT_MS, DOCTOR_FAILED_CODE, DOCTOR_SCOPE_FIELD, DOCTOR_SCOPE_HOST, DOCTOR_TAILSCALE_MAX_MS, HOST_REPORT_INCOMPLETE_CODE, HOST_REPORT_INVALID_CODE, doctorOp, inspectDoctorHost, coverHostReport, hostDoctorRequest, isRequiredFailure, mergeHostReply, } from "./ops/doctor.js";
 export { normalizeKey, normalizeKeys, tokenizeCommand } from "./keys.js";
 export { cliUsage, mcpInputSchema, parseCliArgv, MCP_TOOL_DESCRIPTION, OP_NAMES, PARAMS, TARGET_OPS, } from "./schema.js";
+export { HOST_COMMANDS, hostUsage, parseHostArgs, runHostCommand } from "./host/cli.js";
+export { findPython, runSlot, slotScriptPath } from "./host/slot.js";
+export { installServeService, serveServiceName, serveServiceSpec, serveTokenFromEnv, serveTokenPath, uninstallServeService, SERVE_AWAIT_SESSION_ENV, SERVE_TOKEN_FILE_ENV, } from "./host/serve-service.js";
+export { accountArgv, installServices, launchdLabel, launchdPlist, removeServices, serviceAccount, serviceStates, systemdUnitName, systemdUnits, writeAccountFile, } from "./host/services.js";
+export { crewCheck, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, parseEnvFile, CREW_UNIT_ENV, CREW_WATCH_SEC, } from "./host/crew.js";
+export { deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, prepareRelay, pruneRelays, relayLoop, relaysDir, runRelayDir, scrubRelayToken, startRelay, waitForRelay, } from "./host/relay.js";
+export { hostChecks, hostDoctor, hostInstall, hostInstallArgs, hostScriptPath, parseHostReport, } from "./host/host.js";

package/dist/ops/dispatch.js

@@ -26,6 +26,7 @@ import { DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLogon, uninstallServeLogo
 import { serveCallTimeout, } from "./serve.js";
 import { doctorOp } from "./doctor.js";
 import { forwardServe } from "./serve-tunnel.js";
+import { installServeService, uninstallServeService } from "../host/serve-service.js";
 /**
  * Per-invocation routing from `--local` / `--ssh`. `--local` clears both SSH
  * and serve (and remote IPC). `--ssh` sets the destination for this call and
@@ -114,12 +115,19 @@ async function resolveTarget(client, args, state, clock, env, policy, op, signal
         }
         catch { /* An absent title/command/ID gets a fresh direct observation. */ }
     }
-    const until = Math.min(budget.deadline, clock.now() + observeMs);
+    // observeMs bounds the retries for an absent pane, not the first listing:
+    // a loaded Zellij can take seconds to list, and that is not absence. The
+    // retry window starts once the first listing is in.
+    let until = Number.POSITIVE_INFINITY;
     let pane;
     let fresh = isTrue(args.fresh) || Boolean(op);
     for (;;) {
-        const left = observeMs === 0 ? budget.require() : Math.min(budget.require(), Math.max(1, until - clock.now()));
+        const left = until === Number.POSITIVE_INFINITY || observeMs === 0
+            ? budget.require()
+            : Math.min(budget.require(), Math.max(1, until - clock.now()));
         panes ??= await client.listPanes(session, left, { fresh });
+        if (until === Number.POSITIVE_INFINITY)
+            until = Math.min(budget.deadline, clock.now() + observeMs);
         throwIfAborted(signal);
         try {
             pane = client.resolvePane(panes, to);
@@ -184,6 +192,21 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 min: 1,
                 max: 900_000,
             });
+            const servePlatform = deps.serveInstall?.platform ?? process.platform;
+            if (servePlatform !== "win32" && (isTrue(args.clear) || isTrue(args.install))) {
+                // Linux and macOS: a systemd user unit or launchd job (host/serve-service).
+                const input = {
+                    listen: typeof args.listen === "string" ? args.listen : undefined,
+                    session: optionalString(args.session) ?? undefined,
+                    runAs: optionalString(args.runAs) ?? undefined,
+                    timeoutMs,
+                    env,
+                    ...deps.serveService,
+                };
+                return isTrue(args.clear)
+                    ? { ok: true, data: uninstallServeService(input) }
+                    : { ok: true, data: await installServeService(input) };
+            }
             if (isTrue(args.clear)) {
                 const cleared = await uninstallServeLogon({
                     platform: deps.serveInstall?.platform ?? process.platform,

package/dist/ops/types.d.ts

@@ -15,6 +15,7 @@ export type OpsResult = ({
 };
 import type { GitClient } from "../git.js";
 import type { Policy } from "../policy.js";
+import type { ServeServiceInput } from "../host/serve-service.js";
 import type { StateStore } from "../state.js";
 /** Injectable clock, git, state, and policy so timing/IO ops stay testable. */
 export type DispatchDeps = {
@@ -46,6 +47,8 @@ export type DispatchDeps = {
     networkInterfaces?: () => NodeJS.Dict<import("node:os").NetworkInterfaceInfo[]>;
     /** Narrow injectables for Windows `serve --install` / `--clear`. */
     serveInstall?: ServeInstallDeps;
+    /** Linux/macOS serve --install/--clear seams (tests). */
+    serveService?: Partial<ServeServiceInput>;
 };
 export type ServePowerShellResult = {
     code: number;