@zswarm/core 0.2.6 → 0.2.8

package/dist/harness.d.ts

@@ -1,6 +1,17 @@
 export type SubmitStrategy = "auto" | "double-enter";
+/**
+ * How to ask a harness to quit its own UI. A slash command is typed and
+ * submitted; keys are sent raw. `null` means the restart op falls back to
+ * Ctrl+C instead of guessing.
+ */
+export type HarnessExitRecipe = {
+    /** A command line to type into the harness composer, e.g. "/exit". */
+    command?: string;
+    /** Raw keys to send, e.g. ["Ctrl c"]. */
+    keys?: readonly string[];
+};
 export type HarnessProfile = {
-    /** Stable id: "codex" | "cursor" | "opencode" | "gemini" | "pi" | "unknown" */
+    /** Stable id: "codex" | "cursor" | "opencode" | "gemini" | "pi" | "claude" | "unknown" */
     name: string;
     /** What `send` should do when the caller did not pass submit= explicitly. */
     submit: SubmitStrategy;
@@ -19,23 +30,46 @@ export type HarnessProfile = {
      * these against the trailing lines to avoid treating a busy pane as idle.
      */
     busy: readonly RegExp[];
+    /** Program to type in a shell pane to relaunch this harness; null when unknown. */
+    launch: string | null;
+    /** How to ask the harness to quit; null falls back to Ctrl+C. */
+    exit: HarnessExitRecipe | null;
+    /** Trailing lines showing the harness finished starting and is ready for input. */
+    ready: readonly RegExp[];
 };
+type HarnessName = Exclude<HarnessProfile["name"], "unknown">;
 /**
- * Identify the harness from a pane's command and title, case-insensitively.
- * The command is the executable that spawned the pane, so it wins; the title
- * is the fallback for panes launched from a generic shell. Never throws.
+ * The stable, ordered list of known harness names. `--harness` validates
+ * against this and the schema help names it, so both stay in step with PROFILES.
+ */
+export declare const HARNESS_NAMES: readonly HarnessName[];
+/**
+ * Identify the harness, case-insensitively. An explicit `name` is the override
+ * for wrapper-launched panes whose command/title hides the real harness: a
+ * non-empty name must be one of `HARNESS_NAMES` (else `bad_arg`). Without an
+ * override the pane's command wins (the executable that spawned it), then the
+ * title for panes launched from a generic shell, then `unknown`.
  */
 export declare function resolveHarness(pane: {
     command?: string | null;
     title?: string | null;
-}): HarnessProfile;
+}, name?: 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 busy marker regex a screen shows on its trailing lines, or null. Only
  * the last few lines count: a quoted marker in scrollback is not a live turn.
  */
+export declare function busyMarker(screen: string, profile: HarnessProfile): RegExp | null;
+/** Does this screen's trailing lines show the harness actively working? */
 export declare function busyPrompt(screen: string, profile: HarnessProfile): boolean;
+/**
+ * Does this screen's trailing lines show the harness ready for input? An empty
+ * ready set is unknown, never a match: a profile that never declared a marker
+ * must not make the restart op wait forever.
+ */
+export declare function readyPrompt(screen: string, profile: HarnessProfile): boolean;
+export {};

package/dist/harness.js

@@ -1,3 +1,4 @@
+import { ZellijError } from "./errors.js";
 /** Command and title needles observed on real panes in one live session. */
 const PROFILES = [
     { name: "codex", command: ["codex"], title: ["agent-codex"] },
@@ -5,7 +6,13 @@ const PROFILES = [
     { name: "opencode", command: ["opencode"], title: ["agent-opencode"] },
     { name: "gemini", command: ["agy", "gemini"], title: ["agent-gemini"] },
     { name: "pi", command: ["pi"], title: ["agent-pi"] },
+    { name: "claude", command: ["claude"], title: ["agent-claude"] },
 ];
+/**
+ * The stable, ordered list of known harness names. `--harness` validates
+ * against this and the schema help names it, so both stay in step with PROFILES.
+ */
+export const HARNESS_NAMES = PROFILES.map((p) => p.name);
 /**
  * Only codex needs a second Enter to submit: its composer keeps the pasted
  * message (`› [zswarm from=...]`) until an extra Enter lands — verified live
@@ -17,6 +24,7 @@ const SUBMIT = {
     opencode: "auto",
     gemini: "auto",
     pi: "auto",
+    claude: "auto",
 };
 /**
  * Prompt shapes any CLI can show, so every profile carries these as a base.
@@ -50,6 +58,7 @@ const WAITING = {
         /Accept this file edit\?/i,
     ],
     pi: GENERIC_WAITING,
+    claude: [...GENERIC_WAITING, /Do you want to (?:proceed|continue)\?/i],
 };
 /**
  * Queued-message hints seen live. Claude Code prints
@@ -68,6 +77,7 @@ const QUEUED = {
     opencode: GENERIC_QUEUED,
     gemini: GENERIC_QUEUED,
     pi: GENERIC_QUEUED,
+    claude: GENERIC_QUEUED,
 };
 /**
  * Busy (working) markers seen live. OpenCode draws a progress bar of filled
@@ -80,6 +90,47 @@ const BUSY = {
     opencode: [/[■⬝]{4,}/],
     gemini: [],
     pi: [],
+    claude: [/esc to interrupt/i],
+};
+/**
+ * Program to type in a shell pane to start this harness. The first entry of the
+ * harness's command needle is the executable a shell would accept.
+ */
+const LAUNCH = {
+    codex: "codex",
+    cursor: "cursor-agent",
+    opencode: "opencode",
+    gemini: "agy",
+    pi: "pi",
+    claude: "claude",
+};
+/**
+ * How to ask a harness to quit its own UI. `/exit` is documented for OpenCode
+ * and Claude Code; the rest have no equally reliable in-band quit, so they carry
+ * `null` and the restart op falls back to Ctrl+C (twice) after a bounded wait.
+ */
+const EXIT = {
+    codex: null,
+    cursor: null,
+    opencode: { command: "/exit" },
+    gemini: null,
+    pi: null,
+    claude: { command: "/exit" },
+};
+/**
+ * A trailing line that means the harness finished starting and accepts input.
+ * OpenCode's idle screen pins its composer placeholder ("Ask anything…") and
+ * footer ("ctrl+p commands"); Claude Code pins "? for shortcuts". The profiles
+ * whose composer is not known well enough carry `[]`, and the restart op then
+ * falls back to waiting for the screen to settle instead of guessing.
+ */
+const READY = {
+    codex: [],
+    cursor: [],
+    opencode: [/ask anything/i, /ctrl\+p commands/i],
+    gemini: [],
+    pi: [],
+    claude: [/\? for shortcuts/i, /bypass permissions on/i],
 };
 const UNKNOWN = {
     name: "unknown",
@@ -87,6 +138,9 @@ const UNKNOWN = {
     waiting: GENERIC_WAITING,
     queued: GENERIC_QUEUED,
     busy: [/esc to interrupt/i],
+    launch: null,
+    exit: null,
+    ready: [],
 };
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -122,23 +176,40 @@ function matchTitle(title) {
     }
     return null;
 }
-/**
- * Identify the harness from a pane's command and title, case-insensitively.
- * The command is the executable that spawned the pane, so it wins; the title
- * is the fallback for panes launched from a generic shell. Never throws.
- */
-export function resolveHarness(pane) {
-    const name = matchCommand(pane.command) ?? matchTitle(pane.title) ?? "unknown";
-    if (name === "unknown")
-        return UNKNOWN;
+/** Assemble one known profile from the per-name tables, the one assembly path. */
+function profileFor(name) {
     return {
         name,
         submit: SUBMIT[name],
         waiting: WAITING[name],
         queued: QUEUED[name],
         busy: BUSY[name],
+        launch: LAUNCH[name],
+        exit: EXIT[name],
+        ready: READY[name],
     };
 }
+/**
+ * Identify the harness, case-insensitively. An explicit `name` is the override
+ * for wrapper-launched panes whose command/title hides the real harness: a
+ * non-empty name must be one of `HARNESS_NAMES` (else `bad_arg`). Without an
+ * override the pane's command wins (the executable that spawned it), then the
+ * title for panes launched from a generic shell, then `unknown`.
+ */
+export function resolveHarness(pane, name) {
+    const override = name?.trim().toLowerCase();
+    if (override) {
+        const known = HARNESS_NAMES.find((candidate) => candidate === override);
+        if (!known) {
+            throw new ZellijError("bad_arg", `unknown harness "${name.trim()}"; known harnesses: ${HARNESS_NAMES.join(", ")}`);
+        }
+        return profileFor(known);
+    }
+    const inferred = matchCommand(pane.command) ?? matchTitle(pane.title) ?? "unknown";
+    if (inferred === "unknown")
+        return UNKNOWN;
+    return profileFor(inferred);
+}
 /**
  * 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.
@@ -148,12 +219,27 @@ export function queuedPrompt(screen, profile) {
     return profile.queued.some((re) => lines.some((line) => re.test(line)));
 }
 /**
- * Does this screen's trailing lines show the harness actively working? Only
+ * The busy marker regex a screen shows on its trailing lines, or null. Only
  * the last few lines count: a quoted marker in scrollback is not a live turn.
  */
+export function busyMarker(screen, profile) {
+    const lines = trailingLines(screen);
+    return profile.busy.find((re) => lines.some((line) => re.test(line))) ?? null;
+}
+/** Does this screen's trailing lines show the harness actively working? */
 export function busyPrompt(screen, profile) {
+    return busyMarker(screen, profile) !== null;
+}
+/**
+ * Does this screen's trailing lines show the harness ready for input? An empty
+ * ready set is unknown, never a match: a profile that never declared a marker
+ * must not make the restart op wait forever.
+ */
+export function readyPrompt(screen, profile) {
+    if (profile.ready.length === 0)
+        return false;
     const lines = trailingLines(screen);
-    return profile.busy.some((re) => lines.some((line) => re.test(line)));
+    return profile.ready.some((re) => lines.some((line) => re.test(line)));
 }
 /** The six last non-empty, right-trimmed lines of a screen, CR stripped. */
 function trailingLines(screen) {

package/dist/host/cli.js

@@ -84,12 +84,23 @@ async function crew(argv) {
             return 2;
     }
 }
+/** The DELIVERY cell: the recorded verdict, a reply failure, or `-`. */
+function deliveryLabel(delivery) {
+    if (!delivery)
+        return "-";
+    if (delivery.submitted)
+        return delivery.submitted;
+    if (delivery.note)
+        return `failed:${delivery.note}`;
+    return "-";
+}
 /** 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 header = ["ID", "STATE", "DELIVERY", "TO", "SESSION", "AGE", "LAST CHECK", "JOB", "LEASE"];
     const body = rows.map((r) => [
         r.id,
         r.state,
+        deliveryLabel(r.delivery),
         r.to,
         r.session ?? "-",
         `${r.age}s`,
@@ -114,7 +125,7 @@ function leaseTable(leases) {
     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", "--list", "--leases", "--cancel-all", "--json", "--queue", "--force"]);
+    const { flags } = parseHostArgs(argv, ["--foreground", "--prune", "--list", "--leases", "--cancel-all", "--json", "--queue", "--force", "--if-idle"]);
     const run = str(flags["--run"]);
     if (run)
         return runRelayDir(run);
@@ -172,6 +183,7 @@ async function relay(argv) {
         to: str(flags["--to"]) ?? "",
         bodyFile: str(flags["--body-file"]),
         from: str(flags["--from"]),
+        harness: str(flags["--harness"]),
         done: str(flags["--done"]) ?? "",
         replyTo: str(flags["--reply-to"]) ?? "",
         replySession: str(flags["--reply-session"]),
@@ -182,6 +194,7 @@ async function relay(argv) {
         foreground: flags["--foreground"] === true,
         queue: flags["--queue"] === true,
         force: flags["--force"] === true,
+        ifIdle: flags["--if-idle"] === true,
     }));
 }
 async function host(argv) {
@@ -244,14 +257,17 @@ const COMMANDS = {
     relay: {
         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] [--max-age MIN] [--queue] [--force] [--foreground]",
+            "             [--reply-session S] [--from NAME] [--harness NAME] [--check SCRIPT] [--message TEMPLATE] [--id ID]",
+            "             [--timeout-min 240] [--max-age MIN] [--queue] [--force] [--foreground] [--if-idle]",
             "      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;",
+            "      --harness names the target harness and is passed on every send so delivery matches it;",
             "      --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",
+            "      --if-idle applies send's busy check before the lease: a harness that shows it is working fails pane_busy",
+            "      without sending; --queue then waits for the pane to go idle as well as for the lease, and --force skips the check",
+            "zswarm relay --list [--json]   id, state, delivery, 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)",

package/dist/host/relay.d.ts

@@ -25,6 +25,19 @@ export type RelayJob = {
     unit?: string;
     pid?: number;
 };
+/**
+ * The last delivery verdict, persisted so `relay --list` can show whether the
+ * body (and later the reply) actually landed. A verdict is not a failure: the
+ * relay keeps waiting for the done line after recording one.
+ */
+export type RelayDelivery = {
+    /** The op's `submitted` value: "true", "false", "unverified", "queued", "not-delivered". */
+    submitted?: string;
+    /** Epoch milliseconds the verdict was recorded. */
+    at?: number;
+    /** A reply's hard failure code, or a short note about a soft-but-not-ok send. */
+    note?: string;
+};
 export type RelayConfig = {
     id: string;
     serve: string;
@@ -35,6 +48,8 @@ export type RelayConfig = {
     replyTo: string;
     replySession?: string;
     from: string;
+    /** The target harness (`--harness`); sent with the body and the reply. */
+    harness?: string;
     timeoutMin: number;
     /** Hard cap on the relay's age; defaults to `timeoutMin` plus 60 minutes. */
     maxAgeMin?: number;
@@ -49,6 +64,8 @@ export type RelayConfig = {
     job?: RelayJob;
     /** Final status once the loop ends; absent while the relay runs. */
     status?: RelayStatus;
+    /** The last delivery verdict (the initial send, then the reply). */
+    delivery?: RelayDelivery;
     /** Set by `--cancel`; a late loop must not overwrite it. */
     cancelled?: boolean;
     cancelledAt?: number;
@@ -81,6 +98,20 @@ export declare function doneLines(screen: string, done: string): string[];
 export declare function freshDoneLine(screen: string, done: string, seen?: readonly string[]): string | null;
 /** Fill {id} {status} {note} {match} {output} {pane} in a message template. */
 export declare function fillMessage(template: string, fields: Record<string, string>): string;
+/**
+ * True when a send result is only a delivery *verdict*, not a hard failure.
+ *
+ * The op layer reports `ok:false, error.code="not_delivered"` when the pane was
+ * unchanged apart from the composer. That is the op saying "I could not
+ * confirm", not "the send failed": a slow-redrawing pane can still have taken
+ * the body, and a false not-delivered must never kill the relay. `submitted`
+ * values other than `true` (false / "unverified" / "queued") are the same kind
+ * of verdict. Only a hard error is worth aborting on: the pane is gone
+ * (peer_not_found / pane_exited / not_found) or serve/the tunnel is down
+ * (serve_* / connection failures), or the call itself threw. The relay records
+ * the verdict and keeps waiting — the done line is the real proof of delivery.
+ */
+export declare function softSendVerdict(res: OpsResult): boolean;
 /** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
 export declare function deliverMessage(cfg: RelayConfig, body: string, dir: string, deps?: RelayDeps): Promise<boolean>;
 /** The waiting loop; returns the final status and the message it delivered or left behind. */
@@ -95,6 +126,8 @@ export type RelayStartInput = {
     to: string;
     bodyFile?: string;
     from?: string;
+    /** Target harness name; sent with the body and the reply (omitted when absent). */
+    harness?: string;
     done: string;
     replyTo: string;
     replySession?: string;
@@ -108,6 +141,8 @@ export type RelayStartInput = {
     queue?: boolean;
     /** Send to a leased pane anyway; the lease is shared and noted. */
     force?: boolean;
+    /** With --if-idle, check the target harness before the lease: a visibly working pane fails pane_busy. */
+    ifIdle?: boolean;
     env?: NodeJS.ProcessEnv;
     deps?: RelayDeps;
     /** State store for the pane lease; injected in tests. */
@@ -169,6 +204,8 @@ export type RelayRow = {
     age: number;
     state: string;
     lastCheck?: number;
+    /** The last delivery verdict recorded in config.json, for the DELIVERY column. */
+    delivery?: RelayDelivery;
     /** 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. */

package/dist/host/relay.js

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { ZellijError } from "../errors.js";
-import { dispatchZswarm } from "../ops/dispatch.js";
+import { dispatchZswarm, paneBusyMarker } from "../ops/dispatch.js";
 import { resolveServeCliLaunch } from "../ops/serve-install.js";
 import { createStateStore, defaultStateDir } from "../state.js";
 import { findLease, leaseKey, releaseLeaseKey, takeLease } from "./lease.js";
@@ -92,14 +92,35 @@ const NOTES = {
     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.",
 };
+/**
+ * True when a send result is only a delivery *verdict*, not a hard failure.
+ *
+ * The op layer reports `ok:false, error.code="not_delivered"` when the pane was
+ * unchanged apart from the composer. That is the op saying "I could not
+ * confirm", not "the send failed": a slow-redrawing pane can still have taken
+ * the body, and a false not-delivered must never kill the relay. `submitted`
+ * values other than `true` (false / "unverified" / "queued") are the same kind
+ * of verdict. Only a hard error is worth aborting on: the pane is gone
+ * (peer_not_found / pane_exited / not_found) or serve/the tunnel is down
+ * (serve_* / connection failures), or the call itself threw. The relay records
+ * the verdict and keeps waiting — the done line is the real proof of delivery.
+ */
+export function softSendVerdict(res) {
+    if (!res.ok)
+        return res.error.code === "not_delivered";
+    const submitted = res.data?.submitted;
+    return submitted !== true;
+}
 /** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
 export async function deliverMessage(cfg, body, dir, deps = {}) {
     const env = deps.env ?? process.env;
     const call = deps.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
     const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
     const log = deps.log ?? (() => { });
     writeFileSync(join(dir, "message.txt"), body);
     const delays = delaysFrom(env, deps.delays);
+    let failureCode = "failed";
     for (const [i, delay] of delays.entries()) {
         await sleep(delay * 1000);
         // Generous Zellij budgets: this runs exactly when the machine is busiest.
@@ -108,16 +129,23 @@ export async function deliverMessage(cfg, body, dir, deps = {}) {
         };
         if (cfg.replySession)
             args.session = cfg.replySession;
+        if (cfg.harness)
+            args.harness = cfg.harness;
         const res = await call(args, localEnv(env)).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
         if (res.ok) {
-            log(`message attempt ${i + 1}: delivered, submitted=${String(res.data?.submitted)}`);
+            const submitted = String(res.data?.submitted ?? "unknown");
+            recordDelivery(dir, submitted, now());
+            log(`message attempt ${i + 1}: delivered, submitted=${submitted}`);
             return true;
         }
+        failureCode = res.error.code;
         log(`message attempt ${i + 1} failed: ${res.error.code}: ${res.error.message.slice(0, 200)}`);
     }
     const fallback = join(relaysDir(env), "undelivered");
     mkdirSync(fallback, { recursive: true, mode: 0o700 });
     writeFileSync(join(fallback, `${cfg.id}.txt`), body);
+    // The reply never landed: record the last failure code so --list shows failed:<code>.
+    recordDelivery(dir, undefined, now(), failureCode);
     log(`message not delivered after ${delays.length} attempts; left in ${join(fallback, `${cfg.id}.txt`)}`);
     return false;
 }
@@ -304,6 +332,11 @@ function updateConfig(dir, patch) {
     const cfg = { ...JSON.parse(readFileSync(path, "utf8")), ...patch };
     writePrivate(path, `${JSON.stringify(cfg, null, 1)}\n`);
 }
+/** Record the last delivery verdict in config.json; `note` carries a hard failure code. */
+function recordDelivery(dir, submitted, at, note) {
+    const delivery = { ...(submitted ? { submitted } : {}), at, ...(note ? { note } : {}) };
+    updateConfig(dir, { delivery });
+}
 /** Persist the final status unless `--cancel` already marked the relay. */
 function writeFinalStatus(dir, status) {
     try {
@@ -391,6 +424,7 @@ export async function startRelay(input) {
         // The detached job gets a minimal env, so pin the caller's session now.
         replySession: input.replySession?.trim() || env.ZSWARM_SESSION?.trim() || env.ZELLIJ_SESSION_NAME?.trim() || undefined,
         from: input.from?.trim() || "zswarm-relay",
+        harness: input.harness?.trim() || undefined,
         timeoutMin: input.timeoutMin ?? 240,
         maxAgeMin: input.maxAgeMin ?? (input.timeoutMin ?? 240) + DEFAULT_MAX_AGE_EXTRA_MIN,
     };
@@ -404,15 +438,70 @@ export async function startRelay(input) {
     let how;
     const leaseNow = input.deps?.now ?? Date.now;
     const leaseSleep = input.deps?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const call = input.deps?.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e }));
+    const log = input.deps?.log ?? ((line) => appendFileSync(join(dir, "relay.log"), `${new Date().toISOString()} ${line}\n`));
+    const remote = serveEnv(cfg, env);
+    const target = (args) => cfg.session ? { ...args, session: cfg.session } : args;
     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) {
+    /** The pane --to names, with the command/title the harness check needs. */
+    const resolveRemotePane = async () => {
+        const args = { op: "list" };
+        if (cfg.session)
+            args.session = cfg.session;
+        const res = await call(args, remote).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        const panes = res.ok
+            ? res.data.panes ?? []
+            : [];
+        const pane = panes.find((p) => p.title === cfg.to || p.id === cfg.to);
+        return pane ? { command: pane.command, title: pane.title } : { title: cfg.to };
+    };
+    // --if-idle: the same busy check send --if-idle uses, one dump before the
+    // lease is taken. --force skips it, as it skips the lease.
+    const checkIdle = input.ifIdle === true && input.force !== true;
+    const idlePane = checkIdle ? await resolveRemotePane() : undefined;
+    /** The harness working marker one dump of the target shows, or null. */
+    const busyMarkerNow = async () => {
+        const res = await call(target({ op: "dump", to: cfg.to, max: 400 }), remote).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        if (!res.ok)
+            return null; // cannot see the screen: the lease is the only guard
+        return paneBusyMarker(String(res.data?.text ?? ""), idlePane ?? { title: cfg.to }, cfg.harness);
+    };
+    const deadline = leaseNow() + cfg.timeoutMin * 60_000;
+    let busy = null;
+    let taken;
+    if (!input.queue) {
+        if (checkIdle) {
+            busy = await busyMarkerNow();
+            if (busy) {
+                rmSync(dir, { recursive: true, force: true });
+                throw new ZellijError("pane_busy", `pane ${cfg.to} is busy with a task (marker: ${busy}); retry when it is idle`);
+            }
+        }
+        taken = take();
+    }
+    else {
+        // --queue polls the lease and, under --if-idle, the busy marker. The lease
+        // is only taken once the pane is not visibly working.
+        let attempt;
+        for (;;) {
+            if (checkIdle)
+                busy = await busyMarkerNow();
+            attempt = busy ? undefined : take();
+            if (attempt?.ok)
+                break;
+            if (leaseNow() >= deadline)
+                break;
             await leaseSleep(Math.min(LEASE_QUEUE_POLL_MS, Math.max(1, deadline - leaseNow())));
-            taken = take();
         }
+        if (attempt?.ok)
+            taken = attempt;
+        else if (busy) {
+            rmSync(dir, { recursive: true, force: true });
+            throw new ZellijError("pane_busy", `pane ${cfg.to} is busy with a task (marker: ${busy}) and did not free before --timeout-min`);
+        }
+        else
+            taken = attempt ?? take();
     }
     if (!taken.ok) {
         rmSync(dir, { recursive: true, force: true });
@@ -423,16 +512,23 @@ export async function startRelay(input) {
     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);
-            if (!res.ok)
+            const sendArgs = { op: "send", to: cfg.to, body, from: cfg.from, settleMs: 800 };
+            if (cfg.harness)
+                sendArgs.harness = cfg.harness;
+            const res = await call(target(sendArgs), remote);
+            // A non-ok send is only fatal when it is a hard error. `not_delivered` is a
+            // verdict ("could not confirm"), so the relay records it and keeps waiting.
+            if (!res.ok && !softSendVerdict(res)) {
                 throw new ZellijError(res.error.code, `send failed: ${res.error.message}`, res.error.details);
-            sent = res.data?.submitted === true ? "submitted" : "unverified";
+            }
+            const rawSubmitted = res.ok ? res.data?.submitted : undefined;
+            sent = rawSubmitted === true ? "submitted" : "unverified";
+            const submittedText = rawSubmitted === undefined ? (res.ok ? "unverified" : "not-delivered") : String(rawSubmitted);
+            recordDelivery(dir, submittedText, leaseNow(), res.ok ? undefined : res.error.code);
             if (sent !== "submitted") {
+                log(`send verdict submitted=${submittedText}; waiting for the done line`);
                 // One dump; one Enter if the body still sits in the composer.
                 const dump = await call(target({ op: "dump", to: cfg.to, max: 2000 }), remote);
                 const screen = dump.ok ? String(dump.data.text ?? "") : "";
@@ -669,6 +765,7 @@ export function listRelays(deps = {}) {
             age: Math.max(0, Math.floor((now() - run.started) / 1000)),
             state: relayState(run.dir, cfg),
             lastCheck: lastCheckResult(run.dir),
+            ...(cfg.delivery ? { delivery: cfg.delivery } : {}),
             ...(loaded && cfg.job ? { job: jobLabelText(cfg.job) } : {}),
             ...(held ? { lease: { relayId: held.relayId, from: held.from, at: held.at } } : {}),
         });

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { createZellijClient, type ZellijClient, type ZellijClientOptions, type Z
 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 { EXIT_WAIT_MS, HANDOFF_INLINE_MAX, HANDOFF_MARKER, HANDOFF_SELF_WAIT_MS, READY_SETTLE_MS, READY_STABLE_GAP_MS, READY_WAIT_MS, restartLaunchCommand, restartPane, restartPaneKind, type RestartPaneKind, type RestartStep, } from "./ops/restart.js";
+export { busyPrompt, queuedPrompt, readyPrompt, resolveHarness, type HarnessExitRecipe, type HarnessProfile, type SubmitStrategy, } from "./harness.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";
 export { resolveSshTarget } from "./zellij/binary.js";

package/dist/index.js

@@ -12,6 +12,8 @@ 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 { EXIT_WAIT_MS, HANDOFF_INLINE_MAX, HANDOFF_MARKER, HANDOFF_SELF_WAIT_MS, READY_SETTLE_MS, READY_STABLE_GAP_MS, READY_WAIT_MS, restartLaunchCommand, restartPane, restartPaneKind, } from "./ops/restart.js";
+export { busyPrompt, queuedPrompt, readyPrompt, resolveHarness, } from "./harness.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, } from "./policy.js";
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, } from "./exec.js";
 export { resolveSshTarget } from "./zellij/binary.js";