@zswarm/core 0.1.8 → 0.2.0

package/dist/ops/status.d.ts

@@ -40,12 +40,13 @@ export declare function statusTabs(peers: Record<string, unknown>[]): {
     panes: number;
     states: Record<string, number>;
 }[];
-export declare function classify(input: {
+type ScreenPair = {
     exited: boolean;
     before: string;
     after: string;
     profile?: HarnessProfile | null;
-}): PeerState;
+};
+export declare function classify(input: ScreenPair): PeerState;
 /** Run `fn` over items with at most `limit` in flight. */
 export declare function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
 /**
@@ -59,3 +60,4 @@ export declare function peerStatus(client: ZellijClient, args: Record<string, un
     deadlineAt?: number;
     signal?: AbortSignal;
 }): Promise<OpsResult>;
+export {};

package/dist/ops/status.js

@@ -53,9 +53,6 @@ export function waitingPrompt(screen, profile) {
     const last = lines[lines.length - 1] ?? "";
     return QUESTION.test(last) ? { reason: "prompt", evidence: last.slice(0, 320), source: "screen" } : null;
 }
-function promptHolds(screen, profile) {
-    return waitingPrompt(screen, profile) !== null;
-}
 /** Compact summary of the selected terminal peers, including inactive tabs. */
 export function statusTabs(peers) {
     const tabs = new Map();
@@ -69,12 +66,17 @@ export function statusTabs(peers) {
     }
     return [...tabs.values()];
 }
-export function classify(input) {
+/** The verdict and, for `waiting`, the prompt behind it — one screen scan. */
+function classifyWithEvidence(input) {
     if (input.exited)
-        return "exited";
+        return { state: "exited", waiting: null };
     if (input.before !== input.after)
-        return "busy";
-    return promptHolds(input.after, input.profile) ? "waiting" : "idle";
+        return { state: "busy", waiting: null };
+    const waiting = waitingPrompt(input.after, input.profile);
+    return { state: waiting ? "waiting" : "idle", waiting };
+}
+export function classify(input) {
+    return classifyWithEvidence(input).state;
 }
 /** Run `fn` over items with at most `limit` in flight. */
 export async function mapPool(items, limit, fn) {
@@ -96,6 +98,7 @@ function isCancelledError(err) {
     return ((err instanceof ZellijError && err.code === "cancelled") ||
         (err instanceof Error && /cancelled/i.test(err.message)));
 }
+/** A `waiting` peer carries its evidence in `extra`, found when it was classified. */
 function peerEntry(pane, state, screen, verbose, extra) {
     const entry = {
         id: pane.id,
@@ -106,8 +109,6 @@ function peerEntry(pane, state, screen, verbose, extra) {
         lastLine: lastLine(screen).slice(0, 160),
         ...extra,
     };
-    if (state === "waiting")
-        entry.waiting = waitingPrompt(screen, resolveHarness(pane));
     if (verbose) {
         entry.command = pane.command ?? null;
         entry.cwd = pane.cwd ?? null;
@@ -185,11 +186,13 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
                     return peerEntry(pane, "exited", "", verbose);
                 }
                 const row = changed.get(pane.id);
+                const waiting = row ? waitingPrompt(row.screen, resolveHarness(pane)) : null;
                 const state = !row ? "unknown"
-                    : promptHolds(row.screen, resolveHarness(pane)) ? "waiting"
+                    : waiting ? "waiting"
                         : row.first ? "unknown" : row.changed ? "busy" : "idle";
                 return peerEntry(pane, state, row?.screen ?? "", verbose, {
                     ...(row?.first ? { first: true } : {}),
+                    ...(waiting ? { waiting } : {}),
                 });
             })
                 .sort((a, b) => String(a.id).localeCompare(String(b.id)));
@@ -315,13 +318,13 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
             peers.push(peerEntry(pane, "unknown", after ?? first ?? "", verbose));
             continue;
         }
-        const state = classify({
+        const { state, waiting } = classifyWithEvidence({
             exited: false,
             before: first,
             after,
             profile: resolveHarness(pane),
         });
-        peers.push(peerEntry(pane, state, after, verbose));
+        peers.push(peerEntry(pane, state, after, verbose, waiting ? { waiting } : undefined));
     }
     peers.sort((a, b) => String(a.id).localeCompare(String(b.id)));
     const free = peers.filter((p) => p.state === "idle").map((p) => p.id);

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;

package/dist/ops/wait.js

@@ -1,4 +1,5 @@
 import { ZellijError } from "../errors.js";
+import { DEFAULT_TIMEOUT_MS } from "../zellij/binary.js";
 import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, throwIfAborted, truncateDumpText, } from "./util.js";
 const WAIT_DEFAULTS = {
     idleMs: 2_000,
@@ -10,6 +11,11 @@ const WAIT_LIMITS = {
     pollMs: { min: 50, max: 30_000 },
     timeoutMs: { min: 1_000, max: 900_000 },
 };
+/**
+ * A poll at the deadline still gets this long, so `timeout` reports the screen
+ * at the deadline; a hung dump there overruns the wait by at most this much.
+ */
+const FINAL_DUMP_MS = 1_000;
 export function buildMatcher(args) {
     const match = optionalString(args.match);
     if (!match)
@@ -98,15 +104,29 @@ export async function waitForPane(client, target, args, clock, waitViaBus, signa
     let lastChangeAt = started;
     let polls = 0;
     let changes = 0;
+    let last = null;
     for (;;) {
         throwIfAborted(signal);
-        const dumped = await client.dumpPane({
-            session,
-            paneId: pane.id,
-            full: isTrue(args.full),
-        });
+        const left = timeoutMs - (clock.now() - started);
+        let text;
+        try {
+            const dumped = await client.dumpPane({
+                session,
+                paneId: pane.id,
+                full,
+                timeoutMs: Math.max(FINAL_DUMP_MS, Math.min(left, DEFAULT_TIMEOUT_MS)),
+            });
+            text = dumped.text;
+        }
+        catch (err) {
+            throwIfAborted(signal);
+            // Out of time with a screen in hand: the wait timed out, it did not fail.
+            if (last && clock.now() - started >= timeoutMs) {
+                return waitResult("timeout", { ...last, at: clock.now() });
+            }
+            throw err;
+        }
         polls++;
-        const text = dumped.text;
         const screen = normalizeScreen(text);
         const at = clock.now();
         const ctx = {
@@ -137,6 +157,8 @@ export async function waitForPane(client, target, args, clock, waitViaBus, signa
         }
         if (at - started >= timeoutMs)
             return waitResult("timeout", ctx);
-        await clock.sleep(pollMs);
+        last = ctx;
+        // The last poll lands on the deadline, not up to a whole pollMs past it.
+        await clock.sleep(Math.min(pollMs, timeoutMs - (at - started)));
     }
 }

package/dist/schema.js

@@ -52,7 +52,7 @@ export const PARAMS = [
         name: "session",
         type: "string",
         flags: ["--session", "-s"],
-        description: "Zellij session name (optional if sole live session or ZSWARM_SESSION / ZELLIJ_SESSION_NAME). serve --install: readiness target only — does not change the task's default routing",
+        description: "Zellij session name (optional if sole live session or ZSWARM_SESSION / ZELLIJ_SESSION_NAME). serve --install: on Windows the readiness target only (does not change the task's default routing); on Linux/macOS the session the service serves and waits for, one service per session",
     },
     {
         name: "to",
@@ -112,13 +112,19 @@ export const PARAMS = [
         name: "clear",
         type: "boolean",
         flags: ["--clear"],
-        description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin; serve: stop and unregister the owned Windows zswarm-serve logon task if present",
+        description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin; serve: stop and unregister the owned Windows zswarm-serve logon task, or the Linux/macOS serve service, if present",
     },
     {
         name: "install",
         type: "boolean",
         flags: ["--install"],
-        description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it; serve: register the current-user Windows Interactive logon task and wait for authenticated hello plus host session visibility",
+        description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it; serve: register the current-user Windows Interactive logon task, or on Linux/macOS a systemd user unit (with linger) or launchd job whose token lives in ~/.zswarm/serve/, and wait for authenticated hello plus host session visibility",
+    },
+    {
+        name: "runAs",
+        type: "string",
+        flags: ["--run-as"],
+        description: "serve --install/--clear on Linux/macOS, run as root: install the service for this user (a LaunchDaemon with UserName on macOS, the user's systemd units on Linux), for accounts that never log in",
     },
     {
         name: "reset",
@@ -496,7 +502,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).", "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, 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 <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, 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", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */

package/dist/state.d.ts

@@ -29,6 +29,13 @@ export type BusMarkerRecord = {
     configKey: string;
     installedAt: number;
 };
+/** How much of the end of the log `readLog` reads; older entries are not shown. */
+export declare const LOG_TAIL_BYTES: number;
+/**
+ * Past this, the append that crossed it trims the file back to its readable
+ * tail. Keeps the log bounded without needing a rotation daemon.
+ */
+export declare const LOG_MAX_BYTES: number;
 export declare function defaultStateDir(env?: NodeJS.ProcessEnv): string;
 export type StateStoreOptions = {
     dir?: string;

package/dist/state.js

@@ -1,4 +1,4 @@
-import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const LOG_FILE = "log.jsonl";
@@ -7,8 +7,13 @@ const SIGNALS_LOCK = "signals.lock";
 const CURSORS_FILE = "cursors.json";
 const CURSORS_LOCK = "cursors.lock";
 const BUS_FILE = "bus.json";
-/** Keeps the log bounded without needing a rotation daemon. */
-const LOG_TAIL_BYTES = 512 * 1024;
+/** How much of the end of the log `readLog` reads; older entries are not shown. */
+export const LOG_TAIL_BYTES = 512 * 1024;
+/**
+ * Past this, the append that crossed it trims the file back to its readable
+ * tail. Keeps the log bounded without needing a rotation daemon.
+ */
+export const LOG_MAX_BYTES = 4 * 1024 * 1024;
 /** Bound for waiting on a *live* lock holder before failing. */
 const LOCK_WAIT_MS = 5_000;
 /**
@@ -16,6 +21,45 @@ const LOCK_WAIT_MS = 5_000;
  * exclusive create (wait), not as abandoned debris (refuse).
  */
 const LOCK_PENDING_MS = LOCK_WAIT_MS;
+/**
+ * The last `bytes` of a file, starting at its first whole line. Reads only
+ * that window, so a long-lived log does not cost a full read per `log` call.
+ */
+function readFileTail(path, bytes) {
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        // One byte of lead-in says whether the window already starts a line.
+        const start = Math.max(0, size - bytes - 1);
+        const buf = Buffer.alloc(size - start);
+        let read = 0;
+        while (read < buf.length) {
+            const n = readSync(fd, buf, read, buf.length - read, start + read);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        const text = buf.toString("utf8", 0, read);
+        return start === 0 ? text : text.slice(text.indexOf("\n") + 1);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Keep only a file's readable tail. Everything before it is already invisible
+ * to `readLog`; an append racing the rename can be lost, and the log is an aid.
+ */
+function trimToTail(path, bytes) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, readFileTail(path, bytes), "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        rmSync(tmp, { force: true });
+    }
+}
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -53,7 +97,10 @@ export function createStateStore(options = {}) {
             return;
         try {
             ensureDir();
-            appendFileSync(join(dir, LOG_FILE), `${JSON.stringify(entry)}\n`, "utf8");
+            const path = join(dir, LOG_FILE);
+            appendFileSync(path, `${JSON.stringify(entry)}\n`, "utf8");
+            if (statSync(path).size > LOG_MAX_BYTES)
+                trimToTail(path, LOG_TAIL_BYTES);
         }
         catch {
             // The log is an aid, never a reason to fail an op.
@@ -62,15 +109,11 @@ export function createStateStore(options = {}) {
     function readLog() {
         let raw;
         try {
-            raw = readFileSync(join(dir, LOG_FILE), "utf8");
+            raw = readFileTail(join(dir, LOG_FILE), LOG_TAIL_BYTES);
         }
         catch {
             return [];
         }
-        if (raw.length > LOG_TAIL_BYTES) {
-            raw = raw.slice(raw.length - LOG_TAIL_BYTES);
-            raw = raw.slice(raw.indexOf("\n") + 1);
-        }
         const out = [];
         for (const line of raw.split("\n")) {
             if (!line.trim())

package/dist/zellij/binary.js

@@ -148,6 +148,9 @@ export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000,
     if (result.code === 0) {
         if (signal?.aborted)
             return false;
+        // A loaded host can return nothing; that is unresolved, not a wrong binary.
+        if (!text.trim())
+            return false;
         if (isZellijVersionOutput(result.stdout, result.stderr)) {
             identityCache.add(cacheKey);
             return true;
@@ -188,7 +191,7 @@ export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_0
         capabilityCache.add(cacheKey);
         return true;
     }
-    if (result.code === 0) {
+    if (result.code === 0 && text.trim()) {
         throw new ZellijError("zellij_incompatible", `Zellij at ${zellijPath} does not advertise list-sessions --no-formatting; upgrade Zellij (≥ 0.42) or zswarm`, zellijExecDetails(result));
     }
     // Soft: leave unresolved on transport failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {
@@ -19,6 +19,7 @@
   "license": "MIT",
   "files": [
     "dist",
+    "assets",
     "README.md"
   ],
   "publishConfig": {