@zswarm/core 0.2.3 → 0.2.5

package/dist/host/crew.js

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

package/dist/host/lease.d.ts

@@ -0,0 +1,68 @@
+import type { LeaseRecord, StateStore } from "../state.js";
+/**
+ * Pane leases: a relay holds one on its target pane from before it sends until
+ * it ends, so a second relay or `send --if-idle` can refuse (or wait) instead
+ * of interleaving two tasks in one agent pane.
+ *
+ * The record lives in the zswarm state dir and is only ever read or written
+ * inside `StateStore.withLeases`, whose file lock serializes check-then-take
+ * across processes. A lease whose relay directory is gone or has finished is
+ * stale and is taken over.
+ */
+export type LeaseTarget = {
+    /** The serve endpoint that owns the pane, or undefined for a local pane. */
+    serve?: string;
+    session?: string;
+    /** The pane address as `--to` gives it (id, title or command). */
+    pane: string;
+};
+export type LeaseTakeInput = {
+    relayId: string;
+    from: string;
+    at: number;
+    dir: string;
+    target: LeaseTarget;
+    /** Send anyway: add this relay to the holder's shared list. */
+    force?: boolean;
+};
+export type LeaseTakeResult = {
+    ok: true;
+    lease: LeaseRecord;
+    shared: boolean;
+} | {
+    ok: false;
+    holder: LeaseRecord;
+};
+/** The target identity: serve endpoint (or `local`), session and pane address. */
+export declare function leaseKey(target: LeaseTarget): string;
+type LeaseJob = {
+    kind?: unknown;
+    pid?: unknown;
+    label?: unknown;
+    unit?: unknown;
+};
+export type LeaseStaleDeps = {
+    now?: () => number;
+    /** Whether a launchd/systemd relay job is still loaded; injected in tests. */
+    jobRunning?: (job: LeaseJob) => boolean | undefined;
+};
+export declare function leaseStale(rec: LeaseRecord, deps?: LeaseStaleDeps): boolean;
+/** Live leases only; stale records are dropped from the store as they are seen. */
+export declare function listLeases(store: StateStore, deps?: LeaseStaleDeps): LeaseRecord[];
+/** The live lease for a target, if any. */
+export declare function findLease(store: StateStore, target: LeaseTarget, deps?: LeaseStaleDeps): LeaseRecord | undefined;
+/**
+ * Take the lease for a target. Returns the holder when a live lease is already
+ * held (caller decides: refuse, `--queue`, or `--force`). `force` shares the
+ * holder's lease by recording the new relay id.
+ */
+export declare function takeLease(store: StateStore, input: LeaseTakeInput): LeaseTakeResult;
+/**
+ * Release a target's lease. With `relayId`, the lease is dropped only when that
+ * relay is the holder; a forced relay that ends is removed from `sharedBy` and
+ * the original holder keeps the lease.
+ */
+export declare function releaseLease(store: StateStore, target: LeaseTarget, relayId?: string): boolean;
+/** `releaseLease` by the already-recorded key (the relay config stores it). */
+export declare function releaseLeaseKey(store: StateStore, key: string, relayId?: string): boolean;
+export {};

package/dist/host/lease.js

@@ -0,0 +1,138 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The target identity: serve endpoint (or `local`), session and pane address. */
+export function leaseKey(target) {
+    return [target.serve?.trim() || "local", target.session?.trim() ?? "", target.pane.trim()].join("|");
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH: gone. EPERM: exists, just unsignalable — still a live holder.
+        return err.code === "EPERM";
+    }
+}
+/**
+ * A lease is stale when its relay no longer runs: the run directory is gone,
+ * the relay recorded a final status or was cancelled, its message is written,
+ * or its plain detached pid is dead. (launchd/systemd jobs write a status on
+ * every final path; a killed job without one is recovered by `--cancel`.)
+ */
+/** Minutes past a relay's max age before its lease is dropped regardless. */
+const LEASE_GRACE_MIN = 5;
+/** True while a launchd label or systemd user unit is still loaded; undefined for other jobs. */
+function serviceJobRunning(job) {
+    if (job.kind === "launchd" && typeof job.label === "string") {
+        return spawnSync("launchctl", ["list", job.label], { stdio: "ignore" }).status === 0;
+    }
+    if (job.kind === "systemd" && typeof job.unit === "string") {
+        const res = spawnSync("systemctl", ["--user", "is-active", job.unit], { encoding: "utf8" });
+        return res.status === 0 && /^(active|activating|reloading)$/.test((res.stdout ?? "").trim());
+    }
+    return undefined;
+}
+export function leaseStale(rec, deps = {}) {
+    if (!rec.dir || !existsSync(rec.dir))
+        return true;
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(join(rec.dir, "config.json"), "utf8"));
+    }
+    catch {
+        return true;
+    }
+    if (cfg.cancelled === true || typeof cfg.status === "string")
+        return true;
+    if (existsSync(join(rec.dir, "message.txt")))
+        return true;
+    const job = cfg.job;
+    if (job && job.kind === "pid" && typeof job.pid === "number" && !pidAlive(job.pid))
+        return true;
+    // A launchd/systemd relay that is no longer loaded ended without a final
+    // status (removed by hand, killed, or the machine restarted).
+    if (job && (deps.jobRunning ?? serviceJobRunning)(job) === false)
+        return true;
+    // Backstop: a relay always ends by its max age, so its lease cannot outlive
+    // it (this also covers a pid that was reused by another process).
+    const maxAgeMin = typeof cfg.maxAgeMin === "number" ? cfg.maxAgeMin
+        : typeof cfg.timeoutMin === "number" ? cfg.timeoutMin + 60
+            : undefined;
+    if (maxAgeMin !== undefined && (deps.now ?? Date.now)() > rec.at + (maxAgeMin + LEASE_GRACE_MIN) * 60_000)
+        return true;
+    return false;
+}
+/** Live leases only; stale records are dropped from the store as they are seen. */
+export function listLeases(store, deps = {}) {
+    return store.withLeases((leases) => {
+        for (const [key, rec] of Object.entries(leases)) {
+            if (leaseStale(rec, deps))
+                delete leases[key];
+        }
+        return Object.values(leases);
+    });
+}
+/** The live lease for a target, if any. */
+export function findLease(store, target, deps = {}) {
+    const rec = store.readLeases()[leaseKey(target)];
+    return rec && !leaseStale(rec, deps) ? rec : undefined;
+}
+/**
+ * Take the lease for a target. Returns the holder when a live lease is already
+ * held (caller decides: refuse, `--queue`, or `--force`). `force` shares the
+ * holder's lease by recording the new relay id.
+ */
+export function takeLease(store, input) {
+    const key = leaseKey(input.target);
+    return store.withLeases((leases) => {
+        const held = leases[key];
+        // Staleness on the taker's clock: the new lease's `at` is its now.
+        if (held && !leaseStale(held, { now: () => input.at })) {
+            if (!input.force)
+                return { ok: false, holder: held };
+            const sharedBy = [...new Set([...(held.sharedBy ?? []), input.relayId])];
+            const shared = { ...held, sharedBy };
+            leases[key] = shared;
+            return { ok: true, lease: shared, shared: true };
+        }
+        const lease = {
+            key,
+            relayId: input.relayId,
+            from: input.from,
+            at: input.at,
+            dir: input.dir,
+            serve: input.target.serve,
+            session: input.target.session,
+            pane: input.target.pane,
+        };
+        leases[key] = lease;
+        return { ok: true, lease, shared: false };
+    });
+}
+/**
+ * Release a target's lease. With `relayId`, the lease is dropped only when that
+ * relay is the holder; a forced relay that ends is removed from `sharedBy` and
+ * the original holder keeps the lease.
+ */
+export function releaseLease(store, target, relayId) {
+    return releaseLeaseKey(store, leaseKey(target), relayId);
+}
+/** `releaseLease` by the already-recorded key (the relay config stores it). */
+export function releaseLeaseKey(store, key, relayId) {
+    return store.withLeases((leases) => {
+        const held = leases[key];
+        if (!held)
+            return false;
+        if (!relayId || held.relayId === relayId) {
+            delete leases[key];
+            return true;
+        }
+        if (held.sharedBy?.includes(relayId)) {
+            leases[key] = { ...held, sharedBy: held.sharedBy.filter((id) => id !== relayId) };
+            return true;
+        }
+        return false;
+    });
+}

package/dist/host/relay.d.ts

@@ -1,4 +1,5 @@
 import type { OpsResult } from "../ops/types.js";
+import { type StateStore } from "../state.js";
 /**
  * `zswarm relay`: hand a body to a pane on another host and tell a local pane
  * when the work is done, without anyone polling.
@@ -51,6 +52,8 @@ export type RelayConfig = {
     /** Set by `--cancel`; a late loop must not overwrite it. */
     cancelled?: boolean;
     cancelledAt?: number;
+    /** The pane lease this relay holds; released on every final status. */
+    leaseKey?: string;
 };
 export type RelayDeps = {
     /** dispatchZswarm with an env; injected in tests. */
@@ -101,8 +104,14 @@ export type RelayStartInput = {
     /** Hard cap on the relay's age; defaults to `timeoutMin` plus 60 minutes. */
     maxAgeMin?: number;
     foreground?: boolean;
+    /** Wait for a leased pane to free instead of failing. */
+    queue?: boolean;
+    /** Send to a leased pane anyway; the lease is shared and noted. */
+    force?: boolean;
     env?: NodeJS.ProcessEnv;
     deps?: RelayDeps;
+    /** State store for the pane lease; injected in tests. */
+    store?: StateStore;
     /** Starts the detached relay; injected in tests. */
     launch?: (dir: string, env: NodeJS.ProcessEnv) => string;
 };
@@ -138,6 +147,8 @@ export type RelayJobRunner = (cmd: string, args: string[]) => {
 export type RelayAdminDeps = {
     env?: NodeJS.ProcessEnv;
     now?: () => number;
+    /** State store for the pane leases; injected in tests. */
+    store?: StateStore;
     /** Runs launchctl/systemctl; injected in tests. */
     run?: RelayJobRunner;
     /** Liveness probe for a plain detached pid; injected in tests. */
@@ -160,6 +171,12 @@ export type RelayRow = {
     lastCheck?: number;
     /** The launchd label / systemd unit / pid, when the job is still loaded. */
     job?: string;
+    /** The live pane lease held for this relay's target, if any. */
+    lease?: {
+        relayId: string;
+        from: string;
+        at: number;
+    };
 };
 export type RelayCancelResult = {
     id: string;