@zswarm/core 0.2.4 → 0.2.6

package/dist/host/crew.js

@@ -1,14 +1,15 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { posix } from "node:path";
+import { dirname, posix, win32 } 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 { closeCrewClient, crewClientCommand, crewClientMarker, crewTaskCommand, defaultPowerShellExec, ensureCrewClient, inspectCrewTasks, installCrewTasks, removeCrewTasks, } from "./crew-windows.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.
+// Linux and macOS accounts carry POSIX paths even when this code runs (in
+// tests) on Windows; a Windows crew account carries native Windows paths.
 const { join } = posix;
 /**
  * `zswarm crew`: keep a Zellij session built from a layout running on a host.
@@ -23,12 +24,37 @@ const { join } = posix;
  *   status  services, session and panes
  *   down    remove the services and kill the session
  *
+ * On Windows there is no systemd or launchd: `up` registers two Scheduled
+ * Tasks under `\zswarm\` (a start task and a two-minute watchdog running
+ * `crew check`) and the start path keeps an attached client in a minimized
+ * console window, because a background-only Windows session renders empty
+ * panes and drops pasted input.
+ *
  * 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;
+/** The Windows client window: real PowerShell, or the test seam. */
+function windowsClient(deps, env) {
+    if (deps.client)
+        return deps.client;
+    const runPowerShell = deps.runPowerShell ?? defaultPowerShellExec;
+    const launch = deps.launch ?? resolveServeCliLaunch({ env });
+    return {
+        ensure: (session) => ensureCrewClient({
+            session,
+            clientCommand: crewClientCommand({ session, launch }),
+            runPowerShell,
+        }),
+        close: async (session) => (await closeCrewClient({ session, runPowerShell })).closed,
+    };
+}
+/** A task row shaped like the systemd/launchd `services` entries. */
+function taskStateView(task) {
+    return { name: task.name, unit: task.path, state: task.state, active: task.active };
+}
 /** 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) {
@@ -38,8 +64,13 @@ export function checkCrewSession(session) {
     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);
+    // A Windows account's home and state dir are native paths; joining them with
+    // posix.join would leave a mixed `C:\Users\x/.zswarm` for Zellij to open.
+    const path = account.platform === "win32" ? win32 : posix;
+    const base = !account.foreign && env.ZSWARM_STATE_DIR?.trim()
+        ? defaultStateDir(env)
+        : path.join(account.home, ".zswarm");
+    return path.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) {
@@ -72,7 +103,7 @@ export function parseEnvFile(text) {
     return out;
 }
 function readCrewFiles(dir) {
-    const meta = join(dir, "crew.json");
+    const meta = crewFile(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"));
@@ -102,15 +133,25 @@ 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 ?? "" };
 }
+/**
+ * Zellij, sharing this process's console. `attach --create` needs a real
+ * terminal — with a pipe on stdin it exits 0 having created nothing, which is
+ * exactly the "session that never renders" a Windows crew must avoid.
+ */
+function defaultZellijInteractive(args, env) {
+    const res = spawnSync(resolveZellijBinary(env), args, { env, stdio: "inherit" });
+    return { status: res.status ?? 1, stdout: "", stderr: res.error?.message ?? "" };
+}
 function crewEnv(dir, files, env) {
-    const extra = files.env ? parseEnvFile(readFileSync(join(dir, files.env), "utf8")) : {};
+    const extra = files.env ? parseEnvFile(readFileSync(crewFile(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 account = deps.account ?? serviceAccount(undefined);
+    const dir = deps.dir ?? crewDir(account, checkCrewSession(session), env0);
     const files = readCrewFiles(dir);
     const env = crewEnv(dir, files, env0);
     const zellij = deps.zellij ?? defaultZellij;
@@ -118,10 +159,37 @@ export async function crewStart(session, deps = {}) {
     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)] : [];
+    const config = files.config ? ["--config", crewFile(dir, files.config)] : [];
+    if (account.platform === "win32") {
+        // Windows: a session created with `attach --create-background` renders
+        // empty panes and drops pasted input, so the session is created BY an
+        // attached client instead — a minimized console window running
+        // `zellij --layout ... attach --create`, which `crew client` starts. That
+        // window is also what the watchdog reopens when it dies.
+        const client = windowsClient(deps, env);
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            zellij(["delete-session", session], env); // clears only a dead session of this name
+            await client.close(session); // a window left over from the previous attempt
+            const opened = await client.ensure(session);
+            log(`client window ${opened.opened ? "opened" : "already open"} for ${session}`);
+            for (let i = 0; i < 30 && !(await sessions(env)).includes(session); i++)
+                await sleep(1_000);
+            await sleep(3_000);
+            if ((await panes(session, env)).some((p) => p.title === files.first)) {
+                log(`session ${session} up in window ${crewClientMarker(session)} (attempt ${attempt})`);
+                return 0;
+            }
+            log(`session ${session} came up without its layout (attempt ${attempt}); recreating`);
+            zellij(["kill-session", session], env);
+            await client.close(session);
+            await sleep(1_000);
+        }
+        log(`session ${session} never took its layout`);
+        return 1;
+    }
     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);
+        zellij([...config, "--layout", crewFile(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);
@@ -136,16 +204,63 @@ export async function crewStart(session, deps = {}) {
     log(`session ${session} never took its layout`);
     return 1;
 }
+/**
+ * Zellij's own client variables. A client started from inside a pane inherits
+ * `ZELLIJ=0`, `ZELLIJ_SESSION_NAME`, ...; a nested client then exits without
+ * creating anything. The console window is opened from whatever process asked
+ * for the crew (an agent pane, a scheduled task), so strip them all.
+ */
+const ZELLIJ_CLIENT_ENV = /^ZELLIJ(_|$)/;
+function withoutZellijClientEnv(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (ZELLIJ_CLIENT_ENV.test(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * `crew client`: what the minimized console window runs. It reads the crew dir
+ * (so an env file's variables reach Zellij without being written into a task or
+ * a command line) and attaches with `--create`, which is what makes a Windows
+ * session render — a background-only session leaves pane grids empty.
+ */
+export function crewClient(session, deps = {}) {
+    const env0 = deps.env ?? process.env;
+    const account = deps.account ?? serviceAccount(undefined);
+    const dir = deps.dir ?? crewDir(account, checkCrewSession(session), env0);
+    const files = readCrewFiles(dir);
+    const env = withoutZellijClientEnv(crewEnv(dir, files, env0));
+    const args = [
+        ...(files.config ? ["--config", crewFile(dir, files.config)] : []),
+        "--layout", crewFile(dir, files.layout),
+        "attach", "--create", session,
+    ];
+    // OSC 0 titles the console window; the marker is how status and down find it.
+    // Only on a real console — a piped run (tests, logs) has no window to title.
+    if (process.stdout.isTTY)
+        process.stdout.write(`\u001b]0;${crewClientMarker(session)}\u0007`);
+    return (deps.zellij ?? defaultZellijInteractive)(args, env).status;
+}
 /** 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 account = deps.account ?? serviceAccount(undefined);
+    const dir = deps.dir ?? crewDir(account, 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)) {
+        if (account.platform === "win32") {
+            // The session surviving is not enough on Windows: without the attached
+            // client window its panes render empty, so the watchdog reopens it.
+            const opened = await windowsClient(deps, env).ensure(session);
+            if (opened.opened)
+                log(`client window reopened for ${session}`);
+        }
         return 0;
     }
     log(`session ${session} is gone or lost its layout; restarting`);
@@ -159,8 +274,26 @@ export async function crewCheck(session, deps = {}) {
     }
     return await crewStart(session, deps);
 }
+/** A file inside a crew dir, which is a Windows path for a win32 account. */
+function crewFile(dir, name) {
+    return dir.includes("\\") ? win32.join(dir, name) : join(dir, name);
+}
+/**
+ * The env a Windows crew task action reproduces. Not the whole caller env (it
+ * can hold tokens) and not PATH (the interactive task inherits the user's, and
+ * a host PATH would not fit in a Windows command line).
+ */
+function crewTaskEnv(env) {
+    const out = {};
+    for (const key of ["ZSWARM_BIN", "ZSWARM_STATE_DIR"]) {
+        const value = env[key]?.trim();
+        if (value)
+            out[key] = value;
+    }
+    return out;
+}
 function copyForAccount(account, from, to, secret) {
-    ensureAccountDir(account, to.slice(0, to.lastIndexOf("/")));
+    ensureAccountDir(account, dirname(to));
     if (secret) {
         writeSecretFile(account, to, readFileSync(from, "utf8"));
         return;
@@ -203,7 +336,7 @@ export function crewServiceSpecs(input) {
         },
     ];
 }
-export function crewUp(input) {
+export async function crewUp(input) {
     const env = input.env ?? process.env;
     const run = input.run ?? defaultRunner;
     const account = input.account ?? serviceAccount(input.runAs, run);
@@ -219,17 +352,42 @@ export function crewUp(input) {
     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);
+    copy(account, input.layout, crewFile(dir, "layout.kdl"), false);
     if (input.config) {
-        copy(account, input.config, join(dir, "config.kdl"), false);
+        copy(account, input.config, crewFile(dir, "config.kdl"), false);
         files.config = "config.kdl";
     }
     if (input.envFile) {
-        copy(account, input.envFile, join(dir, "env"), true);
+        copy(account, input.envFile, crewFile(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`);
+    (input.writeMeta ?? writeSecretFile)(account, crewFile(dir, "crew.json"), `${JSON.stringify(files, null, 1)}\n`);
+    if (account.platform === "win32") {
+        // Windows has no systemd/launchd: two Scheduled Tasks (a start task and a
+        // two-minute watchdog) plus the minimized client window the start task
+        // opens, because a background-only session renders empty panes.
+        const taskEnv = crewTaskEnv(env);
+        const installed = await installCrewTasks({
+            session,
+            startCommand: crewTaskCommand({ launch, mode: "start", session, env: taskEnv }),
+            watchCommand: crewTaskCommand({ launch, mode: "check", session, env: taskEnv }),
+            runPowerShell: input.runPowerShell ?? defaultPowerShellExec,
+        });
+        const states = installed.tasks.map(taskStateView);
+        return {
+            session,
+            user: account.user,
+            dir,
+            firstPane: first,
+            services: states,
+            ready: states.every((s) => s.active),
+            tasks: installed.tasks,
+            clientWindow: installed.client,
+            actions: installed.lines,
+            notes: installed.notes,
+        };
+    }
     const specs = crewServiceSpecs({ account, session, launch, env });
     const done = installServices({ account, run, fs: input.fs }, specs);
     const states = serviceStates({ account, run }, specs);
@@ -249,14 +407,28 @@ export async function crewStatus(input) {
     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 };
+    const out = { session, user: account.user };
     if (account.foreign) {
+        const specs = crewServiceSpecs({ account, session, launch: { execPath: "", scriptPath: "" }, env });
+        out.services = serviceStates({ account, run }, specs);
         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"))
+    let client = null;
+    if (account.platform === "win32") {
+        const inspected = await inspectCrewTasks({
+            session,
+            runPowerShell: input.runPowerShell ?? defaultPowerShellExec,
+        });
+        out.services = inspected.tasks.map(taskStateView);
+        client = inspected.client;
+        out.clientWindow = inspected.client;
+    }
+    else {
+        const specs = crewServiceSpecs({ account, session, launch: { execPath: "", scriptPath: "" }, env });
+        out.services = serviceStates({ account, run }, specs);
+    }
+    const files = existsSync(crewFile(crewDir(account, session, env), "crew.json"))
         ? readCrewFiles(crewDir(account, session, env))
         : undefined;
     const live = (await (input.deps?.sessions ?? defaultSessions)(env)).includes(session);
@@ -267,17 +439,34 @@ export async function crewStatus(input) {
     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);
+    out.healthy =
+        out.services.every((s) => s.active) &&
+            live &&
+            out.layoutTook !== false &&
+            panes.every((p) => !p.exited) &&
+            (client ? client.present : true);
     if (live && exited) {
         out.note = `an exited session named ${session} is also listed (resurrectable); remove it with zswarm sessions --prune-exited`;
     }
     return out;
 }
-export function crewDown(input) {
+export async 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);
+    if (account.platform === "win32") {
+        const runPowerShell = input.runPowerShell ?? defaultPowerShellExec;
+        const removed = await removeCrewTasks({ session, runPowerShell });
+        const lines = [...removed.lines];
+        const closed = await closeCrewClient({ session, runPowerShell });
+        lines.push(closed.closed.length > 0
+            ? `client window closed (pids ${closed.closed.join(", ")})`
+            : "no client window was open");
+        const kill = run(resolveZellijBinary(env), ["kill-session", session]);
+        lines.push(kill.status === 0 ? `session ${session} killed` : `session ${session} was not running`);
+        return { session, user: account.user, actions: lines };
+    }
     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.

package/dist/host/services.d.ts

@@ -2,9 +2,12 @@
  * 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.
+ * LaunchDaemon that runs as that user, for accounts that never log in). On
+ * Windows there is no systemd or launchd here: `serviceAccount` returns the
+ * signed-in user (`platform: "win32"`, uid/gid 0) so crew can install a
+ * scheduled task instead, and `--run-as` is refused. 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. */
@@ -31,7 +34,7 @@ export type ServiceSpec = {
     workingDir?: string;
 };
 export type ServiceAccount = {
-    platform: "linux" | "darwin";
+    platform: "linux" | "darwin" | "win32";
     user: string;
     uid: number;
     gid: number;

package/dist/host/services.js

@@ -1,10 +1,10 @@
 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 { dirname, 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.
+// Linux and macOS accounts carry POSIX paths even when this code runs (in
+// tests) on Windows; a Windows crew account carries native Windows paths.
 const { join } = posix;
 const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
 export const defaultRunner = (cmd, args) => {
@@ -22,6 +22,12 @@ function hostSleep(host, ms) {
 /** 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 === "win32") {
+        if (runAs?.trim()) {
+            throw new ZellijError("usage", "--run-as is Linux and macOS only; a Windows crew task runs as the signed-in user");
+        }
+        return { platform: "win32", user: userInfo().username, uid: 0, gid: 0, home: process.env.USERPROFILE || homedir(), foreign: false };
+    }
     if (platform !== "linux" && platform !== "darwin") {
         throw new ZellijError("usage", `host services are for Linux and macOS (this is ${platform}); on Windows use serve --install`);
     }
@@ -72,6 +78,10 @@ function runAsAccount(account, argv, input) {
 }
 /** Write a file in the account's home as the account (see accountArgv). */
 export function writeAccountFile(account, path, text, mode) {
+    if (account.platform === "win32") {
+        writeFileSync(path, text);
+        return;
+    }
     if (!installingFor(account)) {
         writeFileSync(path, text, { mode });
         chmodSync(path, mode);
@@ -416,6 +426,10 @@ function must(res, what) {
 }
 /** Create dir and any missing parents, owned by the account when installing for it. */
 export function ensureAccountDir(account, dir, mode = 0o700) {
+    if (account.platform === "win32") {
+        mkdirSync(dir, { recursive: true });
+        return;
+    }
     const missing = [];
     for (let d = dir; d && d !== "/" && !existsSync(d); d = d.slice(0, d.lastIndexOf("/")) || "/")
         missing.unshift(d);
@@ -428,7 +442,7 @@ export function ensureAccountDir(account, dir, mode = 0o700) {
 }
 /** 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("/")));
+    ensureAccountDir(account, dirname(path));
     writeAccountFile(account, path, text, 0o600);
 }
 export function readSecretFile(path) {

package/dist/index.d.ts

@@ -29,11 +29,11 @@ export type { RoutingContext } from "./ops/routing.js";
 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 { cliUsage, commandUsage, wantsHelp, extractOp, 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 { crewCheck, crewClient, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, parseEnvFile, CREW_UNIT_ENV, CREW_WATCH_SEC, type CrewDeps, type CrewUpInput, } from "./host/crew.js";
 export { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, runRelayDir, scrubRelayToken, startRelay, waitForRelay, type RelayAdminDeps, type RelayCancelResult, type RelayConfig, type RelayDeps, type RelayJob, type RelayJobRunner, type RelayRow, 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,11 +27,11 @@ export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STA
 export { normalizeScreen, unfoldScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.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, } 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 { cliUsage, commandUsage, wantsHelp, extractOp, 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 { crewCheck, crewClient, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, parseEnvFile, CREW_UNIT_ENV, CREW_WATCH_SEC, } from "./host/crew.js";
 export { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, 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/schema.d.ts

@@ -12,6 +12,8 @@ export type ParamSpec = {
     type: ParamType;
     /** CLI flags; empty means the parameter is reachable through MCP only. */
     flags: string[];
+    /** Ops this flag belongs to; omitted means it applies to every op (routing/global flags). */
+    ops?: readonly OpName[];
     /** Repeatable flags collect into an array (`--key a --key b`). */
     repeat?: boolean;
     /** Local CLI preprocessing, excluded from the MCP protocol. */
@@ -24,4 +26,29 @@ export declare const PARAMS: readonly ParamSpec[];
 export declare function mcpInputSchema(): Record<string, unknown>;
 export declare const MCP_TOOL_DESCRIPTION: string;
 export declare function cliUsage(): string;
+/**
+ * True when argv asks for help: `--help` or `-h` as a flag of its own, not the
+ * value of a flag that takes one (`--body -h` sends "-h") and not after `--`.
+ */
+export declare function wantsHelp(argv: readonly string[]): boolean;
+/**
+ * Per-command help for `zswarm <op> --help`: the usage line, the positional
+ * shorthand, and only the flags whose `ops` include this op. A flag without
+ * `ops` (session, --local, --ssh, --fresh, --serve) applies to every op.
+ * Render from the same PARAMS table that parses the flags, so they cannot drift.
+ */
+export declare function commandUsage(op: OpName): string;
+/** Turn argv (without the op) into dispatch args, driven by PARAMS. */
+/**
+ * Pull the op out of argv, tolerating flags before it.
+ *
+ * The op normally comes first. When it does not — `zswarm --session crew list`
+ * — the first token is a flag, and taking argv[0] blindly reported the flag as
+ * an unknown op. Only positions that already errored are affected: if argv[0]
+ * is a real op it wins, so `send reviewer list` still sends the word "list".
+ */
+export declare function extractOp(argv: string[]): {
+    op: string;
+    rest: string[];
+};
 export declare function parseCliArgv(argv: string[]): Record<string, unknown>;