@zswarm/core 0.2.2 → 0.2.4

package/assets/host-install.sh

@@ -24,6 +24,8 @@ while [ $# -gt 0 ]; do
     *) echo "host-install: unknown argument $1" >&2; exit 2 ;;
   esac
 done
+case "$PREFIX" in /*) ;; *) PREFIX="$(pwd)/$PREFIX" ;; esac
+case "$BIN" in /*) ;; *) BIN="$(pwd)/$BIN" ;; esac
 
 step() { printf '%-10s %s\n' "$1" "$2"; }
 fetch() { curl -fsSL --retry 3 -o "$2" "$1"; }
@@ -95,8 +97,40 @@ if [ "$ZSWARM_VERSION" = latest ] || [ "$have" != "$ZSWARM_VERSION" ]; then
 else
   step zswarm "present $have"
 fi
-ln -sfn "$npm_prefix/bin/zswarm" "$BIN/zswarm"
-ln -sfn "$npm_prefix/bin/zswarm-mcp" "$BIN/zswarm-mcp"
+# The npm bin is `#!/usr/bin/env node`, which sshd, sudo, launchd and systemd
+# cannot run when no node is on PATH. Write a small POSIX sh launcher for each
+# command that execs the Node.js this script installed by absolute path.
+resolve() { # $1 path (possibly through symlinks) -> absolute target path
+  target="$1"
+  while [ -L "$target" ]; do
+    link="$(readlink "$target")"
+    case "$link" in
+      /*) target="$link" ;;
+      *) target="$(dirname "$target")/$link" ;;
+    esac
+  done
+  # npm links with a relative target, so fold away any `..` segments for a
+  # clean absolute path in the launcher. Logical pwd keeps the prefix as given
+  # (on macOS /var is a symlink to /private/var; -P would mix the two).
+  dir="$(cd "$(dirname "$target")" 2>/dev/null && pwd)" || dir="$(dirname "$target")"
+  printf '%s/%s\n' "$dir" "$(basename "$target")"
+}
+write_launcher() { # $1 command name, $2 npm bin symlink to the package script
+  pkg="$(resolve "$2")"
+  if [ ! -f "$pkg" ]; then
+    echo "host-install: cannot find the $1 script at $pkg" >&2
+    exit 1
+  fi
+  rm -f "$BIN/$1"
+  cat > "$BIN/$1" <<EOF
+#!/bin/sh
+# zswarm launcher: exec the Node.js host install pinned, whatever PATH says.
+exec "$node_dir/bin/node" "$pkg" "\$@"
+EOF
+  chmod 0755 "$BIN/$1"
+}
+write_launcher zswarm "$npm_prefix/bin/zswarm"
+write_launcher zswarm-mcp "$npm_prefix/bin/zswarm-mcp"
 
 # --- Zellij ------------------------------------------------------------------
 have_zellij="$("$BIN/zellij" --version 2>/dev/null | awk '{print $2}' || true)"

package/assets/host-report.sh

@@ -7,7 +7,18 @@ v() { "$@" 2>/dev/null | head -1; }
 echo "os=$(uname -s)"
 echo "arch=$(uname -m)"
 echo "user=$(id -un)"
-echo "node=$(v node --version | sed 's/^v//')"
+# node: the runtime zswarm actually uses. When zswarm is a host-install launcher,
+# read the Node.js it execs from the launcher, not the first node on PATH.
+node_bin=""
+zw="$(command -v zswarm 2>/dev/null || true)"
+if [ -n "$zw" ] && [ -f "$zw" ]; then
+  node_bin="$(sed -n 's/^exec "\([^"]*\)".*/\1/p' "$zw" | head -1)"
+fi
+if [ -n "$node_bin" ] && [ -x "$node_bin" ]; then
+  echo "node=$(v "$node_bin" --version | sed 's/^v//')"
+else
+  echo "node=$(v node --version | sed 's/^v//')"
+fi
 zv="$(v zswarm --version)"
 case "$zv" in
   [0-9]*) ;;
@@ -19,6 +30,9 @@ echo "python3=$(v python3 -c 'import platform; print(platform.python_version())'
 echo "disk_home_gb=$(df -Pk "$HOME" 2>/dev/null | awk 'NR==2 {printf "%d", $4/1048576}')"
 echo "disk_tmp_gb=$(df -Pk "${TMPDIR:-/tmp}" 2>/dev/null | awk 'NR==2 {printf "%d", $4/1048576}')"
 echo "sessions=$(zellij list-sessions --no-formatting 2>/dev/null | grep -v EXITED | awk '{print $1}' | tr '\n' ' ')"
+exited_names="$(zellij list-sessions --no-formatting 2>/dev/null | awk '/EXITED/ {print $1}' | tr '\n' ' ')"
+echo "exited_sessions=$(printf '%s' "$exited_names" | wc -w | tr -d ' ')"
+echo "exited_session_names=$exited_names"
 if [ "$(uname -s)" = Linux ]; then
   echo "linger=$(loginctl show-user "$(id -un)" -p Linger --value 2>/dev/null)"
   systemctl --user list-units --all --plain --no-legend 'zswarm-*' 2>/dev/null | awk '{print "service=" $1 " " $3 " " $4}'

package/assets/slot.py

@@ -35,6 +35,7 @@ from __future__ import annotations  # macOS ships Python 3.9
 
 import os
 import re
+import shutil
 import signal
 import subprocess
 import sys
@@ -300,6 +301,39 @@ def main(argv: list[str]) -> int:
     return run(argv, env)
 
 
+def resolve_command(
+    argv: list[str],
+    env: dict[str, str],
+    os_name: str = os.name,
+    which=shutil.which,
+) -> list[str] | str:
+    """Rewrite argv so Windows can start argv[0], including .cmd/.bat shims.
+
+    CreateProcess does not search PATH or apply PATHEXT and cannot start a
+    batch file, so `slot -- pnpm ...` died 127 even though pnpm was on PATH.
+    On Windows, resolve argv[0] with shutil.which against the child's PATH;
+    shutil.which also applies PATHEXT from the environment this process
+    inherits (slot passes that environment straight through). A .cmd/.bat shim
+    runs through the command processor with `cmd.exe /d /s /c` and MS-quoted
+    arguments -- the documented way to run a batch file, and `cmd /c` returns
+    the batch's own exit code. A resolved .exe is spawned directly. POSIX and
+    anything that does not resolve are returned unchanged, so Popen still
+    reports the same FileNotFoundError and 127 as before.
+    """
+    if os_name != "nt" or not argv:
+        return argv
+    exe = which(argv[0], path=env.get("PATH"))
+    if not exe:
+        return argv
+    if Path(exe).suffix.lower() in (".cmd", ".bat"):
+        comspec = env.get("ComSpec") or "cmd.exe"
+        # One command line, handed to CreateProcess as is: a list would be
+        # quoted again by subprocess, and cmd.exe does not understand \".
+        # With /s, cmd strips exactly the outer quote pair and runs the rest.
+        return f'"{comspec}" /d /s /c "{subprocess.list2cmdline([exe, *argv[1:]])}"'
+    return [exe, *argv[1:]]
+
+
 def run(argv: list[str], env: dict[str, str], renice: bool = True) -> int:
     """Run the command as a child and wait. The lock descriptors stay in this
     process (close-on-exec), so a daemon the command leaves behind never
@@ -310,7 +344,7 @@ def run(argv: list[str], env: dict[str, str], renice: bool = True) -> int:
         except OSError:
             pass
     try:
-        child = subprocess.Popen(argv, env=env)
+        child = subprocess.Popen(resolve_command(argv, env), env=env)
     except FileNotFoundError:
         die(f"{argv[0]}: command not found", 127)
     for sig in (signal.SIGINT, signal.SIGTERM, getattr(signal, "SIGHUP", None)):

package/dist/harness.d.ts

@@ -9,6 +9,16 @@ export type HarnessProfile = {
      * against the trailing lines; a hit means the pane wants input, not time.
      */
     waiting: readonly RegExp[];
+    /**
+     * A hint that the harness accepted the paste but queued it behind a running
+     * turn. `send` matches these against the trailing lines after the paste.
+     */
+    queued: readonly RegExp[];
+    /**
+     * A hint that the harness is actively working on a turn. `status` matches
+     * these against the trailing lines to avoid treating a busy pane as idle.
+     */
+    busy: readonly RegExp[];
 };
 /**
  * Identify the harness from a pane's command and title, case-insensitively.
@@ -19,3 +29,13 @@ export declare function resolveHarness(pane: {
     command?: string | null;
     title?: string | null;
 }): HarnessProfile;
+/**
+ * Does this screen's trailing lines show the harness's queued-message hint?
+ * Only the last few lines count: a quoted marker in scrollback is not a queue.
+ */
+export declare function queuedPrompt(screen: string, profile: HarnessProfile): boolean;
+/**
+ * Does this screen's trailing lines show the harness actively working? Only
+ * the last few lines count: a quoted marker in scrollback is not a live turn.
+ */
+export declare function busyPrompt(screen: string, profile: HarnessProfile): boolean;

package/dist/harness.js

@@ -51,10 +51,42 @@ const WAITING = {
     ],
     pi: GENERIC_WAITING,
 };
+/**
+ * Queued-message hints seen live. Claude Code prints
+ * "Press up to edit queued messages" while a turn runs and the pasted body is
+ * held above the prompt. No other harness shows an equally clear marker yet,
+ * so every profile carries only this base set.
+ */
+const GENERIC_QUEUED = [/press up to edit queued messages/i];
+/**
+ * Queued lines per harness. Every observed harness currently carries only the
+ * generic Claude Code hint; add harness-specific patterns here when seen.
+ */
+const QUEUED = {
+    codex: GENERIC_QUEUED,
+    cursor: GENERIC_QUEUED,
+    opencode: GENERIC_QUEUED,
+    gemini: GENERIC_QUEUED,
+    pi: GENERIC_QUEUED,
+};
+/**
+ * Busy (working) markers seen live. OpenCode draws a progress bar of filled
+ * and hollow squares while a turn runs; no other named harness has an equally
+ * reliable marker yet, so they rely on the lease only (`[]`).
+ */
+const BUSY = {
+    codex: [],
+    cursor: [],
+    opencode: [/[■⬝]{4,}/],
+    gemini: [],
+    pi: [],
+};
 const UNKNOWN = {
     name: "unknown",
     submit: "auto",
     waiting: GENERIC_WAITING,
+    queued: GENERIC_QUEUED,
+    busy: [/esc to interrupt/i],
 };
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -99,5 +131,36 @@ export function resolveHarness(pane) {
     const name = matchCommand(pane.command) ?? matchTitle(pane.title) ?? "unknown";
     if (name === "unknown")
         return UNKNOWN;
-    return { name, submit: SUBMIT[name], waiting: WAITING[name] };
+    return {
+        name,
+        submit: SUBMIT[name],
+        waiting: WAITING[name],
+        queued: QUEUED[name],
+        busy: BUSY[name],
+    };
+}
+/**
+ * Does this screen's trailing lines show the harness's queued-message hint?
+ * Only the last few lines count: a quoted marker in scrollback is not a queue.
+ */
+export function queuedPrompt(screen, profile) {
+    const lines = trailingLines(screen);
+    return profile.queued.some((re) => lines.some((line) => re.test(line)));
+}
+/**
+ * Does this screen's trailing lines show the harness actively working? Only
+ * the last few lines count: a quoted marker in scrollback is not a live turn.
+ */
+export function busyPrompt(screen, profile) {
+    const lines = trailingLines(screen);
+    return profile.busy.some((re) => lines.some((line) => re.test(line)));
+}
+/** The six last non-empty, right-trimmed lines of a screen, CR stripped. */
+function trailingLines(screen) {
+    return screen
+        .replace(/\r/g, "")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .slice(-6);
 }

package/dist/host/cli.js

@@ -1,8 +1,10 @@
 import { readFileSync } from "node:fs";
 import { ZellijError } from "../errors.js";
+import { createStateStore } from "../state.js";
 import { crewCheck, crewDown, crewStart, crewStatus, crewUp } from "./crew.js";
 import { hostDoctor, hostInstall, hostInstallArgs, hostScriptPath } from "./host.js";
-import { pruneRelays, runRelayDir, startRelay, waitForRelay } from "./relay.js";
+import { listLeases } from "./lease.js";
+import { cancelAllTo, cancelRelay, listRelays, pruneRelays, runRelayDir, startRelay, waitForRelay } from "./relay.js";
 import { runSlot } from "./slot.js";
 /**
  * Host commands: CLI-only (not MCP ops), because they run long, pass argv
@@ -78,8 +80,37 @@ async function crew(argv) {
             return 2;
     }
 }
+/** A plain-text table for `relay --list`, one row per relay. */
+function relayTable(rows) {
+    const header = ["ID", "STATE", "TO", "SESSION", "AGE", "LAST CHECK", "JOB", "LEASE"];
+    const body = rows.map((r) => [
+        r.id,
+        r.state,
+        r.to,
+        r.session ?? "-",
+        `${r.age}s`,
+        r.lastCheck === undefined ? "-" : String(r.lastCheck),
+        r.job ?? "-",
+        r.lease ? `${r.lease.relayId} (${r.lease.from})` : "-",
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length)));
+    return [header, ...body].map((row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd()).join("\n");
+}
+/** A plain-text table for `relay --leases`, one row per live lease. */
+function leaseTable(leases) {
+    const header = ["KEY", "RELAY", "FROM", "PANE", "SINCE"];
+    const body = leases.map((l) => [
+        l.key,
+        l.relayId,
+        l.from,
+        l.pane,
+        new Date(l.at).toISOString(),
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length)));
+    return [header, ...body].map((row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd()).join("\n");
+}
 async function relay(argv) {
-    const { flags } = parseHostArgs(argv, ["--foreground", "--prune"]);
+    const { flags } = parseHostArgs(argv, ["--foreground", "--prune", "--list", "--leases", "--cancel-all", "--json", "--queue", "--force"]);
     const run = str(flags["--run"]);
     if (run)
         return runRelayDir(run);
@@ -93,6 +124,40 @@ async function relay(argv) {
         process.stdout.write(message);
         return 0;
     }
+    if (flags["--list"] === true) {
+        const rows = listRelays();
+        if (flags["--json"] === true)
+            return json(() => ({ relays: rows }));
+        process.stdout.write(`${relayTable(rows)}\n`);
+        return 0;
+    }
+    if (flags["--leases"] === true) {
+        const leases = listLeases(createStateStore());
+        if (flags["--json"] === true)
+            return json(() => ({ leases }));
+        process.stdout.write(`${leaseTable(leases)}\n`);
+        return 0;
+    }
+    const cancelId = str(flags["--cancel"]);
+    if (cancelId) {
+        const res = cancelRelay(cancelId);
+        if (flags["--json"] === true)
+            return json(() => res);
+        process.stdout.write(`${res.reason}\n`);
+        for (const line of res.actions)
+            process.stdout.write(`${line}\n`);
+        return 0;
+    }
+    if (flags["--cancel-all"] === true) {
+        const to = str(flags["--to"]);
+        if (!to)
+            throw new ZellijError("usage", "relay --cancel-all needs --to PANE");
+        const results = cancelAllTo(to);
+        if (flags["--json"] === true)
+            return json(() => ({ cancelled: results }));
+        process.stdout.write(results.length === 0 ? `no running relays to ${to}\n` : `${results.map((r) => r.reason).join("\n")}\n`);
+        return 0;
+    }
     if (flags["--prune"]) {
         return json(() => ({ removed: pruneRelays(Number(str(flags["--days"]) ?? 14)) }));
     }
@@ -109,7 +174,10 @@ async function relay(argv) {
         check: str(flags["--check"]),
         message: str(flags["--message"]),
         timeoutMin: flags["--timeout-min"] ? Number(str(flags["--timeout-min"])) : undefined,
+        maxAgeMin: flags["--max-age"] ? Number(str(flags["--max-age"])) : undefined,
         foreground: flags["--foreground"] === true,
+        queue: flags["--queue"] === true,
+        force: flags["--force"] === true,
     }));
 }
 async function host(argv) {
@@ -170,9 +238,15 @@ const COMMANDS = {
         usage: [
             "zswarm relay --to PANE --done REGEX --reply-to PANE [--serve TARGET] [--session S] [--body-file F]",
             "             [--reply-session S] [--from NAME] [--check SCRIPT] [--message TEMPLATE] [--id ID]",
-            "             [--timeout-min 240] [--foreground]",
+            "             [--timeout-min 240] [--max-age MIN] [--queue] [--force] [--foreground]",
             "      send the body to PANE over serve (ZSWARM_SERVE / ZSWARM_SERVE_TOKEN), then a detached relay",
-            "      waits for REGEX (and SCRIPT exit 0) and pastes a message into the local --reply-to pane",
+            "      waits for REGEX (and SCRIPT exit 0) and pastes a message into the local --reply-to pane;",
+            "      --max-age (default --timeout-min + 60) is a hard end that always yields a final status",
+            "      it leases its target pane until it ends; a second relay to a leased pane fails pane_leased",
+            "      unless --queue waits for the lease to free or --force shares it",
+            "zswarm relay --list [--json]   id, state, target, session, age, last check, job and lease per relay dir",
+            "zswarm relay --leases [--json]   live pane leases and the relay that holds each",
+            "zswarm relay --cancel ID | --cancel-all --to PANE   stop the job, mark it CANCELLED, paste nothing",
             "zswarm relay --wait ID [--timeout-min 240]   block until relay ID has its message, print it (pull path)",
             "zswarm relay --prune [--days 14]   remove old relay dirs and undelivered messages",
         ].join("\n"),

package/dist/host/crew.d.ts

@@ -12,6 +12,8 @@ export type CrewDeps = {
     };
     /** Live session names; injected in tests. */
     sessions?: (env: NodeJS.ProcessEnv) => Promise<string[]>;
+    /** Exited (resurrectable) session names; injected in tests. */
+    exitedSessions?: (env: NodeJS.ProcessEnv) => Promise<string[]>;
     /** Pane titles (with exited flags) of a session; injected in tests. */
     panes?: (session: string, env: NodeJS.ProcessEnv) => Promise<Array<{
         title: string;

package/dist/host/crew.js

@@ -83,6 +83,14 @@ async function defaultSessions(env) {
         return [];
     return (res.data.sessions ?? []).map((s) => s.name ?? "");
 }
+async function defaultExitedSessions(env) {
+    const res = await dispatchZswarm({ op: "sessions", all: true }, undefined, { env });
+    if (!res.ok)
+        return [];
+    return (res.data.sessions ?? [])
+        .filter((s) => s.exited === true)
+        .map((s) => s.name ?? "");
+}
 async function defaultPanes(session, env) {
     const res = await dispatchZswarm({ op: "list", session }, undefined, { env });
     if (!res.ok)
@@ -252,12 +260,17 @@ export async function crewStatus(input) {
         ? readCrewFiles(crewDir(account, session, env))
         : undefined;
     const live = (await (input.deps?.sessions ?? defaultSessions)(env)).includes(session);
+    const exited = (await (input.deps?.exitedSessions ?? defaultExitedSessions)(env)).includes(session);
     const panes = live ? await (input.deps?.panes ?? defaultPanes)(session, { ...env, ZSWARM_BUS: "0" }) : [];
     out.live = live;
+    out.exited = exited;
     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);
+    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) {

package/dist/host/host.js

@@ -90,6 +90,19 @@ export function hostChecks(facts, services, session) {
     tool("zswarm", true, "zswarm host install");
     tool("zellij", true, "zswarm host install");
     tool("python3", false, "zswarm slot needs Python 3.9+");
+    // Exited sessions are resurrectable leftovers; a pile of them is a warning.
+    if (facts.exited_sessions !== undefined && facts.exited_sessions !== "") {
+        const exited = Number(facts.exited_sessions);
+        if (Number.isFinite(exited)) {
+            checks.push({
+                id: "exited_sessions",
+                state: exited > 10 ? "warn" : "pass",
+                detail: exited > 10
+                    ? `${exited} exited (resurrectable) sessions; prune with zswarm sessions --prune-exited`
+                    : `${exited} exited`,
+            });
+        }
+    }
     for (const id of ["disk_home_gb", "disk_tmp_gb"]) {
         const gb = Number(facts[id]);
         if (!Number.isFinite(gb) || facts[id] === "")

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;
+    });
+}