@openrig/cli 0.6.11 → 0.6.12

package/daemon/dist/adapters/tmux-control.d.ts

@@ -0,0 +1,119 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ArgvExecFn } from "./tmux.js";
+/**
+ * tmux commands over one long-lived control-mode client (`tmux -C`) instead of a new tmux client per command. Opt-in:
+ * the daemon drives tmux this way only with OPENRIG_TMUX_CONTROL=1 (startup.ts); without it, every command spawns a
+ * client, as before.
+ *
+ * Each spawned client costs the daemon a fork of its whole process: some 28 ms of CPU a command at its size, against
+ * 0.3 ms for a line written to a client already connected. The client makes a session of its own as it attaches
+ * (`new-session`: an existing session is never taken over, whatever its name), named after this daemon's owner id and
+ * marked with it (`@openrig-control`), and `destroy-unattached`: tmux destroys it when the client leaves, so the daemon
+ * never kills a session itself. Listings leave out this daemon's own session and client, and nothing else: a session
+ * another daemon or a person made, whatever its name or mark, is listed as any other.
+ *
+ * What it runs and what it gives back are the spawned client's: the same commands, their output, the same error text
+ * in `execStderr`, a chain stopped at its first failing command, and output past TMUX_MAX_BUFFER failed with execFile's
+ * `maxBuffer length exceeded`. The differences: a chain's commands are sent one after the other's reply, so another
+ * client's command may run between them, which it cannot in a spawned client's chain; a client that ends partway
+ * through a chain fails the rest at once, the outcome of the commands it sent unknown, and none is run again; and the
+ * blocks tmux's hooks print on their own (an `after-list-panes` in a user's tmux.conf) are not taken for a command's
+ * reply, where a spawned client prints a hook's output after its command's. Anything else (a launch,
+ * which takes the spawning process's environment; `load-buffer`, see ROUTED; a command line that cannot be written on
+ * one line; a global flag; no server yet, or one before 3.2) goes to the spawned client, as before.
+ */
+/** The session option that marks a control session: its value is the owner id of the daemon whose client made it. */
+export declare const CONTROL_OPTION = "@openrig-control";
+/** The name a daemon's control session is made with: one of its own on any server. */
+export declare function controlSessionName(owner: string): string;
+/** The argv's commands, as a spawned tmux reads its arguments (cmd-parse.c): an argument ending in `;` ends its
+ *  command and keeps the rest (`abc;` is `abc`, then a new command); one ending in `\;` is kept with a literal `;`
+ *  instead (`abc\;` is `abc;`). An empty command is skipped. Each argument is then sent quoted, as it reads. */
+export declare function commandsOf(args: string[]): string[][];
+/** What starts each row a listing prints for the owner's own session, its windows, panes and client: drawn for each
+ *  call, so that no other row (whatever its format prints) and no other command's output starts with it. */
+export declare function ownRowTag(): string;
+/** The argv with each listing's `-F` format starting its own rows (the owner's session's, and its client's) with `tag`,
+ *  which `withoutOwnRows` then drops. No `-f` filter: one needs tmux 3.2 (3.4 for list-clients) of the server, which a
+ *  client's own version does not tell. A format is all a row shows, so a listing without `-F` is left as is. */
+export declare function markOwnRows(args: string[], owner: string, tag: string): string[];
+/** A listing's output without the rows `markOwnRows` marked with `tag`. */
+export declare function withoutOwnRows(stdout: string, tag: string): string;
+/** Whether tmux's version (`tmux -V`, or a server's `#{version}`) names 3.2 or later: the client flags of
+ *  `new-session -f`. */
+export declare function supportsControlMode(versionLine: string): boolean;
+/** A command's reply: its output lines, none once they went past the bound (`overflow`). */
+interface Reply {
+    ok: boolean;
+    lines: string[];
+    overflow: boolean;
+}
+interface Pending {
+    resolve: (reply: Reply) => void;
+    reject: (error: Error) => void;
+}
+/** The replies of one control client, read off its stdout: each command's `%begin` … `%end` (or `%error`) block, in
+ *  the order the commands were written. A block ends only on the line that repeats its own `%begin` header, so a pane
+ *  line reading `%end …` never ends it. Only a block whose flags (the header's third field) say the client sent the
+ *  command answers one: a hook (`after-list-panes` in a user's tmux.conf) prints its own blocks, flagged 0, between
+ *  them, and those are no command's reply. A reply keeps at most `maxBytes` of output, as a spawned client's stdout is
+ *  bounded (TMUX_MAX_BUFFER): past it, its lines are dropped as they come, up to its end, so every later reply is still
+ *  its own command's, and it is answered as overflowed. A line with no end yet is bounded the same way. */
+export declare class ControlReplies {
+    private readonly maxBytes;
+    private partial;
+    /** Set while the rest of a line past the bound is dropped, up to its newline. */
+    private skipping;
+    private header;
+    private lines;
+    /** The bytes of the block being read, and whether they went past the bound. */
+    private bytes;
+    private overflow;
+    private readonly pending;
+    /** The first block answers the client's own `new-session`, before any command was written. */
+    private attached;
+    /** Set once the client is gone: nothing will be answered any more. */
+    private failure;
+    /** Called with the outcome of the client's `new-session`: false when it made no session (a name taken). */
+    onAttached?: (ok: boolean) => void;
+    /** Called after each command's reply. */
+    onReply?: () => void;
+    /** Called on tmux's `%sessions-changed`: a session was made or destroyed on the server. */
+    onSessionsChanged?: () => void;
+    constructor(maxBytes?: number);
+    get closed(): boolean;
+    /** The commands written and not answered yet. */
+    get waiting(): number;
+    expect(pending: Pending): void;
+    push(chunk: string): void;
+    /** Drops the block's output once past the bound: only that it overflowed is kept. */
+    private overflowed;
+    private line;
+    /** Fails every command still waiting, and any expected later: the client is gone, so none will be answered. */
+    failAll(error: Error): void;
+}
+/** Starts the control client with these tmux arguments (`spawnTmuxClient`); tests give their own. */
+export type SpawnControlClient = (args: string[]) => ChildProcessWithoutNullStreams | Promise<ChildProcessWithoutNullStreams>;
+export interface TmuxControlOptions {
+    spawnClient?: SpawnControlClient;
+    /** Once the command at the head of the line has had no reply for this long, the client is ended: the reads it owed
+     *  are asked again of a spawned client, the writes it owed fail, and the next command starts a new client. Also the
+     *  time a client has to attach. */
+    replyTimeoutMs?: number;
+    now?: () => number;
+    /** This daemon's id on a tmux server: its control session's name and mark. A random one by default. */
+    owner?: string;
+    /** The most output a call may give, as a spawned client's stdout is bounded: TMUX_MAX_BUFFER by default. */
+    maxBuffer?: number;
+}
+export type TmuxControlExec = ArgvExecFn & {
+    close: () => Promise<void>;
+    owner: string;
+};
+/**
+ * The ArgvExecFn the daemon's TmuxAdapter runs with when control mode is on: routed commands go to the control client,
+ * every other one, or any while the client cannot run, to `fallback` (the spawned client).
+ */
+export declare function tmuxControlExec(fallback: ArgvExecFn, options?: TmuxControlOptions): TmuxControlExec;
+export {};
+//# sourceMappingURL=tmux-control.d.ts.map

package/daemon/dist/adapters/tmux-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux-control.d.ts","sourceRoot":"","sources":["../../src/adapters/tmux-control.ts"],"names":[],"mappings":"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"}

package/daemon/dist/adapters/tmux-control.js

@@ -0,0 +1,547 @@
+import { randomBytes } from "node:crypto";
+import { spawnTmuxClient, TMUX_MAX_BUFFER } from "./tmux-exec.js";
+/**
+ * tmux commands over one long-lived control-mode client (`tmux -C`) instead of a new tmux client per command. Opt-in:
+ * the daemon drives tmux this way only with OPENRIG_TMUX_CONTROL=1 (startup.ts); without it, every command spawns a
+ * client, as before.
+ *
+ * Each spawned client costs the daemon a fork of its whole process: some 28 ms of CPU a command at its size, against
+ * 0.3 ms for a line written to a client already connected. The client makes a session of its own as it attaches
+ * (`new-session`: an existing session is never taken over, whatever its name), named after this daemon's owner id and
+ * marked with it (`@openrig-control`), and `destroy-unattached`: tmux destroys it when the client leaves, so the daemon
+ * never kills a session itself. Listings leave out this daemon's own session and client, and nothing else: a session
+ * another daemon or a person made, whatever its name or mark, is listed as any other.
+ *
+ * What it runs and what it gives back are the spawned client's: the same commands, their output, the same error text
+ * in `execStderr`, a chain stopped at its first failing command, and output past TMUX_MAX_BUFFER failed with execFile's
+ * `maxBuffer length exceeded`. The differences: a chain's commands are sent one after the other's reply, so another
+ * client's command may run between them, which it cannot in a spawned client's chain; a client that ends partway
+ * through a chain fails the rest at once, the outcome of the commands it sent unknown, and none is run again; and the
+ * blocks tmux's hooks print on their own (an `after-list-panes` in a user's tmux.conf) are not taken for a command's
+ * reply, where a spawned client prints a hook's output after its command's. Anything else (a launch,
+ * which takes the spawning process's environment; `load-buffer`, see ROUTED; a command line that cannot be written on
+ * one line; a global flag; no server yet, or one before 3.2) goes to the spawned client, as before.
+ */
+/** The session option that marks a control session: its value is the owner id of the daemon whose client made it. */
+export const CONTROL_OPTION = "@openrig-control";
+/** The name a daemon's control session is made with: one of its own on any server. */
+export function controlSessionName(owner) {
+    return `openrig-control-${owner}`;
+}
+/** What the control session's pane runs, exec'd as argv (no `default-shell -c`, so no shell of the user's and none of
+ *  its rc files): a non-interactive sh that waits forever. */
+const KEEP_ALIVE = ["sh", "-c", "while :; do sleep 86400; done"];
+// Commands that only read the server or write into a pane, whose outcome does not depend on the client that sends
+// them as long as they name their target. A launch or an environment change stays spawned. So does `load-buffer`: it
+// would have the server open the file itself, in its own loop (a FIFO with no writer stops the whole server) and in its
+// own view of the filesystem, where a spawned client reads the file and hands the server its bytes.
+const ROUTED = new Set([
+    "capture-pane", "display-message", "has-session", "list-sessions", "list-windows", "list-panes", "list-clients",
+    "show-environment", "paste-buffer", "delete-buffer", "send-keys",
+]);
+const LISTINGS = new Set(["list-sessions", "list-windows", "list-panes", "list-clients"]);
+/** The routed commands that change nothing, which may be run again after their client is lost. Any other one
+ *  (`send-keys`, `paste-buffer`, `delete-buffer`) is a write: once written, it may have taken effect. */
+const READS = new Set([...LISTINGS, "capture-pane", "display-message", "has-session", "show-environment"]);
+/** Whether a command acts on the same target from any client: a control client's own session would otherwise be the
+ *  "current" one that a target-less command reads. */
+function namesItsTarget(args) {
+    const [command] = args;
+    if (args.includes("-t"))
+        return true;
+    if (command === "list-sessions" || command === "list-clients" || command === "delete-buffer")
+        return true;
+    if (command === "list-windows" || command === "list-panes")
+        return args.includes("-a");
+    if (command === "show-environment")
+        return args.includes("-g");
+    return false;
+}
+/** The argv's commands, as a spawned tmux reads its arguments (cmd-parse.c): an argument ending in `;` ends its
+ *  command and keeps the rest (`abc;` is `abc`, then a new command); one ending in `\;` is kept with a literal `;`
+ *  instead (`abc\;` is `abc;`). An empty command is skipped. Each argument is then sent quoted, as it reads. */
+export function commandsOf(args) {
+    const commands = [];
+    let command = [];
+    for (const arg of args) {
+        if (!arg.endsWith(";")) {
+            command.push(arg);
+            continue;
+        }
+        const rest = arg.slice(0, -1);
+        if (rest.endsWith("\\")) {
+            command.push(`${rest.slice(0, -1)};`);
+            continue;
+        }
+        if (rest !== "")
+            command.push(rest);
+        if (command.length > 0)
+            commands.push(command);
+        command = [];
+    }
+    if (command.length > 0)
+        commands.push(command);
+    return commands;
+}
+/** What starts each row a listing prints for the owner's own session, its windows, panes and client: drawn for each
+ *  call, so that no other row (whatever its format prints) and no other command's output starts with it. */
+export function ownRowTag() {
+    return `${randomBytes(8).toString("hex")}:`;
+}
+/** The argv with each listing's `-F` format starting its own rows (the owner's session's, and its client's) with `tag`,
+ *  which `withoutOwnRows` then drops. No `-f` filter: one needs tmux 3.2 (3.4 for list-clients) of the server, which a
+ *  client's own version does not tell. A format is all a row shows, so a listing without `-F` is left as is. */
+export function markOwnRows(args, owner, tag) {
+    let first = true;
+    let listing = false;
+    return args.map((arg, i) => {
+        let out = arg;
+        if (first) {
+            listing = LISTINGS.has(arg);
+            first = false;
+        }
+        else if (listing && args[i - 1] === "-F" && !arg.endsWith(";")) {
+            out = `#{?#{==:#{${CONTROL_OPTION}},${owner}},${tag},}${arg}`;
+        }
+        if (arg.endsWith(";") && !arg.endsWith("\\;"))
+            first = true;
+        return out;
+    });
+}
+/** A listing's output without the rows `markOwnRows` marked with `tag`. */
+export function withoutOwnRows(stdout, tag) {
+    if (!stdout.includes(tag))
+        return stdout;
+    return stdout.split("\n").filter((line) => !line.startsWith(tag)).join("\n");
+}
+/** One argument on a control-mode command line: in single quotes, where tmux expands nothing; a ' closes them, is
+ *  escaped, and opens them again. */
+function quote(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/** Whether tmux's version (`tmux -V`, or a server's `#{version}`) names 3.2 or later: the client flags of
+ *  `new-session -f`. */
+export function supportsControlMode(versionLine) {
+    const match = /(\d+)\.(\d+)/.exec(versionLine);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    return major > 3 || (major === 3 && Number(match[2]) >= 2);
+}
+/** The replies of one control client, read off its stdout: each command's `%begin` … `%end` (or `%error`) block, in
+ *  the order the commands were written. A block ends only on the line that repeats its own `%begin` header, so a pane
+ *  line reading `%end …` never ends it. Only a block whose flags (the header's third field) say the client sent the
+ *  command answers one: a hook (`after-list-panes` in a user's tmux.conf) prints its own blocks, flagged 0, between
+ *  them, and those are no command's reply. A reply keeps at most `maxBytes` of output, as a spawned client's stdout is
+ *  bounded (TMUX_MAX_BUFFER): past it, its lines are dropped as they come, up to its end, so every later reply is still
+ *  its own command's, and it is answered as overflowed. A line with no end yet is bounded the same way. */
+export class ControlReplies {
+    maxBytes;
+    partial = "";
+    /** Set while the rest of a line past the bound is dropped, up to its newline. */
+    skipping = false;
+    header = null;
+    lines = [];
+    /** The bytes of the block being read, and whether they went past the bound. */
+    bytes = 0;
+    overflow = false;
+    pending = [];
+    /** The first block answers the client's own `new-session`, before any command was written. */
+    attached = false;
+    /** Set once the client is gone: nothing will be answered any more. */
+    failure = null;
+    /** Called with the outcome of the client's `new-session`: false when it made no session (a name taken). */
+    onAttached;
+    /** Called after each command's reply. */
+    onReply;
+    /** Called on tmux's `%sessions-changed`: a session was made or destroyed on the server. */
+    onSessionsChanged;
+    constructor(maxBytes = TMUX_MAX_BUFFER) {
+        this.maxBytes = maxBytes;
+    }
+    get closed() {
+        return this.failure !== null;
+    }
+    /** The commands written and not answered yet. */
+    get waiting() {
+        return this.pending.length;
+    }
+    expect(pending) {
+        if (this.failure)
+            pending.reject(this.failure);
+        else
+            this.pending.push(pending);
+    }
+    push(chunk) {
+        this.partial += chunk;
+        let newline;
+        while ((newline = this.partial.indexOf("\n")) >= 0) {
+            const line = this.partial.slice(0, newline).replace(/\r$/, "");
+            this.partial = this.partial.slice(newline + 1);
+            if (this.skipping)
+                this.skipping = false;
+            else
+                this.line(line);
+        }
+        // In bytes, as the bound is: a UTF-16 unit is 1 to 3 bytes, so the count is taken only when the length cannot tell.
+        const units = this.partial.length;
+        if (units > this.maxBytes || (units * 3 > this.maxBytes && Buffer.byteLength(this.partial) > this.maxBytes)) {
+            this.partial = "";
+            this.skipping = true;
+            this.overflowed();
+        }
+    }
+    /** Drops the block's output once past the bound: only that it overflowed is kept. */
+    overflowed() {
+        if (this.header === null)
+            return;
+        this.overflow = true;
+        this.lines = [];
+    }
+    line(line) {
+        if (this.header === null) {
+            if (line.startsWith("%begin ")) {
+                this.header = line.slice("%begin ".length);
+                this.lines = [];
+                this.bytes = 0;
+                this.overflow = false;
+            }
+            else if (line === "%sessions-changed") {
+                this.onSessionsChanged?.();
+            }
+            return;
+        }
+        if (line === `%end ${this.header}` || line === `%error ${this.header}`) {
+            const ok = line.startsWith("%end ");
+            const flags = Number(this.header.split(" ")[2]);
+            this.header = null;
+            if (!this.attached) {
+                this.attached = true;
+                this.onAttached?.(ok);
+                return;
+            }
+            if ((flags & 1) === 0)
+                return;
+            this.pending.shift()?.resolve({ ok, lines: this.lines, overflow: this.overflow });
+            this.onReply?.();
+            return;
+        }
+        if (this.overflow)
+            return;
+        this.bytes += Buffer.byteLength(line) + 1;
+        if (this.bytes > this.maxBytes)
+            this.overflowed();
+        else
+            this.lines.push(line);
+    }
+    /** Fails every command still waiting, and any expected later: the client is gone, so none will be answered. */
+    failAll(error) {
+        this.failure ??= error;
+        for (const p of this.pending.splice(0))
+            p.reject(error);
+    }
+}
+/** The error a spawned tmux would have thrown for this failure: tmux's text on stderr, the earlier commands' output on
+ *  stdout. Its message is execFile's (the command, then stderr as is), with the output `execArgvCommand` appends to it. */
+function commandFailed(argv, stdout, stderr) {
+    const message = `Command failed: ${argv.join(" ")}\n${stderr}`;
+    const output = [stdout.trim(), stderr.trim()].filter(Boolean).join("\n");
+    return Object.assign(new Error(output && !message.includes(output) ? `${message}\n${output}` : message), {
+        code: 1, stdout, stderr, execStderr: stderr,
+    });
+}
+/** The error a spawned client's call fails with once its stdout is past its bound (execFile's maxBuffer): the same
+ *  first line, which callers match (`capturePanesContent` splits its chain on it), and tmux's stderr empty. */
+function outputTooLarge(stdout) {
+    return Object.assign(new RangeError("stdout maxBuffer length exceeded"), {
+        code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", stdout, stderr: "", execStderr: "",
+    });
+}
+const RETRY_MS = [1_000, 5_000, 30_000];
+const NOT_WRITTEN = new Error("tmux control client ended before the command was written");
+/** How long the end of a client (its input closed) may take before it is killed. */
+const END_MS = 2_000;
+/**
+ * The ArgvExecFn the daemon's TmuxAdapter runs with when control mode is on: routed commands go to the control client,
+ * every other one, or any while the client cannot run, to `fallback` (the spawned client).
+ */
+export function tmuxControlExec(fallback, options = {}) {
+    const owner = options.owner ?? randomBytes(4).toString("hex");
+    const spawnClient = options.spawnClient ?? spawnTmuxClient;
+    const replyTimeoutMs = options.replyTimeoutMs ?? 10_000;
+    const maxBuffer = options.maxBuffer ?? TMUX_MAX_BUFFER;
+    const now = options.now ?? (() => Date.now());
+    let client = null;
+    let starting = null;
+    let failures = 0;
+    let retryAt = 0;
+    let closed = false;
+    /** Every client of this daemon still running: the current one, one attaching, and those retiring. */
+    const live = new Set();
+    /** Gives up the attach under way: the daemon is stopping. */
+    let cancelAttach = null;
+    const backOff = () => {
+        retryAt = now() + RETRY_MS[Math.min(failures, RETRY_MS.length - 1)];
+        failures++;
+    };
+    /** Ends a client at once and fails what it still owes. The current one, when it ended on its own, is started again
+     *  after a while; when dropped for a reply overdue, at the next command. */
+    const drop = (c, reason, overdue = false) => {
+        clearTimeout(c.timer);
+        c.replies.failAll(new Error(`tmux control client ended: ${reason}`));
+        if (c.child.exitCode === null && c.child.signalCode === null)
+            c.child.kill();
+        if (client !== c)
+            return;
+        client = null;
+        if (overdue)
+            retryAt = 0;
+        else
+            backOff();
+    };
+    /** Ends a client as tmux ends one whose input closes: it detaches, after answering what it was sent, and tmux
+     *  destroys its session (`destroy-unattached`). Killed if it has not gone within END_MS. */
+    const end = (c) => new Promise((resolve) => {
+        if (!live.has(c)) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            drop(c, "did not end");
+            resolve();
+        }, END_MS);
+        c.child.once("exit", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        c.child.stdin.end();
+    });
+    /** Takes no new call on the client, and ends it once the calls running on it are done. */
+    const retire = (c) => {
+        c.retiring = true;
+        if (client === c) {
+            client = null;
+            retryAt = 0;
+        }
+        if (c.users === 0)
+            void end(c);
+    };
+    /** Drops the client once the command at the head of its line has waited past the reply timeout: every later command
+     *  waits behind it, a write with no deadline of its own included. */
+    const watch = (c) => {
+        clearTimeout(c.timer);
+        if (c.replies.waiting === 0)
+            return;
+        c.timer = setTimeout(() => {
+            if (now() - c.headSince >= replyTimeoutMs)
+                drop(c, `no reply within ${replyTimeoutMs} ms`, true);
+            else
+                watch(c);
+        }, Math.max(0, c.headSince + replyTimeoutMs - now()));
+        c.timer.unref?.();
+    };
+    /** The control client's arguments: a session of its own, made as it attaches and never one that exists, marked with
+     *  this daemon's id, destroyed by tmux once no client is in it, and never moving its client elsewhere when it goes. */
+    const clientArgs = () => [
+        "-C", "new-session", "-s", controlSessionName(owner), "-x", "80", "-y", "24", "-f", "no-output,ignore-size",
+        "--", ...KEEP_ALIVE,
+        ";", "set-option", CONTROL_OPTION, owner,
+        ";", "set-option", "destroy-unattached", "on",
+        ";", "set-option", "detach-on-destroy", "on",
+    ];
+    /** Whether a server runs that a control client may attach to: one of tmux 3.2 or later (its own version, not the
+     *  tmux binary's) with a session that is no control session, read by a spawned client. With none, no client is
+     *  started: it never starts a server, nor keeps one up that would exit without it (`checkAlone`). */
+    const serverReady = async () => {
+        try {
+            const rows = (await fallback(["tmux", "list-sessions", "-F", `#{version}|#{${CONTROL_OPTION}}`])).split("\n").filter(Boolean);
+            return supportsControlMode(rows[0] ?? "") && rows.some((row) => row.endsWith("|"));
+        }
+        catch {
+            return false;
+        }
+    };
+    const start = async () => {
+        if (!await serverReady()) {
+            backOff();
+            return null;
+        }
+        if (closed)
+            return null;
+        let child;
+        try {
+            child = await spawnClient(clientArgs());
+        }
+        catch {
+            backOff(); // tmux could not be started at all: asked again later, not at every command.
+            return null;
+        }
+        const replies = new ControlReplies(maxBuffer);
+        const started = { child, replies, headSince: 0, users: 0, retiring: false };
+        live.add(started);
+        replies.onReply = () => {
+            started.headSince = now();
+            watch(started);
+        };
+        replies.onSessionsChanged = () => checkAlone(started);
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => replies.push(chunk));
+        child.stderr.resume();
+        child.on("error", (err) => {
+            if (child.pid === undefined)
+                live.delete(started); // never started: no exit will follow
+            drop(started, err.message);
+        });
+        child.on("exit", (code, signal) => {
+            live.delete(started);
+            drop(started, `exited (${signal ?? code})`);
+        });
+        child.stdin.on("error", (err) => drop(started, err.message));
+        // Its output closed, nothing will be answered: what it owes settles now, not at its reply timeout.
+        child.stdout.on("close", () => drop(started, "its output closed"));
+        // The daemon's exit is never held by its control client.
+        child.unref();
+        for (const stream of [child.stdin, child.stdout, child.stderr])
+            stream.unref?.();
+        const attached = await new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), replyTimeoutMs);
+            const settle = (ok) => {
+                clearTimeout(timer);
+                cancelAttach = null;
+                resolve(ok);
+            };
+            replies.onAttached = settle;
+            cancelAttach = () => settle(false);
+            child.once("exit", () => settle(false));
+            // A spawn error may come without an exit: nothing runs, so nothing will attach.
+            child.once("error", () => settle(false));
+            if (closed)
+                settle(false);
+        });
+        client = started;
+        if (!attached || closed) {
+            drop(started, closed ? "closed" : "did not attach");
+            return null;
+        }
+        failures = 0;
+        // The server may have lost its last other session while this one was made.
+        checkAlone(started);
+        return started;
+    };
+    const connected = async () => {
+        if (closed)
+            return null;
+        if (client)
+            return client;
+        if (now() < retryAt)
+            return null;
+        starting ??= start().finally(() => { starting = null; });
+        return starting;
+    };
+    /** One command's reply, or the client's end: the whole line is failed when its head waits too long (`watch`), so no
+     *  command waits behind a client that stopped answering, and every reply stays its own command's. */
+    const send = (target, args) => new Promise((resolve, reject) => {
+        // A chain's client may have ended after an earlier command's reply, or be ending: nothing is written to it.
+        if (target.replies.closed || target.child.stdin.writableEnded) {
+            reject(NOT_WRITTEN);
+            return;
+        }
+        if (target.replies.waiting === 0)
+            target.headSince = now();
+        target.replies.expect({ resolve, reject });
+        target.child.stdin.write(`${args.map(quote).join(" ")}\n`);
+        watch(target);
+    });
+    /** Retires the client once every session left on the server is a control session, this daemon's or another's:
+     *  it would otherwise keep up a server that, as with spawned clients only, exits with its last session. Asked as the
+     *  client attaches and at each `%sessions-changed`; a later command starts a client again while sessions remain. */
+    const checkAlone = (c) => {
+        if (client !== c)
+            return;
+        send(c, ["list-sessions", "-F", `#{${CONTROL_OPTION}}`]).then((reply) => {
+            if (reply.ok && !reply.overflow && reply.lines.every((line) => line !== ""))
+                retire(c);
+        }, () => { });
+    };
+    /** The error of a write whose client ended before its reply, with what a spawned client finds of its target now: a
+     *  server or session gone reads as a spawned client's failure would (`no server running`, `can't find session`), so
+     *  the adapter classifies it the same way. A client dropped for no reply is not asked about: the server is not
+     *  answering, and a spawned client would wait on it as long. */
+    const failedWrite = async (command, err) => {
+        const t = command.indexOf("-t");
+        if (err.message.includes("no reply within") || t < 0 || t + 1 >= command.length)
+            return err;
+        try {
+            await fallback(["tmux", "display-message", "-p", "-t", command[t + 1], ""]);
+            return err;
+        }
+        catch (probe) {
+            const stderr = probe.execStderr;
+            return Object.assign(new Error(`${err.message}; then ${probe.message}`), typeof stderr === "string" ? { execStderr: stderr } : {});
+        }
+    };
+    const exec = async (argvIn) => {
+        const [bin, ...argsIn] = argvIn;
+        const commandsIn = commandsOf(argsIn);
+        const routable = bin === "tmux" && argsIn.length > 0 && !argsIn[0].startsWith("-") && commandsIn.length > 0
+            && commandsIn.every((c) => ROUTED.has(c[0]) && namesItsTarget(c))
+            && argsIn.every((a) => !/[\n\r\0]/.test(a));
+        // Every listing leaves this daemon's own rows out, from the first one on: its session may be made by the very call
+        // that lists, or by another one under way. A row is marked only on this daemon's own mark, so before its session
+        // exists the output is unchanged.
+        const marked = bin === "tmux" && commandsIn.some((c) => LISTINGS.has(c[0]));
+        const tag = marked ? ownRowTag() : "";
+        const argv = marked ? [bin, ...markOwnRows(argsIn, owner, tag)] : argvIn;
+        const own = (text) => marked ? withoutOwnRows(text, tag) : text;
+        const target = routable ? await connected() : null;
+        if (!target)
+            return own(await fallback(argv));
+        target.users++;
+        try {
+            const commands = commandsOf(argv.slice(1));
+            let stdout = "";
+            let bytes = 0;
+            for (const [index, command] of commands.entries()) {
+                let reply;
+                try {
+                    reply = await send(target, command);
+                }
+                catch (err) {
+                    // The call is run again by a spawned client only when no write of it was written: reads, and a write that
+                    // never reached the client. A write that was (this one, or one earlier in the chain) may have taken effect,
+                    // so the call fails, and the commands before this one are not run again.
+                    const written = commands.slice(0, err === NOT_WRITTEN ? index : index + 1);
+                    if (written.some((c) => !READS.has(c[0])))
+                        throw await failedWrite(command, err);
+                    return own(await fallback(argv));
+                }
+                const output = reply.lines.length > 0 ? `${reply.lines.join("\n")}\n` : "";
+                const text = LISTINGS.has(command[0]) ? own(output) : output;
+                // Past the bound, in this reply or in the chain's so far: the call fails as a spawned client's does, and the
+                // rest of the chain is not sent.
+                bytes += Buffer.byteLength(text);
+                if (reply.overflow || bytes > maxBuffer)
+                    throw outputTooLarge(stdout);
+                if (!reply.ok)
+                    throw commandFailed(argvIn, stdout, text);
+                stdout += text;
+            }
+            return stdout;
+        }
+        finally {
+            target.users--;
+            if (target.retiring && target.users === 0)
+                void end(target);
+        }
+    };
+    /** Ends every client, one attaching included, each after what it was sent: the daemon is stopping. tmux destroys
+     *  their sessions as they leave. */
+    const close = async () => {
+        closed = true;
+        cancelAttach?.();
+        await starting;
+        await Promise.all([...live].map(end));
+    };
+    return Object.assign(exec, { close, owner });
+}
+//# sourceMappingURL=tmux-control.js.map