// Finding tmux, and spelling a tmux command the one way the deck runs it. // // The terminal panel owns no pty. tmux does: the deck restarts itself on every // self-update, and a terminal that died with the deck would be no terminal at // all. So every byte the panel shows comes from a tmux server, and this module // is the only place that knows which binary that is, which server a command // goes to, and what environment the server is started with. // // THE DECK'S OWN SERVER, NEVER THE USER'S. `-L ccdeck` is a separate tmux // server behind its own socket. Sessions the deck launches live there, so the // user's `tmux ls` never lists them, the user's `kill-server` never takes them, // and nothing the deck does to its sessions can resize, rename or kill one the // user made. The one time the deck reaches into the user's own server — a // session that was already running in their tmux — it names that server by its // socket path, which is the other shape a socket has here. // // tmux 3.2 IS THE FLOOR. `refresh-client -f` (ignore-size, pause-after, // read-only) arrived in 3.2, and without it the control-mode client can neither // do flow control nor watch a pane in the user's tmux without shrinking their // window to the panel's size. Ubuntu 22.04 ships 3.2a. // // REQUIRED, NOT SHIPPED. tmux publishes source only, so there is no release the // deck could verify against a checksum the way it does claude-swap or uv, and // building C on somebody's machine is not something a tool that "installs // nothing" gets to do. A machine without tmux is told the one line that // installs it for that platform — a fact about the machine, not an error. // // CCDECK'S OWN BUILD OVER A TMUX OLDER THAN 3.6. The user's tmux is the one // they chose, and wins whenever it is 3.6 or newer. One that is 3.2–3.5 works // but mis-draws a row with a wide glyph in it, which a reconnecting pane then // copies (tmux-download.mjs PREFERRED_TMUX_VERSION), so once ccdeck's own // build is in place the deck runs that instead — but never while the deck's // own server still runs sessions under the older tmux: they keep it until // they end (ownOverOlder). CCDECK_TMUX is never second-guessed. import { execFile } from "node:child_process"; import { existsSync, readFileSync } from "node:fs"; import { pathLookup } from "./exec-spec.mjs"; // Every tmux client the deck starts is tracked like any other child, so a // deck shut down mid-command reaps it. The tmux SERVER is not a child of // anything here — it daemonises — which is the whole point of using it. import { watchChild } from "./exec-children.mjs"; import { deckDataDir } from "./deck-home.mjs"; import { PREFERRED_TMUX_VERSION, managedTmuxPath } from "./tmux-download.mjs"; /** The deck's own tmux server. Every deck-launched session lives here. */ export const DECK_SOCKET = Object.freeze({ name: "ccdeck" }); /** The oldest tmux the terminal works with, as [major, minor]. */ export const MIN_TMUX_VERSION = Object.freeze([3, 2]); /** Point the deck at one particular tmux. A development and test knob, not a * setting: it is how the suite reaches a tmux that is not on PATH, and it is * deliberately absent from the README. Read through this constant the way * CCDECK_HOME is in deck-home.mjs. */ const TMUX_ENV = "CCDECK_TMUX"; /** Where tmux lives when PATH does not say. Homebrew on Apple silicon, then * Homebrew on Intel and most hand-built installs, then the distribution's. * A deck started from a login item or a desktop shortcut often has a PATH * that never sourced a shell rc, which is exactly when these matter. */ const KNOWN_PLACES = ["/opt/homebrew/bin/tmux", "/usr/local/bin/tmux", "/usr/bin/tmux"]; /** How long "no usable tmux" is believed. An answer that tmux is present is * kept until resetTmuxCache; an answer that it is missing is not, because the * panel's own advice is to go and install it — and the click after that * install has to see it without a deck restart. A tmux older than 3.6 kept * beside ccdeck's own build (ownOverOlder) is believed as long and no * longer, so the deck moves to the build soon after the last session that * held it back has ended. */ const MISS_TTL_MS = 10_000; /** The line shown when no install command is known for this machine. */ const NEUTRAL_INSTALL = "Install tmux 3.2 or newer with your system's package manager."; /** Linux install lines, matched against os-release ID and then ID_LIKE, so a * derivative (Mint, Rocky, Manjaro) gets its parent's command. */ const LINUX_INSTALL = [ ["sudo apt install tmux", ["debian", "ubuntu", "linuxmint", "pop", "raspbian", "elementary"]], ["sudo dnf install tmux", ["fedora", "rhel", "centos", "rocky", "almalinux", "amzn"]], ["sudo pacman -S tmux", ["arch", "manjaro", "endeavouros"]], ["sudo zypper install tmux", ["opensuse", "suse", "sles", "opensuse-leap", "opensuse-tumbleweed"]], ["sudo apk add tmux", ["alpine"]], ]; /** * Variables a deck-launched agent must not inherit because they describe the * process that started the DECK, not the session being started. * * Measured, not guessed. Claude Code 2.1.294 stamps every child it runs with * CLAUDECODE, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_CHILD_SESSION, * CLAUDE_CODE_SESSION_ATTENDED and CLAUDE_PID (and lists the rest of these * among the variables it strips from its own shell snapshots). A deck started * from inside a Claude session — `npx ccdeck` typed into its Bash tool, which * is how an agent runs the deck — carries all of them, and the tmux server * would hand them to every agent it launched: a Claude that takes itself for a * child of a conversation it has nothing to do with (2.1.294 consults * CLAUDE_CODE_CHILD_SESSION when deciding whether to keep prompt history, for * one) and is handed that conversation's id, pid and messaging socket. The two * Codex names are its sandbox markers, which a Codex started under them reads * as being inside a sandbox. * * BY NAME, NOT BY PREFIX. CLAUDE_CODE_USE_BEDROCK, CLAUDE_CONFIG_DIR and * CODEX_HOME are the user's own settings, and the launched agent needs every * one of them. */ const INHERITED_AGENT_MARKERS = [ "CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_CHILD_SESSION", "CLAUDE_CODE_SESSION_ATTENDED", "CLAUDE_PID", "CLAUDE_CODE_EXECPATH", "CLAUDE_EFFORT", "CLAUDE_CODE_INVOKED_SKILLS", "CLAUDE_CODE_MESSAGING_SOCKET", "CLAUDE_CODE_AGENT", "CLAUDE_JOB_DIR", "CLAUDE_AGENTS_AUTO_RELAUNCHED_AT", "AI_AGENT", "TRACEPARENT", "CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", ]; const DROPPED_NAMES = new Set(["TMUX", "TMUX_PANE", ...INHERITED_AGENT_MARKERS]); const DROPPED_PREFIXES = ["AGENTS_DECK_", "AGENT_DAG_", "CCDECK_"]; /** * The environment a tmux client — and so, the first time, the deck's tmux * server — is started with: the deck's own, minus what belongs to the deck. * * The server keeps the environment of the client that started it for its whole * life and hands it to every pane, so whatever is here is what a launched agent * sees. Three kinds of thing come out: * * - The deck's own variables, AGENTS_DECK_*, AGENT_DAG_* and CCDECK_*. They * configure this deck, not the agent, and one of them is actively harmful: * the hook goes silent under AGENTS_DECK_INTERNAL=1 (that is how the quota * probe keeps its own runs off the board), so a leak would launch a session * the board could never show. * - TMUX and TMUX_PANE, so a deck started from inside the user's tmux does * not start its server as a nested client of theirs. * - The agent-session markers above. * * Everything else stays, PATH first among it: the agent has to find node, git * and whatever else the user's shell would have given it. */ export function tmuxEnv(env = process.env) { const out = {}; for (const [key, value] of Object.entries(env ?? {})) { if (value === undefined) continue; if (DROPPED_NAMES.has(key) || DROPPED_PREFIXES.some(p => key.startsWith(p))) continue; out[key] = value; } return out; } /** * `tmux -V` read as [major, minor], or null when it does not say. * * "tmux 3.6a" and "tmux 3.2a" carry a letter for patch releases; "tmux * next-3.6" is a build from the development branch on its way to the number * it names: newer than every release before it, and read as that number. * "tmux openbsd-7.4" is OpenBSD's base-system tmux, which * follows upstream closely but numbers itself after the OS — reading 7.4 out of * it as a tmux version would be a guess that happens to pass, so it reads as * unknown instead and findTmux lets it through with a warning. */ export function parseTmuxVersion(raw) { const m = /^tmux\s+(?:next-)?(\d+)\.(\d+)/.exec(String(raw ?? "").trim()); return m ? [Number(m[1]), Number(m[2])] : null; } const atLeast = (v, min) => v[0] > min[0] || (v[0] === min[0] && v[1] >= min[1]); /** * The one line that installs tmux on this platform, or undefined where the * terminal is not offered at all (Windows has no tmux). * * `osRelease` is the text of /etc/os-release, passed in so every branch can be * checked from any machine. */ export function tmuxInstallLine(platform = process.platform, osRelease = "") { if (platform === "win32") return undefined; if (platform === "darwin") return "brew install tmux"; if (platform === "freebsd") return "sudo pkg install tmux"; if (platform === "linux") { const fields = Object.fromEntries(String(osRelease ?? "").split("\n").map(line => { const i = line.indexOf("="); return i < 0 ? ["", ""] : [line.slice(0, i).trim(), line.slice(i + 1).trim().replace(/^["']|["']$/g, "")]; })); const ids = [fields.ID, ...String(fields.ID_LIKE ?? "").split(/\s+/)] .filter(Boolean).map(id => id.toLowerCase()); for (const id of ids) { const hit = LINUX_INSTALL.find(([, family]) => family.includes(id)); if (hit) return hit[0]; } } return NEUTRAL_INSTALL; } /** * Every tmux on this machine worth asking, in the order to ask them, as * absolute paths that exist. * * CCDECK_TMUX, when set, is the ONLY candidate. Whoever set it meant that tmux; * quietly falling through to another one when it is wrong would hand them a * passing run against a binary they did not choose — the opposite of why the * variable exists. Otherwise: `tmux` on PATH, then the known install places. */ export function tmuxCandidates({ env = process.env, platform = process.platform, exists = existsSync, managed = managedTmuxPath(deckDataDir(platform, env)), } = {}) { const pathEnv = env.PATH ?? env.Path ?? ""; const located = (bin) => { if (!/[\\/]/.test(bin)) return pathLookup(bin, platform, { pathEnv, exists }); try { return exists(bin) ? bin : null; } catch { return null; } }; const forced = env[TMUX_ENV]?.trim(); if (forced) { const at = located(forced); return at ? [at] : []; } const out = []; // ccdeck's own build last (tmux-download.mjs): a tmux the user installed // is the one they chose, and theirs wins whenever it is new enough. for (const bin of ["tmux", ...KNOWN_PLACES, ...(managed ? [managed] : [])]) { const at = located(bin); if (at && !out.includes(at)) out.push(at); } return out; } let cached = null; /** Forget the remembered answer. For tests, and for nothing else. */ export function resetTmuxCache() { cached = null; } /** * Which tmux the terminal runs, and whether it is good enough. * * Answers `{ ok: true, path, version: [major, minor], raw }`, plus * `warning: "unknown-version"` (and `version: null`) for a tmux whose `-V` does * not carry a version this can read. Otherwise `{ ok: false, reason }` with * reason `missing`, `too-old` (with the path, version and raw text of the * first one found) or `unsupported-platform`, and — except on Windows — an * `install` line for this machine. * * Every candidate is asked before the answer is `too-old`. A Mac with an old * tmux first on PATH and a current Homebrew one behind it has a tmux that * works, and saying otherwise would send its owner off to install something * they already have. * * The first usable tmux is the answer, unless it is 3.2–3.5 and ccdeck's own * build may take its place (ownOverOlder), which asks the deck's server on * `socket` (DECK_SOCKET unless a caller names another) what it runs. * * A candidate that exists but will not run `-V` is skipped as if absent. Never * rejects. * * Remembered: a usable answer until resetTmuxCache, a missing one — or an * older tmux kept beside the own build — for ten seconds (see MISS_TTL_MS), * and concurrent callers share one probe. The memory is keyed on the inputs * that decide the answer — platform, CCDECK_TMUX, PATH, where the own build * lives and the socket — and on the very `run`, `exists` and `readFile` it was * found with, so a case in the suite that injects fakes is never answered from * another case's. * * `run(file, args, { env })` resolves `{ code, stdout, stderr }`; the real one * is execFile with a three-second deadline. */ export function findTmux({ env = process.env, platform = process.platform, socket = DECK_SOCKET, run = runVersion, exists = existsSync, readFile = readText, now = Date.now, } = {}) { const key = [ platform, env[TMUX_ENV] ?? "", env.PATH ?? env.Path ?? "", managedTmuxPath(deckDataDir(platform, env)), socket?.name ?? "", socket?.path ?? "", ].join("\0"); const same = cached && cached.key === key && cached.run === run && cached.exists === exists && cached.readFile === readFile; if (same && (cached.lasting || now() - cached.at < MISS_TTL_MS)) return cached.promise; const probe = probeTmux({ env, platform, run, exists, readFile, socket }); const promise = probe.then(p => p.found); const entry = { key, run, exists, readFile, at: now(), lasting: false, promise }; cached = entry; probe.then(p => { entry.lasting = p.found.ok && p.lasting; }); return promise; } const runVersion = (file, args, { env } = {}) => execTmux(file, args, { timeoutMs: 3000, env: tmuxEnv(env) }); const readText = (p) => readFileSync(p, "utf8"); /** findTmux's answer as `{ found, lasting }`: `lasting` false for an older * tmux kept beside ccdeck's own build, which is asked again soon. */ async function probeTmux({ env, platform, run, exists, readFile, socket }) { if (platform === "win32") return { found: Object.freeze({ ok: false, reason: "unsupported-platform" }), lasting: true }; const managed = managedTmuxPath(deckDataDir(platform, env)); const candidates = tmuxCandidates({ env, platform, exists, managed }); let tooOld = null; for (const path of candidates) { const said = await askVersion(run, path, env); if (!said) continue; const { raw, version } = said; if (!version) return { found: Object.freeze({ ok: true, path, version: null, raw, warning: "unknown-version" }), lasting: true }; if (atLeast(version, MIN_TMUX_VERSION)) { const found = Object.freeze({ ok: true, path, version: Object.freeze(version), raw }); if (atLeast(version, PREFERRED_TMUX_VERSION)) return { found, lasting: true }; return ownOverOlder(found, { candidates, managed, env, run, socket }); } tooOld ??= { ok: false, reason: "too-old", path, version: Object.freeze(version), raw }; } const install = tmuxInstallLine(platform, platform === "linux" ? osReleaseText(readFile) : ""); return { found: Object.freeze(tooOld ? { ...tooOld, install } : { ok: false, reason: "missing", install }), lasting: true }; } /** What `path -V` says, as `{ raw, version }` (version null when unreadable), * or null for a tmux that would not run it. */ async function askVersion(run, path, env) { let r; try { r = await run(path, ["-V"], { env }); } catch { return null; } if (!r || r.code !== 0) return null; const raw = String(r.stdout ?? "").trim(); return { raw, version: parseTmuxVersion(raw) }; } /** * `older`, the first usable tmux and one 3.2–3.5, or ccdeck's own build in its * place — as `{ found, lasting }`. * * The build takes it over only when all of this holds: * - it is one of the candidates: fetched, and CCDECK_TMUX not set (that * names the only candidate, and is never second-guessed); * - it says it is PREFERRED_TMUX_VERSION or newer; * - the deck's server runs no session under an older tmux. Asked of the * build itself, `list-sessions -F '#{version}'` on `socket`, because only * that direction works: measured with Ubuntu 24.04's tmux 3.4 and * ccdeck's 3.8, a 3.8 client lists, reads and starts sessions on a 3.4 * server, while a 3.4 client gets "server exited unexpectedly" from a 3.8 * one. `#{version}` is the server's own, in every tmux since 2.4. * * Otherwise the older tmux stays, and nothing is moved, restarted or killed: * sessions started under it keep the server they are in. Without the build * that is the whole answer, kept until resetTmuxCache — the status route * fetches the build behind it (ownTmuxWanted), and forgets this answer once it * lands. Beside the build it is believed for MISS_TTL_MS only: the server * empties when its last session ends, and the next ask after that moves to * the build. An answer the build or the server would not give (a timeout, a * failure it does not explain) keeps the older tmux too, and is asked again * as soon. */ async function ownOverOlder(older, { candidates, managed, env, run, socket }) { if (!managed || older.path === managed || !candidates.includes(managed)) return { found: older, lasting: true }; const own = await askVersion(run, managed, env); if (!own?.version || !atLeast(own.version, PREFERRED_TMUX_VERSION)) return { found: older, lasting: false }; let listing = null; try { listing = await run(managed, tmuxCommand(managed, socket, ["list-sessions", "-F", "#{version}"]).slice(1), { env }); } catch { /* unanswered: the older tmux stays */ } if (deckServerHoldsOlder(listing)) return { found: older, lasting: false }; return { found: Object.freeze({ ok: true, path: managed, version: Object.freeze(own.version), raw: own.raw }), lasting: true }; } /** A failed listing that only says there is no server to answer it: a * socket nobody answers on, none at all, or a server with no session. Not * "server exited unexpectedly", which a tmux client also says of a server it * cannot speak to. */ const NO_DECK_SERVER = /no server running|error connecting to|^no sessions/im; /** * Whether the deck's server, as ccdeck's own build answered `list-sessions -F * '#{version}'` on it (`{ code, stdout, stderr }`, or null for no answer), may * run a session under a tmux older than PREFERRED_TMUX_VERSION. * * No only when that is known: an answer each of whose lines is a version that * new or newer (an empty one is a server with no session), or a failure that * says there is no server at all. Everything else — an older version, one it * cannot read, a timeout, an error it does not explain — is yes, which keeps * the older tmux. Pure. */ export function deckServerHoldsOlder(listing) { if (!listing || typeof listing !== "object") return true; if (listing.code !== 0) return !NO_DECK_SERVER.test(String(listing.stderr ?? "")); return String(listing.stdout ?? "").split("\n").map(l => l.trim()).filter(Boolean).some((l) => { const v = parseTmuxVersion(`tmux ${l}`); return !v || !atLeast(v, PREFERRED_TMUX_VERSION); }); } /** * Whether ccdeck's own build is worth fetching although `found` (findTmux's * answer) works: a tmux 3.2–3.5 the deck chose by itself — CCDECK_TMUX unset * — on Linux or macOS, while the build is not at `managed`. Once it is there, * findTmux runs it instead (ownOverOlder). The status route starts the same * download a machine with no tmux gets, behind its answer. `env`, `platform`, * `exists` and `managed` as for tmuxCandidates. Never throws. */ export function ownTmuxWanted(found, { env = process.env, platform = process.platform, exists = existsSync, managed = managedTmuxPath(deckDataDir(platform, env)), } = {}) { if (platform === "win32" || found?.ok !== true || !Array.isArray(found.version)) return false; if (!atLeast(found.version, MIN_TMUX_VERSION) || atLeast(found.version, PREFERRED_TMUX_VERSION)) return false; if (String(env?.[TMUX_ENV] ?? "").trim() || !managed) return false; try { return !exists(managed); } catch { return false; } } /** /etc/os-release, or the copy systemd keeps when /etc has none. */ function osReleaseText(readFile) { for (const p of ["/etc/os-release", "/usr/lib/os-release"]) { try { return String(readFile(p) ?? ""); } catch { /* try the next */ } } return ""; } /** * The argv for one tmux invocation against one server: the binary, `-u`, the * socket, then `args` exactly as given. * * `tmux` is a path or findTmux's answer. `socket` is `{ name }` for a server in * tmux's own socket directory (`-L`), `{ path }` for one named by its socket * file (`-S`), or null for the user's default server. * * WHY `-u` ON EVERY CALL. A tmux client decides whether it may print UTF-8 from * LC_ALL, LC_CTYPE and LANG, and a deck started by a login item or a service * manager often has none of them. Such a client prints every non-ASCII * character as `_`: measured on 3.6, a session started in `~/проект 日本` * listed its directory as `~/______ ____`. `-u` says the reader handles UTF-8, * which this one always does. It changes nothing on the server. */ export function tmuxCommand(tmux, socket, args = []) { const bin = typeof tmux === "string" ? tmux : tmux?.path; if (typeof bin !== "string" || bin === "") throw new TypeError("tmuxCommand needs the tmux binary"); return [bin, "-u", ...socketFlags(socket), ...args.map(String)]; } function socketFlags(socket) { if (socket == null) return []; if (typeof socket.name === "string" && socket.name !== "") { // -L names a file inside tmux's socket directory; a separator would point // it somewhere else entirely. if (/[\\/]/.test(socket.name)) throw new TypeError("a tmux socket name cannot contain a path separator"); return ["-L", socket.name]; } if (typeof socket.path === "string" && socket.path !== "") return ["-S", socket.path]; throw new TypeError("a tmux socket is { name } or { path }"); } /** * One literal argument, safe from tmux's own command parser. * * tmux splits its argv into commands on any argument that ENDS in `;`, not * only on a lone `;` — so a project folder named `notes;` passed as `-c * notes;` ends the command there, and what follows is parsed as a new command. * Measured on 3.6: the whole invocation then fails to parse, and the client * reports "error connecting" as though no server existed. A trailing `\;` is * tmux's escape for a literal one. */ export function tmuxArg(value) { const s = String(value); return s.endsWith(";") ? `${s.slice(0, -1)}\\;` : s; } /** * Several tmux commands as one invocation's arguments: every argument escaped * with tmuxArg, the commands joined by lone `;` tokens. * * One invocation rather than several because tmux runs a sequence back to back * in one turn of its event loop. A pane whose program exits at once — a binary * that is not there — is reaped only on a later turn, so options set in the * same sequence as new-session are always in place before tmux decides what to * do with the corpse. Set from a second invocation, remain-on-exit can arrive * after the session it was meant for has already been destroyed. */ export function tmuxSequence(commands) { const out = []; commands.forEach((cmd, i) => { if (i > 0) out.push(";"); for (const arg of cmd) out.push(tmuxArg(arg)); }); return out; } /** * A literal value for an argument tmux expands as a format, such as * new-session's `-c`. * * `-c` is expanded before it is used, so a folder named `x#{pane_id}` is * opened as `x%0` — and `#(...)` in a format RUNS a shell command. Measured on * 3.6: a directory with `#{pane_id}` in its name made tmux fall back to $HOME. * `##` is a literal `#`. */ export function tmuxFormatLiteral(value) { return String(value).replaceAll("#", "##"); } /** * The command a pane runs, in the form tmux executes directly. * * tmux runs a command given as two or more arguments with execvp, and one given * as a SINGLE argument through `default-shell -c` — the user's login shell, * which re-splits it on spaces and reads its metacharacters, and may be fish. * So a lone `/Volumes/My Disk/bin/codex` would not start, and the same argv * would mean different things on different machines. A single argument is * handed to /bin/sh as `$0` instead and exec'd from there: no word splitting, * no expansion, and the agent replaces sh, so the pane's pid is the agent's. */ export function paneArgv(argv) { return argv.length === 1 ? ["/bin/sh", "-c", 'exec "$0"', argv[0]] : [...argv]; } /** * Whether a failed tmux call failed only because there is no server (or no * session) to answer it, which for every caller here means "nothing is * running" rather than "something is wrong". */ export function tmuxHasNoServer(stderr) { return /no server running|error connecting to|server exited unexpectedly|^no sessions/im.test(String(stderr ?? "")); } /** * Whether a tmux client run through execFile with a `timeout` outran it. The * kill alone says so: tmux's client catches the SIGTERM and exits 0 with * nothing printed, so a stalled server (stopped, swapped out) would otherwise * read as a clean, empty answer: no sessions, no panes. Measured on tmux 3.8. */ export function tmuxTimedOut(child, err) { return Boolean(err?.killed || child?.killed); } /** * Run one tmux invocation and collect its output: `{ ok, code, stdout, stderr }`. * * execFile with an argument vector, never a shell — a project path is an * argument, not a command line. `code` is the exit status, or a string when * there was none: "ETIMEDOUT" for a client that outran `timeoutMs`, a spawn * error's own code such as "ENOENT". Never rejects; every caller treats a * failed tmux as a state to report. * * `env` is the deck's environment and is passed through tmuxEnv here, on every * call, rather than at the one call that happens to start the server: which * call that is depends on what ran before it, and a server started dirty stays * dirty for its whole life. */ export function runTmux(tmux, socket, args, { timeoutMs = 3000, env = process.env, scope = null } = {}) { const [file, ...argv] = tmuxCommand(tmux, socket, args); // `scope` is serverScope's answer: the same tmux, started by systemd-run in // a scope of its own. if (Array.isArray(scope) && scope.length) return execTmux(scope[0], [...scope.slice(1), file, ...argv], { timeoutMs, env: tmuxEnv(env) }); return execTmux(file, argv, { timeoutMs, env: tmuxEnv(env) }); } // ── a server that outlives the deck's service ────────────────────────────── // // On Linux the login item is a systemd user service (login-service.mjs), and // systemd stops a service by killing everything in its cgroup — KillMode's // default, control-group. A tmux server forked by the deck worker daemonizes, // but daemonizing does not leave a cgroup: it stays in the service's, so // `ccdeck --stop`, `systemctl --user stop` or the crash ceiling would kill the // server and every agent running in it, mid-turn. (A restart or an upgrade is // safe: the supervisor stays up through those.) macOS is not affected — tmux's // setsid() is enough to escape launchd's process-group kill. // // So the call that may START the deck's server runs through // `systemd-run --user --scope`, which puts the client — and the server it // forks — in a transient scope of their own, outside the service. Only when // the deck is in a service at all: a deck started from a terminal is in that // terminal's scope, which nothing stops on the deck's behalf. /** The cgroup systemd tracks this process in, from a /proc/self/cgroup text: * its own named hierarchy where there is one (a v1 or hybrid host, whose * unified line may say only "/"), else the unified line. Pure. */ export function cgroupPath(text) { const lines = String(text ?? "").split("\n"); const named = lines.find(l => /^\d+:name=systemd:/.test(l)); if (named) return named.replace(/^\d+:name=systemd:/, "").trim(); const unified = lines.find(l => l.startsWith("0::")); return unified ? unified.slice(3).trim() : ""; } /** systemd-run's arguments before the command it starts in a new scope. * `--expand-environment=no` keeps that command as the deck wrote it: the * systemd-run on Ubuntu 26.04 (systemd 259) expands `$NAME` and `${NAME}` in * a scope's command line, as ExecStart= does, from systemd-run's own * environment — a name it does not have, or one that is not a valid name, * becomes an empty string — so a `$` in an agent's arguments or in a * folder's name reached tmux rewritten. Ubuntu 24.04's (255) left a scope's * command alone. */ export const SCOPE_ARGS = Object.freeze(["--user", "--scope", "--collect", "--quiet", "--expand-environment=no", "--description=ccdeck terminal sessions", "--"]); /** The same without `--expand-environment=no`, for a systemd-run older than * 254, which refuses the option and does not expand a scope's command. */ export const LEGACY_SCOPE_ARGS = Object.freeze(SCOPE_ARGS.filter(a => a !== "--expand-environment=no")); const scopeProbes = new Map(); /** Whether systemd-run starts a scope here with `args` — a service under the * SYSTEM manager has no user bus to ask, a minimal container has no systemd * behind its systemd-run, and one older than 254 refuses SCOPE_ARGS. Asked * with `true`. */ function probeScope(bin, env, args) { return new Promise((resolve) => { try { execFile(bin, [...args, "true"], { env: tmuxEnv(env), timeout: 5000, windowsHide: true }, (err) => resolve(!err)); } catch { resolve(false); } }); } /** The first of SCOPE_ARGS and LEGACY_SCOPE_ARGS this systemd-run starts a * scope with, or null when it starts none. */ async function scopeArgsFor(bin, env, probe) { for (const args of [SCOPE_ARGS, LEGACY_SCOPE_ARGS]) { let ok = false; try { ok = await probe(bin, env, args); } catch { ok = false; } if (ok) return args; } return null; } /** * The prefix that starts a tmux server outside the deck's systemd service — * `[systemd-run, ...SCOPE_ARGS]`, or LEGACY_SCOPE_ARGS for an older * systemd-run — or null where none is needed or none works: not Linux, not * in a `.service` cgroup, no systemd-run, or one that cannot start a scope. * Asked once per binary. Never rejects; null means "run tmux as it is". */ export async function serverScope({ platform = process.platform, env = process.env, readCgroup = () => readFileSync("/proc/self/cgroup", "utf8"), exists = existsSync, probe = probeScope, } = {}) { if (platform !== "linux") return null; let path = ""; try { path = cgroupPath(readCgroup()); } catch { return null; } if (!/\.service$/.test(path)) return null; const bin = pathLookup("systemd-run", platform, { pathEnv: env.PATH ?? "", exists }) ?? ["/usr/bin/systemd-run", "/bin/systemd-run"].find(p => exists(p)) ?? null; if (!bin) return null; if (!scopeProbes.has(bin)) scopeProbes.set(bin, scopeArgsFor(bin, env, probe)); const args = await scopeProbes.get(bin); return args ? [bin, ...args] : null; } /** For tests: forget what systemd-run answered. */ export function resetServerScope() { scopeProbes.clear(); } function execTmux(file, argv, { timeoutMs, env }) { return new Promise((resolve) => { const settle = (code, stdout, stderr) => resolve({ ok: code === 0, code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }); let child; try { child = execFile(file, argv, { env, timeout: timeoutMs, maxBuffer: 4 << 20, windowsHide: true }, (err, stdout, stderr) => { if (!err && tmuxTimedOut(child)) return settle("ETIMEDOUT", stdout, stderr || "tmux did not answer in time"); if (!err) return settle(0, stdout, stderr); const code = typeof err.code === "number" || typeof err.code === "string" ? err.code : err.killed ? "ETIMEDOUT" : err.signal ?? "EFAIL"; settle(code, stdout, stderr || err.message); }); } catch (err) { settle(err?.code ?? "EFAIL", "", String(err?.message ?? err)); return; } watchChild(child); }); }