@zswarm/core 0.6.0 → 0.8.0

package/dist/exec.d.ts

@@ -40,7 +40,7 @@ export type SshTarget = {
     /** Concrete IPC temp, or `auto` to read `--server` off a live zellij process. */
     tmp?: string;
     /** `interactive` runs the CLI in the Windows desktop session (schtasks /IT). */
-    mode?: "ssh" | "interactive";
+    mode?: "ssh" | "interactive" | "gate";
     remoteShell?: "cmd" | "sh";
 };
 export declare function quoteRemoteArg(arg: string, shell: RemoteShell): string;

package/dist/host/cli.js

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
 import { ZellijError } from "../errors.js";
-import { createStateStore } from "../state.js";
+import { createStateStore, defaultStateDir } from "../state.js";
 import { crewCheck, crewClient, crewDown, crewStart, crewStatus, crewUp } from "./crew.js";
+import { GATE_USAGE, gateCommand } from "./gate.js";
 import { hostDoctor, hostInstall, hostInstallArgs, hostScriptPath } from "./host.js";
 import { listLeases } from "./lease.js";
 import { cancelAllTo, cancelRelay, listRelays, pruneRelays, runRelayDir, startRelay, waitForRelay } from "./relay.js";
@@ -151,6 +152,10 @@ async function relay(argv) {
         if (flags["--json"] === true)
             return json(() => ({ leases }));
         process.stdout.write(`${leaseTable(leases)}\n`);
+        if (leases.length === 0) {
+            // A tool that runs zswarm with its own ZSWARM_STATE_DIR keeps its leases there.
+            process.stderr.write(`no live leases in ${defaultStateDir()}; set ZSWARM_STATE_DIR to read another state directory\n`);
+        }
         return 0;
     }
     const cancelId = str(flags["--cancel"]);
@@ -284,6 +289,10 @@ const COMMANDS = {
         ].join("\n"),
         run: host,
     },
+    gate: {
+        usage: GATE_USAGE,
+        run: (argv) => gateCommand(argv, (a) => parseHostArgs(a)),
+    },
 };
 export const HOST_COMMANDS = Object.keys(COMMANDS);
 export function hostUsage() {

package/dist/host/gate.d.ts

@@ -0,0 +1,25 @@
+import type { DispatchDeps, OpsResult } from "../ops/types.js";
+type Dispatch = (args: Record<string, unknown>, injected: undefined, deps: DispatchDeps) => Promise<OpsResult>;
+/**
+ * The forced command behind a gate key: check one request against gate.json,
+ * then send locally. The sender's origin keeps its session and pane, but its
+ * host is the key-bound id and it is stamped `via=gate`.
+ */
+export declare function runGate(input: {
+    id: string;
+    request: string;
+    env?: NodeJS.ProcessEnv;
+    dispatch?: Dispatch;
+    now?: () => Date;
+}): Promise<OpsResult>;
+type Flags = Record<string, string | true>;
+export declare function gateAllow(id: string, flags: Flags, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export declare function gateRevoke(id: string, flags: Flags, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export declare function gateList(flags: Flags, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export declare const GATE_USAGE: string;
+/** `zswarm gate …`; resolves to the exit code. */
+export declare function gateCommand(argv: string[], parse: (argv: string[]) => {
+    flags: Flags;
+    rest: string[];
+}): Promise<number>;
+export {};

package/dist/host/gate.js

@@ -0,0 +1,168 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ZellijError } from "../errors.js";
+import { dispatchZswarm } from "../ops/dispatch.js";
+import { GATE_MAX_REQUEST_BYTES, allowInConfig, authorizeGateRequest, defaultAuthorizedKeysPath, gateConfigPath, gateForcedCommand, gateKeyLine, idIsAllowed, listGateKeys, loadGateConfig, removeGateKey, revokeInConfig, saveGateConfig, upsertGateKey, validateGateId, writeAuthorizedKeys, } from "../ops/gate.js";
+import { defaultStateDir } from "../state.js";
+const RESERVED = new Set(["allow", "revoke", "list", "help"]);
+/**
+ * The forced command behind a gate key: check one request against gate.json,
+ * then send locally. The sender's origin keeps its session and pane, but its
+ * host is the key-bound id and it is stamped `via=gate`.
+ */
+export async function runGate(input) {
+    const env = input.env ?? process.env;
+    const dispatch = input.dispatch ?? ((a, i, d) => dispatchZswarm(a, i, d));
+    const at = (input.now ?? (() => new Date()))().toISOString();
+    let result;
+    let target = "";
+    try {
+        const id = validateGateId(input.id);
+        const allowed = authorizeGateRequest(loadGateConfig(gateConfigPath(env)), id, input.request);
+        target = `${allowed.session}/${allowed.to}`;
+        const a = allowed.args;
+        result = await dispatch({
+            op: "send",
+            session: allowed.session,
+            to: allowed.to,
+            body: a.body,
+            ...(typeof a.from === "string" ? { from: a.from } : {}),
+            ...(typeof a.submit === "string" ? { submit: a.submit } : {}),
+            ...(typeof a.harness === "string" ? { harness: a.harness } : {}),
+            ...(a.ifIdle === true ? { ifIdle: true } : {}),
+            origin: a.origin,
+            local: true,
+        }, undefined, { env, gateId: id });
+    }
+    catch (err) {
+        const e = err instanceof ZellijError ? err : new ZellijError("gate_failed", String(err));
+        result = { ok: false, error: { code: e.code, message: e.message, ...(e.details ? { details: e.details } : {}) } };
+    }
+    try {
+        const log = join(defaultStateDir(env), "gate.log");
+        mkdirSync(dirname(log), { recursive: true });
+        const submitted = result.ok ? result.data?.submitted : undefined;
+        appendFileSync(log, `${JSON.stringify({ at, id: input.id, target, bytes: Buffer.byteLength(input.request), ok: result.ok, submitted, error: result.ok ? undefined : result.error.code })}\n`);
+    }
+    catch {
+        // the log is a convenience; delivery already happened or failed on its own
+    }
+    return result;
+}
+async function readStdin(limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += b.length;
+        if (size > limit)
+            throw new ZellijError("gate_request_too_large", `gate requests are limited to ${limit} bytes`);
+        chunks.push(b);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function cliPath() {
+    const script = process.argv[1] ?? "";
+    try {
+        return realpathSync(script);
+    }
+    catch {
+        return script;
+    }
+}
+const s = (v) => (typeof v === "string" ? v : undefined);
+export function gateAllow(id, flags, env = process.env) {
+    id = validateGateId(id);
+    if (RESERVED.has(id))
+        throw new ZellijError("bad_gate_id", `${id} is a gate subcommand, not an id`);
+    const session = s(flags["--session"]);
+    const pane = s(flags["--pane"]);
+    if (!session || !pane)
+        throw new ZellijError("usage", "gate allow needs --session and --pane (the pane title or id senders will use with --to)");
+    const keyFile = s(flags["--key-file"]);
+    const key = s(flags["--key"]) ?? (keyFile ? readFileSync(keyFile, "utf8") : undefined);
+    if (!key)
+        throw new ZellijError("usage", "gate allow needs --key 'ssh-ed25519 AAAA…' or --key-file PATH (the sender's public key)");
+    const command = gateForcedCommand({ id, node: process.execPath, cli: cliPath(), env });
+    const line = gateKeyLine({ id, key, command, from: s(flags["--from"]) });
+    const keysPath = s(flags["--authorized-keys"]) ?? defaultAuthorizedKeysPath(env);
+    mkdirSync(dirname(keysPath), { recursive: true, mode: 0o700 });
+    writeAuthorizedKeys(keysPath, upsertGateKey(existsSync(keysPath) ? readFileSync(keysPath, "utf8") : "", id, line));
+    const configPath = gateConfigPath(env);
+    const config = allowInConfig(loadGateConfig(configPath), id, session, pane);
+    saveGateConfig(configPath, config);
+    return { id, session, pane, from: s(flags["--from"]) ?? null, authorizedKeys: keysPath, config: configPath, command };
+}
+export function gateRevoke(id, flags, env = process.env) {
+    id = validateGateId(id);
+    const session = s(flags["--session"]);
+    const pane = s(flags["--pane"]);
+    if (Boolean(session) !== Boolean(pane))
+        throw new ZellijError("usage", "gate revoke takes both --session and --pane, or neither (all targets)");
+    const configPath = gateConfigPath(env);
+    const config = revokeInConfig(loadGateConfig(configPath), id, session && pane ? { session, pane } : undefined);
+    saveGateConfig(configPath, config);
+    const keysPath = s(flags["--authorized-keys"]) ?? defaultAuthorizedKeysPath(env);
+    const keyRemoved = !idIsAllowed(config, id) && existsSync(keysPath);
+    if (keyRemoved)
+        writeAuthorizedKeys(keysPath, removeGateKey(readFileSync(keysPath, "utf8"), id));
+    return { id, config: configPath, keyRemoved, stillAllowed: config.targets.filter((t) => t.allow.includes(id)).map((t) => `${t.session}/${t.pane}`) };
+}
+export function gateList(flags, env = process.env) {
+    const keysPath = s(flags["--authorized-keys"]) ?? defaultAuthorizedKeysPath(env);
+    const configPath = gateConfigPath(env);
+    return {
+        config: configPath,
+        targets: loadGateConfig(configPath).targets,
+        authorizedKeys: keysPath,
+        keys: existsSync(keysPath) ? listGateKeys(readFileSync(keysPath, "utf8")) : [],
+    };
+}
+export const GATE_USAGE = [
+    "zswarm gate allow ID (--key 'ssh-ed25519 AAAA…' | --key-file PUB) --session S --pane P [--from ADDRS] [--authorized-keys PATH]",
+    "      on the receiving machine: let the key send to pane P in session S as ID. Writes a forced-command line",
+    "      (send only: no shell, no pty, no forwarding) to authorized_keys and the target to gate.json (ZSWARM_GATE_CONFIG,",
+    "      default ~/.zswarm/gate.json); --from limits the source addresses (sshd from= patterns)",
+    "zswarm gate revoke ID [--session S --pane P]   drop ID from one target or all; the key line goes when nothing is left",
+    "zswarm gate list   targets, allowed ids and gate keys",
+    "zswarm gate ID     the forced command itself: reads one request on stdin and sends locally (sshd runs this)",
+    "sender: zswarm send --gate DEST --session S --to P --body …   (DEST: ssh alias or user@host using that key)",
+].join("\n");
+/** `zswarm gate …`; resolves to the exit code. */
+export async function gateCommand(argv, parse) {
+    const [sub, ...args] = argv;
+    const print = (r) => {
+        process.stdout.write(`${JSON.stringify(r)}\n`);
+        return r.ok ? 0 : 1;
+    };
+    const run = (work) => {
+        try {
+            return print({ ok: true, data: work() });
+        }
+        catch (err) {
+            const e = err instanceof ZellijError ? err : new ZellijError("failed", String(err));
+            return print({ ok: false, error: { code: e.code, message: e.message } });
+        }
+    };
+    if (sub === "allow" || sub === "revoke" || sub === "list") {
+        const { flags, rest } = parse(args);
+        if (sub === "list")
+            return run(() => gateList(flags));
+        const id = rest[0] ?? "";
+        return run(() => (sub === "allow" ? gateAllow(id, flags) : gateRevoke(id, flags)));
+    }
+    if (!sub) {
+        process.stderr.write(`${GATE_USAGE}\n`);
+        return 2;
+    }
+    // Receiver: sshd's forced command. Anything the client asked to run is ignored.
+    let request;
+    try {
+        request = await readStdin(GATE_MAX_REQUEST_BYTES);
+    }
+    catch (err) {
+        const e = err instanceof ZellijError ? err : new ZellijError("gate_failed", String(err));
+        return print({ ok: false, error: { code: e.code, message: e.message } });
+    }
+    return print(await runGate({ id: sub, request }));
+}

package/dist/host/relay.d.ts

@@ -46,6 +46,9 @@ export type RelayConfig = {
     to: string;
     done: string;
     replyTo: string;
+    /** The reply pane's unique title when `replyTo` was a pane id: delivery tries
+     * the name first, because ids shift when panes are restarted or renumbered. */
+    replyToName?: string;
     replySession?: string;
     from: string;
     /** The target harness (`--harness`); sent with the body and the reply. */
@@ -112,6 +115,10 @@ export declare function fillMessage(template: string, fields: Record<string, str
  * the verdict and keeps waiting — the done line is the real proof of delivery.
  */
 export declare function softSendVerdict(res: OpsResult): boolean;
+/** The unique title of the reply pane when `replyTo` is a pane id (`terminal_14`, `14`),
+ * else undefined: an untitled pane (default shell title) or a title shared by two panes
+ * keeps delivery by id. */
+export declare function replyPaneName(cfg: Pick<RelayConfig, "replyTo" | "replySession">, env: NodeJS.ProcessEnv, call: NonNullable<RelayDeps["call"]>): Promise<string | undefined>;
 /** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
 export declare function deliverMessage(cfg: RelayConfig, body: string, dir: string, deps?: RelayDeps): Promise<boolean>;
 /** The waiting loop; returns the final status and the message it delivered or left behind. */

package/dist/host/relay.js

@@ -111,6 +111,28 @@ export function softSendVerdict(res) {
     const submitted = res.data?.submitted;
     return submitted !== true;
 }
+/** The unique title of the reply pane when `replyTo` is a pane id (`terminal_14`, `14`),
+ * else undefined: an untitled pane (default shell title) or a title shared by two panes
+ * keeps delivery by id. */
+export async function replyPaneName(cfg, env, call) {
+    const ref = cfg.replyTo.trim();
+    if (!/^(terminal_)?\d+$/i.test(ref))
+        return undefined;
+    const args = { op: "list" };
+    if (cfg.replySession)
+        args.session = cfg.replySession;
+    const res = await call(args, localEnv(env)).catch(() => null);
+    if (!res?.ok)
+        return undefined;
+    const panes = (res.data.panes ?? [])
+        .filter((p) => !p.isPlugin);
+    const id = `terminal_${ref.replace(/^terminal_/i, "")}`;
+    const title = panes.find((p) => p.id === id)?.title?.trim();
+    if (!title || /^(Pane #\d+|-?(zsh|bash|fish|sh|pwsh|powershell))$/i.test(title))
+        return undefined;
+    const same = panes.filter((p) => (p.title ?? "").trim().toLowerCase() === title.toLowerCase());
+    return same.length === 1 ? title : undefined;
+}
 /** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
 export async function deliverMessage(cfg, body, dir, deps = {}) {
     const env = deps.env ?? process.env;
@@ -125,13 +147,20 @@ export async function deliverMessage(cfg, body, dir, deps = {}) {
         await sleep(delay * 1000);
         // Generous Zellij budgets: this runs exactly when the machine is busiest.
         const args = {
-            op: "send", to: cfg.replyTo, body, from: cfg.from, fresh: true, settleMs: 800, observeMs: 30_000, timeoutMs: 60_000,
+            op: "send", to: cfg.replyToName ?? cfg.replyTo, body, from: cfg.from, fresh: true, settleMs: 800, observeMs: 30_000,
+            timeoutMs: 60_000,
         };
         if (cfg.replySession)
             args.session = cfg.replySession;
         if (cfg.harness)
             args.harness = cfg.harness;
-        const res = await call(args, localEnv(env)).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        const send = (a) => call(a, localEnv(env)).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        let res = await send(args);
+        if (!res.ok && cfg.replyToName && (res.error.code === "peer_not_found" || res.error.code === "peer_ambiguous")) {
+            // The named pane is gone or now ambiguous: the id it had at start is the last resort.
+            log(`message attempt ${i + 1}: pane "${cfg.replyToName}" ${res.error.code}; trying ${cfg.replyTo}`);
+            res = await send({ ...args, to: cfg.replyTo });
+        }
         if (res.ok) {
             const submitted = String(res.data?.submitted ?? "unknown");
             recordDelivery(dir, submitted, now());
@@ -430,6 +459,7 @@ export async function startRelay(input) {
     };
     // Read the body before the relay directory (and its token copy) exists.
     const body = input.bodyFile ? readFileSync(input.bodyFile, "utf8") : undefined;
+    cfg.replyToName = await replyPaneName(cfg, env, input.deps?.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e })));
     const dir = prepareRelay(cfg, { check: input.check, message: input.message }, env);
     const store = input.store ?? createStateStore({ env });
     const leaseTarget = { serve, session: cfg.session, pane: cfg.to };

package/dist/index.d.ts

@@ -35,10 +35,12 @@ export { DEFAULT_DOCTOR_TIMEOUT_MS, DOCTOR_FAILED_CODE, DOCTOR_SCOPE_FIELD, DOCT
 export { normalizeKey, normalizeKeys, tokenizeCommand } from "./keys.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 { GATE_USAGE, gateAllow, gateList, gateRevoke, runGate } from "./host/gate.js";
+export { GATE_PROTOCOL, allowInConfig, authorizeGateRequest, buildGateRequest, forwardGate, gateConfigPath, gateForcedCommand, gateKeyLine, isGateMode, listGateKeys, loadGateConfig, parsePublicKey, removeGateKey, revokeInConfig, upsertGateKey, validateGateId, type GateConfig, type GateRequest, type GateTarget, } from "./ops/gate.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, crewClient, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, layoutPaneNames, parseEnvFile, 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 { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, replyPaneName, 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";
 export { isSelfPane } from "./ops/guards.js";

package/dist/index.js

@@ -33,10 +33,12 @@ export { DEFAULT_DOCTOR_TIMEOUT_MS, DOCTOR_FAILED_CODE, DOCTOR_SCOPE_FIELD, DOCT
 export { normalizeKey, normalizeKeys, tokenizeCommand } from "./keys.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 { GATE_USAGE, gateAllow, gateList, gateRevoke, runGate } from "./host/gate.js";
+export { GATE_PROTOCOL, allowInConfig, authorizeGateRequest, buildGateRequest, forwardGate, gateConfigPath, gateForcedCommand, gateKeyLine, isGateMode, listGateKeys, loadGateConfig, parsePublicKey, removeGateKey, revokeInConfig, upsertGateKey, validateGateId, } from "./ops/gate.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, crewClient, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, layoutPaneNames, parseEnvFile, } 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 { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, replyPaneName, runRelayDir, scrubRelayToken, startRelay, waitForRelay, } from "./host/relay.js";
 export { hostChecks, hostDoctor, hostInstall, hostInstallArgs, hostScriptPath, parseHostReport, } from "./host/host.js";
 export { isSelfPane } from "./ops/guards.js";

package/dist/ops/delivery.d.ts

@@ -16,8 +16,11 @@ export type SenderOrigin = {
     session: string | null;
     /** Sender's pane id, e.g. "terminal_3". */
     pane: string | null;
-    /** "serve" only when this host received the op over serve. */
-    via: "serve" | null;
+    /**
+     * "serve" when this host received the op over serve; "gate" when it came
+     * through a gate key, whose id (not the sender's claim) is `host`.
+     */
+    via: "serve" | "gate" | null;
 };
 /**
  * Clean one origin part for the `[zswarm from=…]` header: non-strings and

package/dist/ops/delivery.js

@@ -66,7 +66,7 @@ export function originSuffix(origin) {
     const src = session && pane ? `${session}/${pane}` : (pane ?? session ?? null);
     return ((src ? " src=" + src : "") +
         (host ? " host=" + host : "") +
-        (via === "serve" ? " via=serve" : ""));
+        (via === "serve" || via === "gate" ? " via=" + via : ""));
 }
 /**
  * An args-supplied origin, cleaned again (a direct caller may skip dispatch),
@@ -80,7 +80,7 @@ function originArg(raw) {
         host: sanitizeOriginPart(record.host),
         session: sanitizeOriginPart(record.session),
         pane: sanitizeOriginPart(record.pane),
-        via: record.via === "serve" ? "serve" : null,
+        via: record.via === "serve" || record.via === "gate" ? record.via : null,
     };
 }
 /** Fixed send windows before adaptive scaling; explicit flags always win. */

package/dist/ops/dispatch.js

@@ -30,6 +30,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 { forwardGate, isGateMode } from "./gate.js";
 import { installServeService, uninstallServeService } from "../host/serve-service.js";
 /**
  * The harness busy marker a dumped screen shows for `pane`, or null. The one
@@ -47,13 +48,21 @@ export function paneBusyMarker(screen, pane, harness) {
 export function resolveInvocationEnv(args, base) {
     const local = isTrue(args.local);
     const sshDest = typeof args.ssh === "string" && args.ssh.trim() ? args.ssh.trim() : null;
+    const gateDest = typeof args.gate === "string" && args.gate.trim() ? args.gate.trim() : null;
     const serveAddress = optionalString(args.serveAddress);
-    if (Number(local) + Number(Boolean(sshDest)) + Number(Boolean(serveAddress)) > 1) {
-        throw new ZellijError("usage", "choose only one of --local, --ssh, or --serve");
+    if (Number(local) + Number(Boolean(sshDest)) + Number(Boolean(gateDest)) + Number(Boolean(serveAddress)) > 1) {
+        throw new ZellijError("usage", "choose only one of --local, --ssh, --gate, or --serve");
     }
-    if (!local && !sshDest && !serveAddress)
+    if (!local && !sshDest && !gateDest && !serveAddress)
         return base;
     const env = { ...base };
+    if (gateDest) {
+        env.ZSWARM_SSH = gateDest;
+        env.ZSWARM_SSH_MODE = "gate";
+        delete env.ZSWARM_SERVE;
+        delete env.ZSWARM_SERVE_TOKEN;
+        return env;
+    }
     if (serveAddress) {
         env.ZSWARM_SERVE = serveAddress;
         delete env.ZSWARM_SSH;
@@ -72,6 +81,9 @@ export function resolveInvocationEnv(args, base) {
         return env;
     }
     env.ZSWARM_SSH = sshDest;
+    // --ssh means per-call Zellij forwarding, even when the env carries a gate mode.
+    if ((env.ZSWARM_SSH_MODE ?? "").trim().toLowerCase() === "gate")
+        delete env.ZSWARM_SSH_MODE;
     delete env.ZSWARM_SERVE;
     delete env.ZSWARM_SERVE_TOKEN;
     return env;
@@ -263,6 +275,18 @@ async function dispatchOperation(args, injected, deps, context, env) {
         // Policy gates the op before anything touches the session.
         assertOpAllowed(policy, op);
         assertSshGitAllowed(env, op, args);
+        // A gate key can only send: refuse anything else before it reaches ssh.
+        if (!injected && !env.ZSWARM_SERVE?.trim() && isGateMode(env)) {
+            if (op !== "send") {
+                throw new ZellijError("gate_op_unsupported", `${op} is not available through a gate (ZSWARM_SSH_MODE=gate / --gate only carries send); use --ssh or --serve`);
+            }
+            return await forwardGate({
+                env,
+                args: attachKnownSender(args, env),
+                timeoutMs: serveCallTimeout(args),
+                signal,
+            });
+        }
         if (op === "doctor") {
             // Before serve forwarding and session resolution so a dead tunnel still
             // yields controller findings. Policy already ran.
@@ -358,7 +382,7 @@ async function dispatchOperation(args, injected, deps, context, env) {
         // Only ops that build a sender header or compare against the caller's own
         // pane need the resolved self session; read-only ops must not pay a
         // Zellij round-trip for it.
-        if (deps.viaServe !== true && SELF_SESSION_OPS.has(op) && typeof client.resolveSelf === "function") {
+        if (deps.viaServe !== true && !deps.gateId && SELF_SESSION_OPS.has(op) && typeof client.resolveSelf === "function") {
             // The pane's ZELLIJ_SESSION_NAME can be stale after a rename; the header
             // must name the live session peers can reply to.
             const self = await client.resolveSelf();
@@ -791,7 +815,9 @@ export async function dispatchZswarm(args, injected, deps = {}) {
         args =
             deps.viaServe === true
                 ? { ...args, origin: originFromServeRequest(args.origin) }
-                : { ...args, origin: resolveSenderOrigin(env) };
+                : deps.gateId
+                    ? { ...args, origin: { ...originFromServeRequest(args.origin), host: deps.gateId, via: "gate" } }
+                    : { ...args, origin: resolveSenderOrigin(env) };
         const context = invocationContext(args, env, injected?.transport);
         const result = await dispatchOperation(args, injected, deps, context, env);
         if (context.transport === "serve" && result.context) {

package/dist/ops/gate.d.ts

@@ -0,0 +1,101 @@
+import type { OpsResult } from "./types.js";
+/**
+ * Gate: a send-only SSH key. The receiving machine puts the key in
+ * authorized_keys with `command="… zswarm gate <id>"`, so whatever the client
+ * asks to run, sshd starts the gate with an id the sender cannot choose. The
+ * gate reads one JSON request on stdin, checks it against the allowlist in
+ * gate.json and performs a local send. Nothing else is reachable with the key:
+ * no shell, no screen reads, no other pane.
+ *
+ * The sender side is `ZSWARM_SSH_MODE=gate` (or `--gate DEST`): one ssh call
+ * carrying the whole send, instead of per-call Zellij forwarding.
+ */
+export declare const GATE_PROTOCOL = 1;
+/** What the client asks sshd to run; the forced command replaces it. */
+export declare const GATE_REMOTE_COMMAND = "zswarm-gate";
+/** Largest request the gate reads (body plus envelope). */
+export declare const GATE_MAX_REQUEST_BYTES: number;
+export declare const GATE_KEY_COMMENT_PREFIX = "zswarm-gate:";
+/** Send parameters a gate passes on. Guards (force, allow-self, expect) and prefix control stay with the receiver. */
+declare const GATE_SEND_FIELDS: readonly ["session", "to", "body", "from", "submit", "harness", "ifIdle"];
+export type GateRequest = {
+    v: number;
+    op: "send";
+    args: Partial<Record<(typeof GATE_SEND_FIELDS)[number], unknown>> & {
+        origin?: unknown;
+    };
+};
+export type GateTarget = {
+    session: string;
+    pane: string;
+    allow: string[];
+};
+export type GateConfig = {
+    targets: GateTarget[];
+};
+export declare function validateGateId(raw: unknown): string;
+export declare function isGateMode(env: NodeJS.ProcessEnv): boolean;
+/** The request a gate client sends: only the whitelisted send fields, plus the sender's own origin. */
+export declare function buildGateRequest(args: Record<string, unknown>): GateRequest;
+/** Sender side: one ssh call, the request on stdin, the receiver's send result on stdout. */
+export declare function forwardGate(input: {
+    env: NodeJS.ProcessEnv;
+    args: Record<string, unknown>;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<OpsResult>;
+export declare function gateConfigPath(env?: NodeJS.ProcessEnv): string;
+export declare function loadGateConfig(path: string): GateConfig;
+export declare function saveGateConfig(path: string, config: GateConfig): void;
+/** Add `id` to the target (created when new). */
+export declare function allowInConfig(config: GateConfig, id: string, session: string, pane: string): GateConfig;
+/** Remove `id` from one target, or from all; targets left with nobody are dropped. */
+export declare function revokeInConfig(config: GateConfig, id: string, only?: {
+    session: string;
+    pane: string;
+}): GateConfig;
+export declare function idIsAllowed(config: GateConfig, id: string): boolean;
+/**
+ * Receiver side: parse and check one request for the key-bound `id`.
+ * Returns the send arguments the gate may run; throws `gate_denied` otherwise.
+ */
+export declare function authorizeGateRequest(config: GateConfig, id: string, raw: string): {
+    session: string;
+    to: string;
+    args: GateRequest["args"];
+};
+/**
+ * The forced command for one id. sshd gives it a bare environment, so the PATH
+ * (and on macOS the per-user TMPDIR that Zellij keeps its sockets under) of the
+ * process running `gate allow` is written into the command.
+ */
+export declare function gateForcedCommand(input: {
+    id: string;
+    node: string;
+    cli: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/** `type base64 [comment]` → `type base64`; anything else is refused. */
+export declare function parsePublicKey(raw: string): string;
+export declare function gateKeyLine(input: {
+    id: string;
+    key: string;
+    command: string;
+    from?: string;
+}): string;
+/** Replace this id's gate line, or append it. Other lines are kept byte for byte. */
+export declare function upsertGateKey(text: string, id: string, line: string): string;
+export declare function removeGateKey(text: string, id: string): string;
+export declare function listGateKeys(text: string): Array<{
+    id: string;
+    from: string | null;
+    keyType: string;
+}>;
+/**
+ * authorized_keys for this account. On Windows an administrator's keys live in
+ * %ProgramData%\ssh\administrators_authorized_keys when that file exists.
+ */
+export declare function defaultAuthorizedKeysPath(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+export declare function writeAuthorizedKeys(path: string, text: string, platform?: NodeJS.Platform): void;
+export {};

package/dist/ops/gate.js

@@ -0,0 +1,324 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ZellijError } from "../errors.js";
+import { defaultStateDir } from "../state.js";
+import { resolveSshTarget } from "../zellij/binary.js";
+/**
+ * Gate: a send-only SSH key. The receiving machine puts the key in
+ * authorized_keys with `command="… zswarm gate <id>"`, so whatever the client
+ * asks to run, sshd starts the gate with an id the sender cannot choose. The
+ * gate reads one JSON request on stdin, checks it against the allowlist in
+ * gate.json and performs a local send. Nothing else is reachable with the key:
+ * no shell, no screen reads, no other pane.
+ *
+ * The sender side is `ZSWARM_SSH_MODE=gate` (or `--gate DEST`): one ssh call
+ * carrying the whole send, instead of per-call Zellij forwarding.
+ */
+export const GATE_PROTOCOL = 1;
+/** What the client asks sshd to run; the forced command replaces it. */
+export const GATE_REMOTE_COMMAND = "zswarm-gate";
+/** Largest request the gate reads (body plus envelope). */
+export const GATE_MAX_REQUEST_BYTES = 256 * 1024;
+export const GATE_KEY_COMMENT_PREFIX = "zswarm-gate:";
+const GATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
+/** Send parameters a gate passes on. Guards (force, allow-self, expect) and prefix control stay with the receiver. */
+const GATE_SEND_FIELDS = ["session", "to", "body", "from", "submit", "harness", "ifIdle"];
+export function validateGateId(raw) {
+    const id = typeof raw === "string" ? raw.trim() : "";
+    if (!GATE_ID.test(id)) {
+        throw new ZellijError("bad_gate_id", `gate id must be 1-63 letters, digits, '.', '_' or '-', starting with a letter or digit; got ${JSON.stringify(raw)}`);
+    }
+    return id;
+}
+export function isGateMode(env) {
+    return Boolean(env.ZSWARM_SSH?.trim()) && (env.ZSWARM_SSH_MODE ?? "").trim().toLowerCase() === "gate";
+}
+/** The request a gate client sends: only the whitelisted send fields, plus the sender's own origin. */
+export function buildGateRequest(args) {
+    const out = {};
+    for (const field of GATE_SEND_FIELDS) {
+        if (args[field] !== undefined && args[field] !== null)
+            out[field] = args[field];
+    }
+    if (args.origin && typeof args.origin === "object")
+        out.origin = args.origin;
+    return { v: GATE_PROTOCOL, op: "send", args: out };
+}
+function lastJsonLine(text) {
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line.startsWith("{"))
+            continue;
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            // keep looking: a pretty-printed result spans lines
+        }
+    }
+    const start = text.indexOf("{");
+    if (start >= 0) {
+        try {
+            return JSON.parse(text.slice(start));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** Sender side: one ssh call, the request on stdin, the receiver's send result on stdout. */
+export async function forwardGate(input) {
+    const target = resolveSshTarget(input.env);
+    if (!target)
+        throw new ZellijError("bad_ssh", "gate mode needs ZSWARM_SSH or --gate DEST");
+    const request = JSON.stringify(buildGateRequest(input.args));
+    if (Buffer.byteLength(request) > GATE_MAX_REQUEST_BYTES) {
+        throw new ZellijError("gate_request_too_large", `gate requests are limited to ${GATE_MAX_REQUEST_BYTES} bytes`);
+    }
+    const argv = [...target.options, target.host, GATE_REMOTE_COMMAND];
+    const { code, stdout, stderr } = await new Promise((resolve, reject) => {
+        const child = spawn(target.ssh, argv, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            input.signal?.removeEventListener("abort", onAbort);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(() => reject(new ZellijError("timeout", `gate send to ${target.host} took longer than ${input.timeoutMs} ms`)));
+        }, input.timeoutMs);
+        const onAbort = () => {
+            child.kill();
+            finish(() => reject(new ZellijError("cancelled", "operation cancelled")));
+        };
+        input.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.setEncoding("utf8").on("data", (d) => (stdout += d));
+        child.stderr.setEncoding("utf8").on("data", (d) => (stderr += d));
+        child.on("error", (err) => finish(() => reject(new ZellijError("gate_failed", `could not start ${target.ssh}: ${err.message}`))));
+        child.on("close", (code) => finish(() => resolve({ code, stdout, stderr })));
+        child.stdin.on("error", () => {
+            // the remote may close stdin early on refusal; the result still arrives on stdout
+        });
+        child.stdin.end(request);
+    });
+    const parsed = lastJsonLine(stdout);
+    if (parsed && typeof parsed === "object" && "ok" in parsed)
+        return parsed;
+    const hint = /Permission denied/i.test(stderr)
+        ? " (the key is not authorized there; on the receiver run `zswarm gate allow`)"
+        : /not found|No such file/i.test(stderr + stdout)
+            ? " (the key reached a shell instead of the gate: its authorized_keys line has no forced command)"
+            : "";
+    throw new ZellijError("gate_failed", `gate send to ${target.host} failed (exit ${code})${hint}: ${(stderr || stdout).trim().slice(0, 400)}`);
+}
+export function gateConfigPath(env = process.env) {
+    return env.ZSWARM_GATE_CONFIG?.trim() || join(defaultStateDir(env), "gate.json");
+}
+export function loadGateConfig(path) {
+    if (!existsSync(path))
+        return { targets: [] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new ZellijError("gate_config", `${path} is not valid JSON: ${err.message}`);
+    }
+    const targets = raw?.targets;
+    if (!Array.isArray(targets))
+        return { targets: [] };
+    return {
+        targets: targets
+            .filter((t) => t !== null && typeof t === "object")
+            .map((t) => ({
+            session: String(t.session ?? ""),
+            pane: String(t.pane ?? ""),
+            allow: Array.isArray(t.allow) ? t.allow.map(String) : [],
+        }))
+            .filter((t) => t.session && t.pane),
+    };
+}
+function writeAtomic(path, text, mode = 0o600) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, text, { mode });
+    renameSync(tmp, path);
+}
+export function saveGateConfig(path, config) {
+    writeAtomic(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+/** Add `id` to the target (created when new). */
+export function allowInConfig(config, id, session, pane) {
+    const targets = config.targets.map((t) => ({ ...t, allow: [...t.allow] }));
+    let target = targets.find((t) => t.session === session && t.pane === pane);
+    if (!target) {
+        target = { session, pane, allow: [] };
+        targets.push(target);
+    }
+    if (!target.allow.includes(id))
+        target.allow.push(id);
+    return { targets };
+}
+/** Remove `id` from one target, or from all; targets left with nobody are dropped. */
+export function revokeInConfig(config, id, only) {
+    return {
+        targets: config.targets
+            .map((t) => only && (t.session !== only.session || t.pane !== only.pane)
+            ? t
+            : { ...t, allow: t.allow.filter((a) => a !== id) })
+            .filter((t) => t.allow.length > 0),
+    };
+}
+export function idIsAllowed(config, id) {
+    return config.targets.some((t) => t.allow.includes(id));
+}
+/**
+ * Receiver side: parse and check one request for the key-bound `id`.
+ * Returns the send arguments the gate may run; throws `gate_denied` otherwise.
+ */
+export function authorizeGateRequest(config, id, raw) {
+    let request;
+    try {
+        request = JSON.parse(raw);
+    }
+    catch {
+        throw new ZellijError("gate_bad_request", "the gate reads one JSON request on stdin (send it with ZSWARM_SSH_MODE=gate or --gate)");
+    }
+    if (!request || typeof request !== "object" || request.v !== GATE_PROTOCOL) {
+        throw new ZellijError("gate_bad_request", `unsupported gate protocol ${JSON.stringify(request?.v)}; this receiver speaks ${GATE_PROTOCOL}`);
+    }
+    if (request.op !== "send") {
+        throw new ZellijError("gate_denied", `a gate key may only send; ${JSON.stringify(request.op)} is not allowed`);
+    }
+    const args = request.args ?? {};
+    const session = typeof args.session === "string" ? args.session.trim() : "";
+    const to = typeof args.to === "string" ? args.to.trim() : "";
+    if (!session || !to) {
+        throw new ZellijError("gate_denied", "a gate send must name --session and --to exactly as the receiver allows them");
+    }
+    if (typeof args.body !== "string" || !args.body.trim()) {
+        throw new ZellijError("gate_bad_request", "the message body is empty");
+    }
+    const target = config.targets.find((t) => t.session === session && t.pane === to);
+    if (!target || !target.allow.includes(id)) {
+        throw new ZellijError("gate_denied", `gate id ${JSON.stringify(id)} may not send to ${session}/${to}`, {
+            allowed: config.targets.filter((t) => t.allow.includes(id)).map((t) => `${t.session}/${t.pane}`),
+        });
+    }
+    return { session, to, args };
+}
+/** Single-quote for a POSIX shell (sshd runs the forced command through the user's shell). */
+function posixQuote(arg) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The forced command for one id. sshd gives it a bare environment, so the PATH
+ * (and on macOS the per-user TMPDIR that Zellij keeps its sockets under) of the
+ * process running `gate allow` is written into the command.
+ */
+export function gateForcedCommand(input) {
+    const platform = input.platform ?? process.platform;
+    const env = input.env ?? process.env;
+    if (platform === "win32") {
+        // Unquoted paths run the same in cmd and PowerShell (OpenSSH's DefaultShell
+        // may be either); a path with spaces needs quoting, which only cmd accepts.
+        const q = (s) => {
+            const p = s.replace(/\\/g, "/");
+            return /\s/.test(p) ? `"${p}"` : p;
+        };
+        return `${q(input.node)} ${q(input.cli)} gate ${input.id}`;
+    }
+    const vars = [];
+    if (env.PATH)
+        vars.push(`PATH=${posixQuote(env.PATH)}`);
+    if (platform === "darwin" && env.TMPDIR)
+        vars.push(`TMPDIR=${posixQuote(env.TMPDIR)}`);
+    if (env.ZSWARM_STATE_DIR)
+        vars.push(`ZSWARM_STATE_DIR=${posixQuote(env.ZSWARM_STATE_DIR)}`);
+    if (env.ZSWARM_GATE_CONFIG)
+        vars.push(`ZSWARM_GATE_CONFIG=${posixQuote(env.ZSWARM_GATE_CONFIG)}`);
+    return ["env", ...vars, posixQuote(input.node), posixQuote(input.cli), "gate", input.id].join(" ");
+}
+const KEY_TYPES = /^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com)$/;
+/** `type base64 [comment]` → `type base64`; anything else is refused. */
+export function parsePublicKey(raw) {
+    const parts = raw.trim().split(/\s+/);
+    if (parts.length < 2 || !KEY_TYPES.test(parts[0]) || !/^[A-Za-z0-9+/=]+$/.test(parts[1])) {
+        throw new ZellijError("bad_gate_key", "expected one OpenSSH public key line, e.g. `ssh-ed25519 AAAA… name`");
+    }
+    return `${parts[0]} ${parts[1]}`;
+}
+export function gateKeyLine(input) {
+    if (input.from && !/^[0-9A-Fa-f:.,/*?!]+$/.test(input.from)) {
+        throw new ZellijError("bad_gate_from", `--from takes addresses or patterns separated by commas; got ${JSON.stringify(input.from)}`);
+    }
+    const opts = [
+        // sshd only unescapes \" inside command="…"; every other byte is passed as is.
+        `command="${input.command.replace(/"/g, '\\"')}"`,
+        ...(input.from ? [`from="${input.from}"`] : []),
+        "no-pty",
+        "no-port-forwarding",
+        "no-agent-forwarding",
+        "no-X11-forwarding",
+        "no-user-rc",
+    ];
+    return `${opts.join(",")} ${parsePublicKey(input.key)} ${GATE_KEY_COMMENT_PREFIX}${input.id}`;
+}
+function lineId(line) {
+    const m = line.trim().match(/\szswarm-gate:([A-Za-z0-9._-]+)\s*$/);
+    return m ? m[1] : null;
+}
+/** Replace this id's gate line, or append it. Other lines are kept byte for byte. */
+export function upsertGateKey(text, id, line) {
+    const lines = text.split(/\r?\n/);
+    const kept = lines.filter((l) => lineId(l) !== id);
+    while (kept.length > 0 && kept[kept.length - 1] === "")
+        kept.pop();
+    kept.push(line);
+    return `${kept.join("\n")}\n`;
+}
+export function removeGateKey(text, id) {
+    const kept = text.split(/\r?\n/).filter((l) => lineId(l) !== id);
+    while (kept.length > 0 && kept[kept.length - 1] === "")
+        kept.pop();
+    return kept.length ? `${kept.join("\n")}\n` : "";
+}
+export function listGateKeys(text) {
+    return text
+        .split(/\r?\n/)
+        .map((l) => ({ l, id: lineId(l) }))
+        .filter((x) => x.id !== null)
+        .map(({ l, id }) => ({
+        id,
+        from: l.match(/from="([^"]*)"/)?.[1] ?? null,
+        keyType: l.match(/\s(ssh-[a-z0-9]+|ecdsa-[a-z0-9-]+|sk-[a-z0-9@.-]+)\s/)?.[1] ?? "",
+    }));
+}
+/**
+ * authorized_keys for this account. On Windows an administrator's keys live in
+ * %ProgramData%\ssh\administrators_authorized_keys when that file exists.
+ */
+export function defaultAuthorizedKeysPath(env = process.env, platform = process.platform) {
+    if (platform === "win32") {
+        const admin = join(env.ProgramData || "C:\\ProgramData", "ssh", "administrators_authorized_keys");
+        if (existsSync(admin))
+            return admin;
+    }
+    return join(env.USERPROFILE || env.HOME || "", ".ssh", "authorized_keys");
+}
+export function writeAuthorizedKeys(path, text, platform = process.platform) {
+    // Windows sshd checks the file's ACL; a renamed temp file would not keep it.
+    if (platform === "win32")
+        writeFileSync(path, text);
+    else
+        writeAtomic(path, text, 0o600);
+}

package/dist/ops/types.d.ts

@@ -31,6 +31,11 @@ export type DispatchDeps = {
      * the worker host's environment.
      */
     viaServe?: boolean;
+    /**
+     * Set by `zswarm gate <id>`: the request's origin is kept for session and
+     * pane, but its host becomes the key-bound id and it is stamped `via gate`.
+     */
+    gateId?: string;
     /** MCP cancellation; aborted waits stop instead of running to timeout. */
     signal?: AbortSignal;
     /** Process-owned ssh:// LocalForward manager. CLI disposes; MCP reuses. */

package/dist/schema.js

@@ -130,6 +130,13 @@ export const PARAMS = [
         flags: ["--ssh"],
         description: "route this call over SSH to user@host (or an alias) for the invocation; clears ZSWARM_SERVE; put flags in ZSWARM_SSH_OPTS",
     },
+    {
+        name: "gate",
+        type: "string",
+        flags: ["--gate"],
+        ops: ["send"],
+        description: "send through a gate on that machine: an ssh alias (or user@host) whose key the receiver allowed with `zswarm gate allow`; one ssh call, send only (ZSWARM_SSH_MODE=gate)",
+    },
     {
         name: "group",
         type: "string",
@@ -655,7 +662,7 @@ export function cliUsage() {
         const value = param.type === "boolean" ? "" : param.type === "number" ? " N" : " VALUE";
         lines.push(`  ${param.flags.join(", ").padEnd(28)}${value.trim().padEnd(6)}${param.description}`);
     }
-    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE / --serve (host:port, tcp://, or ssh://user@host?servePort=9419) plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. Private raw TCP Tailscale Serve keeps the backend on 127.0.0.1 behind `tailscale serve --tcp=…` (docs/tailscale.md). ssh:// does not start remote serve. Windows default recipe: `zswarm serve --install` (verified readiness).", "Hosts (CLI only, see docs/hosts.md): `zswarm slot`, `zswarm crew`, `zswarm relay`, `zswarm host`; `zswarm <command> --help` for each.", "Doctor: `zswarm doctor --session crew` inspects local, --ssh, and --serve routes without installs, pane changes, or plugin launch. See docs/doctor.md and docs/tailscale.md.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZSWARM_HOST, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_SSH_BIN, ZSWARM_SSH_OPTS, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
+    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE / --serve (host:port, tcp://, or ssh://user@host?servePort=9419) plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. Private raw TCP Tailscale Serve keeps the backend on 127.0.0.1 behind `tailscale serve --tcp=…` (docs/tailscale.md). ssh:// does not start remote serve. Windows default recipe: `zswarm serve --install` (verified readiness).", "Hosts (CLI only, see docs/hosts.md): `zswarm slot`, `zswarm crew`, `zswarm relay`, `zswarm host`, `zswarm gate`; `zswarm <command> --help` for each.", "Gate (docs/gate.md): a send-only ssh key. Receiver: `zswarm gate allow ID --key-file K --session S --pane P`. Sender: `zswarm send --gate DEST --session S --to P --body …`.", "Doctor: `zswarm doctor --session crew` inspects local, --ssh, and --serve routes without installs, pane changes, or plugin launch. See docs/doctor.md and docs/tailscale.md.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZSWARM_HOST, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_SSH_BIN, ZSWARM_SSH_OPTS, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_GATE_CONFIG, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
     return lines.join("\n");
 }
 /**

package/dist/state.d.ts

@@ -16,7 +16,7 @@ export type LogEntry = {
     /** Sender's pane id, e.g. "terminal_3". */
     fromPane?: string | null;
     /** "serve" when this host received the op over serve. */
-    via?: "serve" | null;
+    via?: "serve" | "gate" | null;
     bytes?: number;
     ok: boolean;
     detail?: string | null;

package/dist/zellij/binary.d.ts

@@ -25,7 +25,7 @@ export declare function assertZellijBinaryPath(path: string): void;
  * Accept `user@host` or an SSH config alias; put flags in ZSWARM_SSH_OPTS.
  */
 export declare function validateSshDestination(raw: string): string;
-export declare function validateSshMode(raw: string): "ssh" | "interactive";
+export declare function validateSshMode(raw: string): "ssh" | "interactive" | "gate";
 /** True when `--version` output is positively Zellij. */
 export declare function isZellijVersionOutput(stdout: string, stderr?: string): boolean;
 /**

package/dist/zellij/binary.js

@@ -96,7 +96,10 @@ export function validateSshMode(raw) {
         return "ssh";
     if (mode === "interactive")
         return "interactive";
-    throw new ZellijError("bad_ssh_mode", `ZSWARM_SSH_MODE must be "interactive" or "ssh" (or unset); got ${JSON.stringify(raw.trim())}`);
+    // `gate`: the whole send goes over one ssh call to a send-only key (ops/gate.ts).
+    if (mode === "gate")
+        return "gate";
+    throw new ZellijError("bad_ssh_mode", `ZSWARM_SSH_MODE must be "interactive", "gate" or "ssh" (or unset); got ${JSON.stringify(raw.trim())}`);
 }
 /** Cache of verified `zellij --version` probes keyed by target identity. */
 const identityCache = new Set();

package/dist/zellij/client.d.ts

@@ -34,7 +34,7 @@ export type ZellijClientOptions = {
 export declare function resetSelfResolutionCache(): void;
 export type ZellijTransport = {
     kind: "local" | "ssh";
-    mode: "local" | "ssh" | "interactive";
+    mode: "local" | "ssh" | "interactive" | "gate";
     host?: string;
     remoteBin?: string;
     /** Configured or resolved IPC temp (`auto` until discovery succeeds). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {