@zswarm/core 0.2.3 → 0.2.5

package/dist/host/relay.js

@@ -4,7 +4,8 @@ import { basename, join } 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 { createStateStore, defaultStateDir } from "../state.js";
+import { findLease, leaseKey, releaseLeaseKey, takeLease } from "./lease.js";
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 /** Spread over about an hour: Zellij on a loaded machine can stall for minutes. */
 const DEFAULT_DELAYS = [0, 30, 60, 120, 300, 600, 900, 1500];
@@ -17,6 +18,8 @@ const CHECK_BROKEN_TRIES = 10;
 const DEFAULT_MAX_AGE_EXTRA_MIN = 60;
 /** A wait that only finds `seen` lines returns at once; poll no faster than this. */
 const STALE_MATCH_POLL_MS = 15_000;
+/** `relay --queue` re-checks a leased pane this often. */
+const LEASE_QUEUE_POLL_MS = 5_000;
 export function relaysDir(env = process.env) {
     return join(defaultStateDir(env), "relays");
 }
@@ -394,12 +397,35 @@ 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;
     const dir = prepareRelay(cfg, { check: input.check, message: input.message }, env);
-    const call = input.deps?.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
-    const remote = serveEnv(cfg, env);
-    const target = (args) => cfg.session ? { ...args, session: cfg.session } : args;
+    const store = input.store ?? createStateStore({ env });
+    const leaseTarget = { serve, session: cfg.session, pane: cfg.to };
     let sent;
     let warning;
     let how;
+    const leaseNow = input.deps?.now ?? Date.now;
+    const leaseSleep = input.deps?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const take = () => takeLease(store, { relayId: id, from: cfg.from, at: leaseNow(), dir, target: leaseTarget, force: input.force });
+    const leaseKeyValue = leaseKey(leaseTarget);
+    let taken = take();
+    if (!taken.ok && input.queue) {
+        const deadline = leaseNow() + cfg.timeoutMin * 60_000;
+        while (!taken.ok && leaseNow() < deadline) {
+            await leaseSleep(Math.min(LEASE_QUEUE_POLL_MS, Math.max(1, deadline - leaseNow())));
+            taken = take();
+        }
+    }
+    if (!taken.ok) {
+        rmSync(dir, { recursive: true, force: true });
+        const holder = taken.holder;
+        throw new ZellijError("pane_leased", `pane ${cfg.to} is leased by relay ${holder.relayId} (from ${holder.from}, since ${new Date(holder.at).toISOString()})${input.queue ? " and did not free before --timeout-min" : "; use --queue to wait or --force to share it"}`, { relayId: holder.relayId, from: holder.from, at: holder.at, dir: holder.dir });
+    }
+    updateConfig(dir, { leaseKey: leaseKeyValue });
+    if (taken.shared) {
+        warning = `pane ${cfg.to} is already leased by relay ${taken.lease.relayId}; --force shares its lease`;
+    }
+    const call = input.deps?.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
+    const remote = serveEnv(cfg, env);
+    const target = (args) => cfg.session ? { ...args, session: cfg.session } : args;
     try {
         if (body !== undefined) {
             const res = await call(target({ op: "send", to: cfg.to, body, from: cfg.from, settleMs: 800 }), remote);
@@ -418,7 +444,8 @@ export async function startRelay(input) {
                 }
             }
             if (doneLines(body, cfg.done).length > 0) {
-                warning = "--done matches a line of the body; that line is ignored while it stays on screen, so an identical done line is only seen once it scrolls off";
+                const note = "--done matches a line of the body; that line is ignored while it stays on screen, so an identical done line is only seen once it scrolls off";
+                warning = warning ? `${warning}; ${note}` : note;
             }
         }
         // Whatever already matches --done (the echoed body, an earlier task's done
@@ -431,21 +458,32 @@ export async function startRelay(input) {
             how = (input.launch ?? launchRelay)(dir, env);
     }
     catch (err) {
-        // Nothing will run from this directory: take the token copy with it.
+        // Nothing will run from this directory: take the lease and token copy with it.
+        releaseLeaseKey(store, leaseKeyValue, id);
         rmSync(dir, { recursive: true, force: true });
         throw err;
     }
     const extra = warning ? { warning } : {};
     if (input.foreground) {
-        const result = await relayLoop(dir, input.deps).finally(() => scrubRelayToken(dir));
+        const result = await relayLoop(dir, input.deps).finally(() => {
+            releaseLeaseKey(store, leaseKeyValue, id);
+            scrubRelayToken(dir);
+        });
         return { id, dir, sent: sent ?? null, ...extra, ...result };
     }
     return { id, dir, sent: sent ?? null, ...extra, relay: how };
 }
 /** What `zswarm relay --run <dir>` does inside the detached job. */
 export async function runRelayDir(dir, deps = {}) {
+    const store = createStateStore({ env: deps.env ?? process.env });
+    const releaseLease = () => {
+        const cfg = readRelayConfig(dir);
+        if (cfg?.leaseKey && cfg.id)
+            releaseLeaseKey(store, cfg.leaseKey, cfg.id);
+    };
     const stop = (sig) => () => {
         appendFileSync(join(dir, "relay.log"), `${new Date().toISOString()} relay stopped by ${sig}\n`);
+        releaseLease();
         scrubRelayToken(dir);
         process.exit(143);
     };
@@ -459,6 +497,7 @@ export async function runRelayDir(dir, deps = {}) {
         code = res.delivered ? 0 : 3;
     }
     finally {
+        releaseLease();
         scrubRelayToken(dir);
         process.off("SIGTERM", onTerm);
         process.off("SIGHUP", onHup);
@@ -613,12 +652,14 @@ function jobLoaded(job, deps, dir) {
 export function listRelays(deps = {}) {
     const env = deps.env ?? process.env;
     const now = deps.now ?? Date.now;
+    const store = deps.store ?? createStateStore({ env });
     const rows = [];
     for (const run of runDirs(relaysDir(env))) {
         const cfg = readRelayConfig(run.dir);
         if (!cfg)
             continue;
         const loaded = cfg.job ? jobLoaded(cfg.job, deps, run.dir) : false;
+        const held = findLease(store, { serve: cfg.serve, session: cfg.session, pane: cfg.to }, { now });
         rows.push({
             id: cfg.id || run.id,
             dir: run.dir,
@@ -629,6 +670,7 @@ export function listRelays(deps = {}) {
             state: relayState(run.dir, cfg),
             lastCheck: lastCheckResult(run.dir),
             ...(loaded && cfg.job ? { job: jobLabelText(cfg.job) } : {}),
+            ...(held ? { lease: { relayId: held.relayId, from: held.from, at: held.at } } : {}),
         });
     }
     return rows.sort((a, b) => b.started - a.started);
@@ -680,6 +722,9 @@ export function cancelRelay(id, deps = {}) {
                 : `${jobLabelText(cfg.job)} is no longer running this relay; nothing to stop`,
     ];
     updateConfig(match.dir, { cancelled: true, status: "CANCELLED", cancelledAt: now() });
+    if (cfg.leaseKey && releaseLeaseKey(deps.store ?? createStateStore({ env }), cfg.leaseKey, cfg.id)) {
+        actions.push(`released the pane lease for ${cfg.to}`);
+    }
     scrubRelayToken(match.dir);
     actions.push(`${id} marked CANCELLED (nothing pasted)`);
     return { id, cancelled: true, state: "cancelled", reason: `cancelled relay ${id}`, actions };

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

@@ -9,7 +9,8 @@ export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPane
 export { busPluginUrl, busToPanes, isBusPluginPane, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, type BusMarker, type BusPane, type BusScrollback, type BusScrollbackPane, type BusSnapshot, } from "./zellij/bus.js";
 export { busSnapshot, closeBusPluginPanes, planBus, resetBusCache, type BusPlan, } from "./ops/bus.js";
 export { createZellijClient, type ZellijClient, type ZellijClientOptions, type ZellijTransport, } from "./zellij/client.js";
-export { createStateStore, defaultStateDir, type LogEntry, type SignalChannel, type StateStore, type StateStoreOptions, } from "./state.js";
+export { createStateStore, defaultStateDir, type LeaseRecord, type LogEntry, type SignalChannel, type StateStore, type StateStoreOptions, } from "./state.js";
+export { findLease, leaseKey, leaseStale, listLeases, releaseLease, releaseLeaseKey, takeLease, type LeaseTakeInput, type LeaseTakeResult, type LeaseTarget, } from "./host/lease.js";
 export { dispatchZswarm, resolveInvocationEnv } from "./ops/dispatch.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, type Policy, } from "./policy.js";
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, type IpcDiscoveryState, type SshExecFn, type SshTarget, } from "./exec.js";
@@ -23,7 +24,7 @@ export { parseTabList, resolveTab, type ZellijTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";
 export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STATUS_DUMP_CONCURRENCY, type PeerState, } from "./ops/status.js";
-export { normalizeScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";
+export { normalizeScreen, unfoldScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";
 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";
@@ -33,6 +34,6 @@ export { HOST_COMMANDS, hostUsage, parseHostArgs, runHostCommand } from "./host/
 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

@@ -10,6 +10,7 @@ export { busPluginUrl, busToPanes, isBusPluginPane, nextConfigKey, parseBusReply
 export { busSnapshot, closeBusPluginPanes, planBus, resetBusCache, } from "./ops/bus.js";
 export { createZellijClient, } from "./zellij/client.js";
 export { createStateStore, defaultStateDir, } from "./state.js";
+export { findLease, leaseKey, leaseStale, listLeases, releaseLease, releaseLeaseKey, takeLease, } from "./host/lease.js";
 export { dispatchZswarm, resolveInvocationEnv } from "./ops/dispatch.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, } from "./policy.js";
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, } from "./exec.js";
@@ -23,7 +24,7 @@ export { parseTabList, resolveTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";
 export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STATUS_DUMP_CONCURRENCY, } from "./ops/status.js";
-export { normalizeScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";
+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";
@@ -31,6 +32,6 @@ export { HOST_COMMANDS, hostUsage, parseHostArgs, runHostCommand } from "./host/
 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/ops/dispatch.js

@@ -1,5 +1,7 @@
 import { ZellijError } from "../errors.js";
 import { createGitClient } from "../git.js";
+import { busyPrompt, resolveHarness } from "../harness.js";
+import { findLease } from "../host/lease.js";
 import { normalizeKeys } from "../keys.js";
 import { createZellijClient } from "../zellij/client.js";
 import { parseCreatedAge } from "../zellij/session.js";
@@ -20,7 +22,7 @@ import { invocationContext } from "./routing.js";
 import { DEFAULT_STATUS_TIMEOUT_MS, peerStatus, } from "./status.js";
 import { tailPane } from "./tail.js";
 import { OP_NAMES } from "../schema.js";
-import { dumpMaxChars, fail, isTrue, isVerbose, numberArg, optionalString, paneViewBus, paneViewFull, paneViewSlim, throwIfAborted, truncateDumpText, } from "./util.js";
+import { dumpMaxChars, fail, isTrue, isVerbose, numberArg, optionalString, paneViewBus, paneViewFull, paneViewSlim, throwIfAborted, truncateDumpText, unfoldScreen, } from "./util.js";
 import { waitForPane } from "./wait.js";
 import { listPeerWorktrees, removePeerWorktree } from "./worktree.js";
 import { DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLogon, uninstallServeLogon, } from "./serve-install.js";
@@ -110,11 +112,13 @@ async function resolveTarget(client, args, state, clock, env, policy, op, signal
         deadlineAt: budget.deadline, signal,
     });
     let panes = null;
+    let fromBus = false;
     if (bus) {
         const snapshot = busToPanes(bus.snapshot);
         try {
             client.resolvePane(snapshot, to);
             panes = snapshot;
+            fromBus = true;
         }
         catch { /* An absent title/command/ID gets a fresh direct observation. */ }
     }
@@ -160,7 +164,48 @@ async function resolveTarget(client, args, state, clock, env, policy, op, signal
     }
     if (policy && op)
         assertPaneAllowed(policy, pane, op);
-    return { session, panes, pane, firstCallMs, timeoutMs };
+    return { session, panes, pane, fromBus, firstCallMs, timeoutMs };
+}
+/**
+ * A pane's content width, for unfolding a glued dump. Only a bus-resolved pane
+ * reaches this: a direct listing already carried the field, and the manifest
+ * the bus pushes has no geometry. A single-line dump is the only caller.
+ */
+async function paneContentColumns(client, session, pane) {
+    const panes = await client.listPanes(session);
+    return panes.find((p) => p.id === pane.id)?.contentColumns ?? 0;
+}
+/**
+ * Zellij puts a newline before a row only when the row is marked canonical, and
+ * a full-screen TUI repaints by writing full-width rows back to back, so every
+ * row is a wrap continuation: `dump-screen` then hands back the whole viewport
+ * as one line. A pane whose rows are ended by a line feed reads normally and is
+ * left alone. The `--ansi` dump keeps the repainted rows full width, so it
+ * unfolds back into rows when it divides into the pane's column count exactly;
+ * anything else keeps the original text.
+ */
+async function unglueScreen(client, session, pane, text, full, fromBus) {
+    // The Zellij client prints the dump, so even a glued screen ends in one
+    // `println!` newline; only a newline *inside* the text separates rows.
+    const body = text.replace(/\n+$/, "");
+    if (!body || body.includes("\n"))
+        return text;
+    const columns = pane.contentColumns && pane.contentColumns > 1
+        ? pane.contentColumns
+        : fromBus
+            ? await paneContentColumns(client, session, pane)
+            : 0;
+    if (columns < 2 || body.length <= columns)
+        return text;
+    let ansi;
+    try {
+        ansi = (await client.dumpPane({ session, paneId: pane.id, full, ansi: true })).text;
+    }
+    catch {
+        // A Zellij too old for `--ansi` (or a failing call) must not break dump.
+        return text;
+    }
+    return unfoldScreen(ansi, columns) ?? text;
 }
 async function dispatchOperation(args, injected, deps, context, env) {
     const op = String(args.op ?? "");
@@ -341,6 +386,23 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 const { session, pane, panes, firstCallMs, timeoutMs } = await resolveTarget(client, args, state(), clock, env, policy, op, signal);
                 assertWritable(client, pane, args, "send");
                 await assertExpectedScreen(client, session, pane.id, args, signal);
+                if (isTrue(args.ifIdle)) {
+                    // Before delivery starts: a live pane lease (a relay working it) is a
+                    // hard refusal; a harness that is visibly working is the softer one.
+                    const to = String(args.to ?? "").trim();
+                    const held = findLease(state(), {
+                        serve: typeof args.serve === "string" ? args.serve : env.ZSWARM_SERVE,
+                        session,
+                        pane: to,
+                    });
+                    if (held) {
+                        throw new ZellijError("pane_leased", `pane ${to} is leased by relay ${held.relayId} (from ${held.from}, since ${new Date(held.at).toISOString()})`, { relayId: held.relayId, from: held.from, at: held.at, dir: held.dir });
+                    }
+                    const screen = await client.dumpPane({ session, paneId: pane.id }).then((res) => res.text, () => null);
+                    if (screen !== null && busyPrompt(screen, resolveHarness(pane))) {
+                        throw new ZellijError("pane_busy", `pane ${to} is busy with a task; retry when it is idle`);
+                    }
+                }
                 const labeled = withSenderLabel(args, {
                     env,
                     selfTitle: selfPaneTitle(client, panes),
@@ -428,15 +490,17 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 };
             }
             case "dump": {
-                const { session, pane } = await resolveTarget(client, args, state(), clock, env, undefined, undefined, signal);
+                const { session, pane, fromBus } = await resolveTarget(client, args, state(), clock, env, undefined, undefined, signal);
+                const full = isTrue(args.full);
                 const dumped = await client.dumpPane({
                     session,
                     paneId: pane.id,
-                    full: isTrue(args.full),
+                    full,
                 });
+                const text = await unglueScreen(client, session, pane, dumped.text, full, fromBus);
                 const max = dumpMaxChars(args);
                 const keep = isTrue(args.head) ? "head" : "tail";
-                const clipped = truncateDumpText(dumped.text, max, keep);
+                const clipped = truncateDumpText(text, max, keep);
                 return {
                     ok: true,
                     data: {

package/dist/ops/util.d.ts

@@ -44,6 +44,15 @@ export declare function truncateDumpText(text: string, maxChars: number, keep?:
 };
 /** Screen text with trailing blanks removed, so idle detection ignores padding. */
 export declare function normalizeScreen(text: string): string;
+/**
+ * Zellij's plain `dump-screen` puts a newline only before rows it marks
+ * canonical; a full-width repaint (a TUI) leaves every row a wrap
+ * continuation, so the whole viewport arrives as one line. The `--ansi`
+ * dump keeps those rows full width, so the text is a whole number of
+ * `columns`-wide rows once the SGR sequences are dropped. Returns null when
+ * that shape does not hold and the caller must keep the original text.
+ */
+export declare function unfoldScreen(text: string, columns: number): string | null;
 export declare function numberArg(args: Record<string, unknown>, key: string, fallback: number, limits: {
     min: number;
     max: number;

package/dist/ops/util.js

@@ -71,6 +71,30 @@ export function normalizeScreen(text) {
         .join("\n")
         .replace(/\n+$/, "");
 }
+/**
+ * Zellij's plain `dump-screen` puts a newline only before rows it marks
+ * canonical; a full-width repaint (a TUI) leaves every row a wrap
+ * continuation, so the whole viewport arrives as one line. The `--ansi`
+ * dump keeps those rows full width, so the text is a whole number of
+ * `columns`-wide rows once the SGR sequences are dropped. Returns null when
+ * that shape does not hold and the caller must keep the original text.
+ */
+export function unfoldScreen(text, columns) {
+    if (columns < 2)
+        return null;
+    const body = text.replace(/\x1b\[[0-9;]*m/g, "").replace(/\n+$/, "");
+    if (body.length === 0)
+        return null;
+    if (body.length % columns !== 0)
+        return null;
+    if (body.length / columns < 2)
+        return null;
+    const rows = [];
+    for (let i = 0; i < body.length; i += columns) {
+        rows.push(body.slice(i, i + columns).replace(/\s+$/, ""));
+    }
+    return rows.join("\n");
+}
 export function numberArg(args, key, fallback, limits) {
     const raw = args[key];
     if (raw === undefined || raw === null || raw === "")

package/dist/schema.js

@@ -399,6 +399,12 @@ export const PARAMS = [
         flags: ["--confirm"],
         description: 'send/broadcast: after the send, dump once more and report what it sees; paste again only on "not-delivered" (positive evidence nothing landed), press Enter when the body is still in the composer, and never paste the body twice',
     },
+    {
+        name: "ifIdle",
+        type: "boolean",
+        flags: ["--if-idle"],
+        description: "send: refuse a pane that a relay has leased (pane_leased) or whose harness is visibly working (pane_busy) instead of pasting into it",
+    },
     {
         name: "expect",
         type: "string",

package/dist/state.d.ts

@@ -29,6 +29,24 @@ export type BusMarkerRecord = {
     configKey: string;
     installedAt: number;
 };
+/**
+ * One held pane lease: a relay is working this target until it ends. `key`
+ * names the target (serve endpoint or local, session, pane) so two processes
+ * racing to take it are serialized by the lease lock.
+ */
+export type LeaseRecord = {
+    key: string;
+    relayId: string;
+    from: string;
+    at: number;
+    /** The relay run directory; a missing/finished one makes the lease stale. */
+    dir: string;
+    serve?: string;
+    session?: string;
+    pane: string;
+    /** Relays that forced through while this lease was held. */
+    sharedBy?: string[];
+};
 /** How much of the end of the log `readLog` reads; older entries are not shown. */
 export declare const LOG_TAIL_BYTES: number;
 /**
@@ -55,6 +73,8 @@ export declare function createStateStore(options?: StateStoreOptions): {
     readBus: (session: string) => BusMarkerRecord | null;
     writeBus: (session: string, marker: BusMarkerRecord) => void;
     clearBus: (session?: string) => void;
+    readLeases: () => Record<string, LeaseRecord>;
+    withLeases: <T>(fn: (leases: Record<string, LeaseRecord>) => T) => T;
     reset: () => void;
 };
 export type StateStore = ReturnType<typeof createStateStore>;

package/dist/state.js

@@ -7,6 +7,8 @@ const SIGNALS_LOCK = "signals.lock";
 const CURSORS_FILE = "cursors.json";
 const CURSORS_LOCK = "cursors.lock";
 const BUS_FILE = "bus.json";
+const LEASES_FILE = "leases.json";
+const LEASES_LOCK = "leases.lock";
 /** How much of the end of the log `readLog` reads; older entries are not shown. */
 export const LOG_TAIL_BYTES = 512 * 1024;
 /**
@@ -462,6 +464,22 @@ export function createStateStore(options = {}) {
         }
         writeJson(BUS_FILE, { sessions });
     }
+    function readLeases() {
+        return readJson(LEASES_FILE, {});
+    }
+    /**
+     * Atomic lease check-then-take/update. The callback mutates the map and its
+     * return value goes to the caller; the map is persisted while the state lock
+     * is held, so two processes racing to take one pane cannot both win.
+     */
+    function withLeases(fn) {
+        return withFileLock(LEASES_LOCK, () => {
+            const leases = readJson(LEASES_FILE, {});
+            const result = fn(leases);
+            writeJson(LEASES_FILE, leases);
+            return result;
+        });
+    }
     /** Test helper: drop everything this store wrote. */
     function reset() {
         rmSync(dir, { recursive: true, force: true });
@@ -480,6 +498,8 @@ export function createStateStore(options = {}) {
         readBus,
         writeBus,
         clearBus,
+        readLeases,
+        withLeases,
         reset,
     };
 }

package/dist/zellij/args.d.ts

@@ -83,7 +83,7 @@ export declare function buildLaunchPluginArgs(input: LaunchPluginInput): string[
 export declare function buildListPanesArgs(session: string): string[];
 export declare function buildPasteArgs(session: string, paneId: string, text: string): string[];
 export declare function buildSendEnterArgs(session: string, paneId: string): string[];
-export declare function buildDumpArgs(session: string, paneId: string, full?: boolean): string[];
+export declare function buildDumpArgs(session: string, paneId: string, full?: boolean, ansi?: boolean): string[];
 export declare function buildSendKeysArgs(session: string, paneId: string, keys: string[]): string[];
 export declare function buildWriteCharsArgs(session: string, paneId: string, chars: string): string[];
 export declare function buildRenamePaneArgs(session: string, paneId: string, name: string): string[];

package/dist/zellij/args.js

@@ -122,7 +122,7 @@ export function buildSendEnterArgs(session, paneId) {
         "Enter",
     ];
 }
-export function buildDumpArgs(session, paneId, full = false) {
+export function buildDumpArgs(session, paneId, full = false, ansi = false) {
     const args = [
         ...sessionPrefix(session),
         "action",
@@ -132,6 +132,8 @@ export function buildDumpArgs(session, paneId, full = false) {
     ];
     if (full)
         args.push("--full");
+    if (ansi)
+        args.push("--ansi");
     return args;
 }
 export function buildSendKeysArgs(session, paneId, keys) {

package/dist/zellij/bus.js

@@ -295,6 +295,7 @@ export function busToPanes(snapshot) {
             focused: pane.focused,
             exited: pane.exited,
             floating: false,
+            contentColumns: null,
         };
     });
 }

package/dist/zellij/client.d.ts

@@ -59,6 +59,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         session: string;
         paneId: string;
         full?: boolean;
+        ansi?: boolean;
         timeoutMs?: number;
     }) => Promise<{
         paneId: string;

package/dist/zellij/client.js

@@ -209,7 +209,7 @@ export function createZellijClient(options = {}) {
     }
     async function dumpPane(input) {
         const paneId = normalizePaneId(input.paneId);
-        const result = await run(buildDumpArgs(input.session, paneId, input.full), "zellij action dump-screen", input.timeoutMs ?? timeoutMs);
+        const result = await run(buildDumpArgs(input.session, paneId, input.full, input.ansi), "zellij action dump-screen", input.timeoutMs ?? timeoutMs);
         return { paneId, session: input.session, text: result.stdout };
     }
     async function sendKeys(input) {

package/dist/zellij/panes.d.ts

@@ -10,6 +10,7 @@ export type ZellijPane = {
     focused: boolean;
     exited: boolean;
     floating: boolean;
+    contentColumns: number | null;
 };
 export declare function normalizePaneId(raw: string, isPlugin?: boolean): string;
 /** Parse `list-panes --json` output. */

package/dist/zellij/panes.js

@@ -32,6 +32,9 @@ function parsePaneRow(row) {
         focused: row.is_focused === true,
         exited: row.exited === true,
         floating: row.is_floating === true,
+        contentColumns: typeof row.pane_content_columns === "number"
+            ? row.pane_content_columns
+            : null,
     };
 }
 /** Parse `list-panes --json` output. */

package/package.json

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