@zswarm/core 0.2.2 → 0.2.4

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.
@@ -16,7 +17,14 @@ import type { OpsResult } from "../ops/types.js";
  * message.txt. It reads nothing else, so moving or updating the caller's files
  * while it waits cannot break it.
  */
-export type RelayStatus = "DONE" | "TIMEOUT" | "PANE_DIED" | "SERVE_DOWN" | "UNCONFIRMED";
+export type RelayStatus = "DONE" | "TIMEOUT" | "MAX_AGE" | "CHECK_BROKEN" | "CANCELLED" | "PANE_DIED" | "SERVE_DOWN" | "UNCONFIRMED";
+/** How a detached relay can be stopped: the launchd label, systemd unit, or pid. */
+export type RelayJob = {
+    kind: "launchd" | "systemd" | "pid";
+    label?: string;
+    unit?: string;
+    pid?: number;
+};
 export type RelayConfig = {
     id: string;
     serve: string;
@@ -28,6 +36,8 @@ export type RelayConfig = {
     replySession?: string;
     from: string;
     timeoutMin: number;
+    /** Hard cap on the relay's age; defaults to `timeoutMin` plus 60 minutes. */
+    maxAgeMin?: number;
     check?: string;
     message?: string;
     /**
@@ -35,6 +45,15 @@ export type RelayConfig = {
      * pasted body, an earlier task's done line). Only a line beyond these counts.
      */
     seen?: string[];
+    /** Recorded by launchRelay so `--cancel` can stop the detached job. */
+    job?: RelayJob;
+    /** Final status once the loop ends; absent while the relay runs. */
+    status?: RelayStatus;
+    /** 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. */
@@ -82,9 +101,17 @@ export type RelayStartInput = {
     check?: string;
     message?: string;
     timeoutMin?: number;
+    /** 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;
 };
@@ -112,5 +139,57 @@ export declare function waitForRelay(id: string, opts?: {
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
 }): Promise<string | null>;
+export type RelayJobRunner = (cmd: string, args: string[]) => {
+    status: number;
+    stdout: string;
+    stderr?: 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. */
+    alive?: (pid: number) => boolean;
+    /** Sends SIGTERM to a plain detached pid; injected in tests. */
+    kill?: (pid: number) => void;
+    /** A pid's command line (undefined when unknown); injected in tests. */
+    commandLine?: (pid: number) => string | undefined;
+};
+export type RelayRow = {
+    id: string;
+    dir: string;
+    to: string;
+    session?: string;
+    /** Epoch milliseconds the run started (the `<ts>` in its directory name). */
+    started: number;
+    /** Seconds since it started. */
+    age: number;
+    state: string;
+    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;
+    cancelled: boolean;
+    state: string;
+    reason: string;
+    actions: string[];
+};
+/** One row per relay run directory; newest first. */
+export declare function listRelays(deps?: RelayAdminDeps): RelayRow[];
+/** Stop a running relay's job, mark its directory CANCELLED and scrub its token. */
+export declare function cancelRelay(id: string, deps?: RelayAdminDeps): RelayCancelResult;
+/** Cancel every running relay that targets `to`. */
+export declare function cancelAllTo(to: string, deps?: RelayAdminDeps): RelayCancelResult[];
 /** Remove relay directories and undelivered messages older than `days`. */
 export declare function pruneRelays(days?: number, env?: NodeJS.ProcessEnv): string[];

package/dist/host/relay.js

@@ -4,15 +4,22 @@ 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];
 /** Consecutive matches of the done regex without a passing check before UNCONFIRMED. */
 const CONFIRM_TRIES = 3;
 const SERVE_DOWN_TRIES = 3;
+/** Consecutive identical failing checks before CHECK_BROKEN: a check that can never pass. */
+const CHECK_BROKEN_TRIES = 10;
+/** How long a relay may outlive `--timeout-min` when `--max-age` is not given. */
+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");
 }
@@ -78,6 +85,9 @@ export function fillMessage(template, fields) {
 const DEFAULT_TEMPLATE = "RELAY {id} STATUS {status} pane {pane}\n{output}{note}\n";
 const NOTES = {
     TIMEOUT: "no done line or passing check before the deadline; dump the pane once, do not resend blindly.",
+    MAX_AGE: "the relay reached --max-age without its done line; check the target pane and --done before resending.",
+    CHECK_BROKEN: "the check script failed the same way ten times in a row; fix the check (or --done) before resending.",
+    CANCELLED: "the relay was cancelled before it finished; nothing was pasted.",
     PANE_DIED: "the target pane is gone or exited; check the crew (zswarm crew status) before resending.",
     SERVE_DOWN: "serve was unreachable for three checks in a row; run zswarm doctor against it.",
     UNCONFIRMED: "the pane printed the done line but the check never passed; dump the pane once for the error.",
@@ -130,12 +140,20 @@ export async function relayLoop(dir, deps = {}) {
         ZSWARM_RELAY_PANE: cfg.to,
         ZSWARM_RELAY_DIR: dir,
     });
-    const deadline = now() + cfg.timeoutMin * 60_000;
+    // The timeout is the normal end; --max-age (default timeout + 60 min) is the
+    // hard cap that still ends the relay when a wait or the serve-down backoff
+    // overruns the timeout.
+    const startedAtMs = now();
+    const timeoutAt = startedAtMs + cfg.timeoutMin * 60_000;
+    const maxAgeAt = startedAtMs + (cfg.maxAgeMin ?? cfg.timeoutMin + DEFAULT_MAX_AGE_EXTRA_MIN) * 60_000;
+    const deadline = Math.min(timeoutAt, maxAgeAt);
     let status = "TIMEOUT";
     let output = "";
     let match = "";
     let confirmTries = 0;
     let serveDown = 0;
+    let lastCheckFail;
+    let sameCheckFails = 0;
     log(`relay start id=${cfg.id} to=${cfg.to} serve=${cfg.serve} done=${cfg.done}`);
     while (now() < deadline) {
         const started = now();
@@ -163,6 +181,20 @@ export async function relayLoop(dir, deps = {}) {
                 output = r.stdout;
                 break;
             }
+            // The same failure over and over means the check can never pass for this
+            // pane: end as CHECK_BROKEN rather than polling to the timeout.
+            const sig = `${r.status}:${r.stdout}`;
+            if (sig === lastCheckFail)
+                sameCheckFails += 1;
+            else {
+                lastCheckFail = sig;
+                sameCheckFails = 1;
+            }
+            if (sameCheckFails >= CHECK_BROKEN_TRIES) {
+                status = "CHECK_BROKEN";
+                output = r.stdout;
+                break;
+            }
         }
         else {
             log(`wait ok=${res.ok} matched=${matched}${stale ? " (seen before start)" : ""}`);
@@ -207,6 +239,9 @@ export async function relayLoop(dir, deps = {}) {
         if (matched)
             await sleep(30_000); // the done line stays on screen; give the check time
     }
+    if (status === "TIMEOUT" && maxAgeAt <= timeoutAt && now() >= maxAgeAt)
+        status = "MAX_AGE";
+    writeFinalStatus(dir, status);
     let body;
     if (status !== "DONE" && check) {
         const r = runCheck(check, checkEnv(status, match));
@@ -269,6 +304,18 @@ function updateConfig(dir, patch) {
     const cfg = { ...JSON.parse(readFileSync(path, "utf8")), ...patch };
     writePrivate(path, `${JSON.stringify(cfg, null, 1)}\n`);
 }
+/** Persist the final status unless `--cancel` already marked the relay. */
+function writeFinalStatus(dir, status) {
+    try {
+        const cfg = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+        if (cfg.cancelled || cfg.status === "CANCELLED")
+            return;
+        updateConfig(dir, { status });
+    }
+    catch {
+        // the directory is gone; nothing to record
+    }
+}
 /** Remove the token copy once the relay no longer needs it. */
 export function scrubRelayToken(dir) {
     const path = join(dir, "config.json");
@@ -298,6 +345,7 @@ export function launchRelay(dir, env = process.env) {
         ], { encoding: "utf8" });
         if (res.status !== 0)
             throw new ZellijError("failed", `launchctl submit failed: ${(res.stderr ?? "").trim().slice(0, 200)}`);
+        updateConfig(dir, { job: { kind: "launchd", label } });
         return `launchd job ${label}`;
     }
     if (process.platform === "linux" && spawnSync("systemctl", ["--user", "is-system-running"], { encoding: "utf8" }).status !== null) {
@@ -307,12 +355,16 @@ export function launchRelay(dir, env = process.env) {
             ...(env.ZSWARM_STATE_DIR ? [`--setenv=ZSWARM_STATE_DIR=${env.ZSWARM_STATE_DIR}`] : []),
             ...(env.ZSWARM_RELAY_DELAYS ? [`--setenv=ZSWARM_RELAY_DELAYS=${env.ZSWARM_RELAY_DELAYS}`] : []),
             ...argv], { encoding: "utf8" });
-        if (res.status === 0)
+        if (res.status === 0) {
+            updateConfig(dir, { job: { kind: "systemd", unit } });
             return `systemd unit ${unit}`;
+        }
     }
     const out = openLog(log);
     const child = spawn(argv[0], argv.slice(1), { detached: true, stdio: ["ignore", out, out], env, windowsHide: true });
     child.unref();
+    if (child.pid)
+        updateConfig(dir, { job: { kind: "pid", pid: child.pid } });
     return `pid ${child.pid}`;
 }
 /** A file descriptor the detached child can inherit. */
@@ -340,16 +392,40 @@ export async function startRelay(input) {
         replySession: input.replySession?.trim() || env.ZSWARM_SESSION?.trim() || env.ZELLIJ_SESSION_NAME?.trim() || undefined,
         from: input.from?.trim() || "zswarm-relay",
         timeoutMin: input.timeoutMin ?? 240,
+        maxAgeMin: input.maxAgeMin ?? (input.timeoutMin ?? 240) + DEFAULT_MAX_AGE_EXTRA_MIN,
     };
     // 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);
@@ -368,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
@@ -381,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);
     };
@@ -409,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);
@@ -454,6 +543,199 @@ export async function waitForRelay(id, opts = {}) {
         await sleep(opts.pollMs ?? 15_000);
     }
 }
+/** A pid's command line: `ps` on POSIX, CIM on Windows. */
+function defaultCommandLine(pid) {
+    const res = process.platform === "win32"
+        ? spawnSync("powershell.exe", ["-NoProfile", "-Command",
+            `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`], { encoding: "utf8", windowsHide: true })
+        : spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" });
+    const text = res.status === 0 ? (res.stdout ?? "").trim() : "";
+    return text || undefined;
+}
+const defaultJobRunner = (cmd, args) => {
+    const res = spawnSync(cmd, args, { encoding: "utf8" });
+    return { status: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? (res.error?.message ?? "") };
+};
+/** The run directories under relaysDir, with the start time from each name. */
+function runDirs(root) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const name of readdirSync(root)) {
+        if (name === "undelivered")
+            continue;
+        const path = join(root, name);
+        let isDir = false;
+        try {
+            isDir = statSync(path).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir)
+            continue;
+        const m = /^(.*)-(\d+)$/.exec(name);
+        out.push({
+            id: m ? m[1] : name,
+            dir: path,
+            started: (m ? Number(m[2]) : Math.floor(statSync(path).mtimeMs / 1000)) * 1000,
+        });
+    }
+    return out;
+}
+function readRelayConfig(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The state a relay dir already records: a cancel marker, a final status, a message, else running. */
+function relayState(dir, cfg) {
+    if (cfg?.cancelled || cfg?.status === "CANCELLED")
+        return "cancelled";
+    if (cfg?.status)
+        return cfg.status.toLowerCase();
+    const message = join(dir, "message.txt");
+    if (existsSync(message)) {
+        const m = /^\s*RELAY \S+ STATUS (\S+)/m.exec(readFileSync(message, "utf8"));
+        return (m?.[1] ?? "done").toLowerCase();
+    }
+    return "running";
+}
+/** The last `check=<n>` a relay logged, if any. */
+function lastCheckResult(dir) {
+    try {
+        const matches = [...readFileSync(join(dir, "relay.log"), "utf8").matchAll(/check=(-?\d+)/g)];
+        const last = matches.at(-1)?.[1];
+        return last === undefined ? undefined : Number(last);
+    }
+    catch {
+        return undefined;
+    }
+}
+function jobLabelText(job) {
+    if (job.kind === "launchd")
+        return `launchd job ${job.label}`;
+    if (job.kind === "systemd")
+        return `systemd unit ${job.unit}`;
+    return `pid ${job.pid}`;
+}
+/**
+ * True while the recorded job is still loaded (launchd/systemd), or while the
+ * pid is alive and its command line still names this relay's directory (a
+ * relay that died without a final status leaves a pid another process may reuse).
+ */
+function jobLoaded(job, deps, dir) {
+    const run = deps.run ?? defaultJobRunner;
+    if (job.kind === "launchd" && job.label)
+        return run("launchctl", ["list", job.label]).status === 0;
+    if (job.kind === "systemd" && job.unit) {
+        const res = run("systemctl", ["--user", "is-active", job.unit]);
+        return res.status === 0 && /^(active|activating|reloading)$/.test(res.stdout.trim());
+    }
+    if (job.kind === "pid" && job.pid) {
+        const alive = deps.alive ?? ((pid) => (process.kill(pid, 0), true));
+        try {
+            if (!alive(job.pid))
+                return false;
+        }
+        catch {
+            return false;
+        }
+        return (deps.commandLine ?? defaultCommandLine)(job.pid)?.includes(dir) ?? false;
+    }
+    return false;
+}
+/** One row per relay run directory; newest first. */
+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,
+            to: cfg.to,
+            session: cfg.session,
+            started: run.started,
+            age: Math.max(0, Math.floor((now() - run.started) / 1000)),
+            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);
+}
+function stopJob(job, deps) {
+    const run = deps.run ?? defaultJobRunner;
+    if (job.kind === "launchd" && job.label) {
+        const res = run("launchctl", ["remove", job.label]);
+        if (res.status !== 0)
+            throw new ZellijError("failed", `launchctl remove ${job.label} failed: ${(res.stderr || res.stdout).trim().slice(0, 200)}`);
+    }
+    else if (job.kind === "systemd" && job.unit) {
+        const res = run("systemctl", ["--user", "stop", job.unit]);
+        if (res.status !== 0)
+            throw new ZellijError("failed", `systemctl --user stop ${job.unit} failed: ${(res.stderr || res.stdout).trim().slice(0, 200)}`);
+    }
+    else if (job.kind === "pid" && job.pid) {
+        const kill = deps.kill ?? ((pid) => { process.kill(pid, "SIGTERM"); });
+        kill(job.pid);
+    }
+    else {
+        return "no job recorded; nothing to stop";
+    }
+    return `stopped ${jobLabelText(job)}`;
+}
+/** Stop a running relay's job, mark its directory CANCELLED and scrub its token. */
+export function cancelRelay(id, deps = {}) {
+    const env = deps.env ?? process.env;
+    const now = deps.now ?? Date.now;
+    const match = runDirs(relaysDir(env))
+        .filter((r) => r.id === id)
+        .sort((a, b) => b.started - a.started)[0];
+    if (!match)
+        throw new ZellijError("usage", `no relay ${id}`);
+    const cfg = readRelayConfig(match.dir);
+    if (!cfg)
+        throw new ZellijError("failed", `relay ${id} has no config.json`);
+    const state = relayState(match.dir, cfg);
+    if (state !== "running") {
+        return { id, cancelled: false, state, reason: `relay ${id} is already ${state}; nothing to cancel`, actions: [] };
+    }
+    // Stop only a job that is still this relay's: a crashed relay's label may be
+    // gone and its pid reused. Either way the directory is marked cancelled.
+    const actions = [
+        !cfg.job
+            ? "no job recorded; nothing to stop"
+            : jobLoaded(cfg.job, deps, match.dir)
+                ? stopJob(cfg.job, 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 };
+}
+/** Cancel every running relay that targets `to`. */
+export function cancelAllTo(to, deps = {}) {
+    const env = deps.env ?? process.env;
+    return listRelays({ ...deps, env })
+        .filter((row) => row.to === to && row.state === "running")
+        .map((row) => cancelRelay(row.id, { ...deps, env }));
+}
 /** Remove relay directories and undelivered messages older than `days`. */
 export function pruneRelays(days = 14, env = process.env) {
     const root = relaysDir(env);

package/dist/host/services.d.ts

@@ -48,8 +48,13 @@ export type Runner = (cmd: string, args: string[]) => RunResult;
 export type ServiceState = {
     name: string;
     unit: string;
+    /** Human summary: `running (pid 42)`, `timer every 120 s, loaded`, `not loaded`. */
     state: string;
     active: boolean;
+    /** Main pid when the platform reports one (daemons). */
+    pid?: number;
+    /** Last exit status when the platform reports one. */
+    lastExit?: number;
 };
 export type ServiceHost = {
     account: ServiceAccount;
@@ -61,6 +66,8 @@ export type ServiceHost = {
         exists(path: string): boolean;
         mkdir(path: string): void;
     };
+    /** Synchronous sleep; injected in tests so the launchd wait is instant. */
+    sleep?: (ms: number) => void;
 };
 export declare const defaultRunner: Runner;
 /** The account services are installed for: the current user, or `runAs` when root. */
@@ -87,7 +94,7 @@ export declare function ensureLinger(host: ServiceHost): {
     note?: string;
 };
 export declare function launchdLabel(account: ServiceAccount, name: string): string;
-export declare function launchdPlist(account: ServiceAccount, spec: ServiceSpec): string;
+export declare function launchdPlist(account: ServiceAccount, spec: ServiceSpec, run?: Runner): string;
 /** Write, (re)load and start the services. Returns what it did, one line per unit. */
 export declare function installServices(host: ServiceHost, specs: ServiceSpec[]): {
     lines: string[];
@@ -95,7 +102,7 @@ export declare function installServices(host: ServiceHost, specs: ServiceSpec[])
 };
 /** Stop and delete the services; missing ones are fine. */
 export declare function removeServices(host: ServiceHost, specs: Array<Pick<ServiceSpec, "name" | "kind">>): string[];
-export declare function serviceStates(host: ServiceHost, specs: Array<Pick<ServiceSpec, "name" | "kind">>): ServiceState[];
+export declare function serviceStates(host: ServiceHost, specs: Array<Pick<ServiceSpec, "name" | "kind" | "intervalSec">>): ServiceState[];
 /** Create dir and any missing parents, owned by the account when installing for it. */
 export declare function ensureAccountDir(account: ServiceAccount, dir: string, mode?: number): void;
 /** Write a mode-600 file for the account, creating its directory (700) as needed. */