Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Everything that happens before a pane exists (architecture §2.3): the socket root,
* pane ids, the child's environment, the launcher and shell shim, the caller-flag check,
* and the two spawns — the pane watcher, then magmux.
*
* The pane child must run in EXACTLY the MCP server's environment and cwd (D16), which
* a pipe spawn gave for free and a pane does not: magmux starts the pane through
* `$SHELL -l -c`, a login shell that would run the user's profile. So the environment
* travels as a JSON snapshot in `CLAUDISH_PANE_ENV` (inherited, never on disk) that the
* child re-applies (`child-env.ts`), and `$SHELL` is a generated shim that drops `-l`, so
* no profile runs at all (X-M15).
*
* magmux runs a pane DECLARED: `--controller claude-code --session-id <uuid> --transcript
* <path>` before `-e` names the session and the transcript claudish already gives Claude
* Code and its own transcript follower, so magmux's input gate reads exactly that file
* and never its mtime-based discovery, which can lock onto the parent's or a sibling's
* transcript (research-magmux §3; architecture-v2 R1.0). `PaneSession` verifies the
* binding from `list` on every attach (`gate-binding.ts`). The pane command itself still
* never names `claude`: a direct `claude` launch would be gated with basis `direct`, by
* discovery, and have its `--settings` rewritten.
*/
import { type ChildProcess, execFile, spawn } from "node:child_process";
import { randomBytes } from "node:crypto";
import { chmodSync, lstatSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { join, resolve } from "node:path";
import {
CLAUDISH_EXITING_FLAGS,
CLAUDISH_FLAG_ARITY,
type PassthroughClassification,
classifyPassthroughTokens,
} from "../cli.js";
import { ENV } from "../config.js";
import { findMagmuxBinaryOrNull } from "../launcher/magmux-binary.js";
import { STRIPPED_CHILD_VARS } from "../launcher/magmux-wrapper.js";
import { resolveClaudishSpawn } from "../spawn-claudish.js";
import { isPaneShellManagedKey } from "./child-env.js";
import { DEFAULT_PANE_COLS, DEFAULT_PANE_ROWS } from "./pane-size.js";
import { type WatcherArgs, isValidPaneId, watcherArgv } from "./process-identity.js";
/* ───────────────────────────── socket root ───────────────────────────── */
function uid(): number {
return typeof process.getuid === "function" ? process.getuid() : 0;
}
/**
* The socket root for `env`: `CLAUDISH_PANE_ROOT` when set (a location, like
* `CLAUDISH_SESSIONS_DIR`; every check below still applies), else `/tmp/claudish-mux-<uid>`.
*/
export function sockRootFor(env: Record<string, string | undefined> = process.env): string {
const override = env[ENV.CLAUDISH_PANE_ROOT]?.trim();
// resolved once: every path check compares against this exact spelling, and the
// watcher's shell globs ("$ROOT"/launch-??????) never match `/x/` or `./x`
return override ? resolve(override) : `/tmp/claudish-mux-${uid()}`;
}
/** The default socket root of this process. */
export const SOCK_ROOT: string = sockRootFor();
export class PaneRootError extends Error {
readonly code = "pane_root";
}
function assertPrivateDir(p: string): void {
const st = lstatSync(p);
if (st.isSymbolicLink() || !st.isDirectory())
throw new PaneRootError(`pane socket root ${p} is not a real directory`);
if (st.uid !== uid())
throw new PaneRootError(`pane socket root ${p} is not owned by uid ${uid()}`);
if ((st.mode & 0o077) !== 0)
throw new PaneRootError(
`pane socket root ${p} has mode ${(st.mode & 0o777).toString(8)}; it must be 0700`
);
}
/** Create (0700) and verify the socket root and its `panes/` record dir. Returns `root`. */
export function ensureSockRoot(given: string = sockRootFor()): string {
const root = resolve(given);
try {
mkdirSync(root, { mode: 0o700 });
} catch (e) {
if ((e as NodeJS.ErrnoException).code === "ENOENT")
mkdirSync(root, { recursive: true, mode: 0o700 });
else if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
}
assertPrivateDir(root);
const panes = join(root, "panes");
try {
mkdirSync(panes, { mode: 0o700 });
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
}
assertPrivateDir(panes);
return root;
}
/* ───────────────────────────── ids ───────────────────────────── */
/** This process's start time in ms, base 36: with the pid it makes a reused owner pid detectable. */
export const OWNER_START36 = Math.round(Date.now() - process.uptime() * 1000).toString(36);
export { isValidPaneId };
/** `c<pid>-<ownerStart36>-<kind><label>-<6 hex>`, at most 40 characters. */
export function mintPaneId(kind: "t" | "s", label: string): string {
const head = `c${process.pid}-${OWNER_START36}-${kind}`;
const tail = `-${randomBytes(3).toString("hex")}`;
const room = Math.max(0, 40 - head.length - tail.length);
const clean = label.replace(/[^A-Za-z0-9_]/g, "").slice(0, room);
const id = `${head}${clean}${tail}`;
if (!isValidPaneId(id)) throw new Error(`minted an invalid pane id: ${id}`);
return id;
}
/* ───────────────────────────── environment ───────────────────────────── */
/** Variables that steer a TUI's rendering and integrations (X-M16): never in a pane. */
export const TERMINAL_IDENTITY_VARS = [
"TMUX",
"TMUX_PANE",
"TERM_PROGRAM",
"TERM_PROGRAM_VERSION",
"TERM_SESSION_ID",
"COLORTERM",
"LC_TERMINAL",
"LC_TERMINAL_VERSION",
"WT_SESSION",
"CLAUDE_CODE_SSE_PORT",
"ENABLE_IDE_INTEGRATION",
] as const;
export const TERMINAL_IDENTITY_PREFIXES = [
"ITERM_",
"KITTY_",
"WEZTERM_",
"ALACRITTY_",
"GHOSTTY_",
"VSCODE_",
] as const;
/** The MCP server's HOST identity: describes the server's host, not the pane's fresh session. */
export const HOST_IDENTITY_VARS = [
"CLAUDISH_LAUNCHER_PID",
"CLAUDISH_LAUNCHER_PPID",
"CLAUDE_CODE_SESSION_ID",
] as const;
/** Linux's per-variable limit (MAX_ARG_STRLEN 131,072) with a margin. */
export const LINUX_ENV_STRING_LIMIT = 131_000;
/**
* Whether `key` is withheld from every claudish child this server starts: a pane child
* (`buildPaneEnv`) and `run_prompt`'s print child (`mcp/run-prompt-claude-code.ts`).
* One list for both spawners: `STRIPPED_CHILD_VARS` (a nested-session marker), every
* `MAGMUX_*` key, the terminal-identity set and the server's host identity.
*/
export function isStrippedFromChildEnv(key: string): boolean {
return (
(STRIPPED_CHILD_VARS as readonly string[]).includes(key) ||
key.startsWith("MAGMUX_") ||
(TERMINAL_IDENTITY_VARS as readonly string[]).includes(key) ||
TERMINAL_IDENTITY_PREFIXES.some((p) => key.startsWith(p)) ||
(HOST_IDENTITY_VARS as readonly string[]).includes(key)
);
}
export class PaneEnvTooLargeError extends Error {
readonly code = "pane_lost";
}
export interface PaneEnvInput {
parentEnv: Record<string, string | undefined>;
slotEnv: Record<string, string>;
/** realpath of the spawn cwd */
cwd: string;
/** the control directory holding `sh-shim` */
ctlDir: string;
/**
* This process's active `--config` / `CLAUDISH_CONFIG` file (`getConfigFileOverride()`),
* or null. Set as the child's `CLAUDISH_CONFIG`, so the child reads the config its
* parent reads, whatever `parentEnv` carries.
*/
configFile: string | null;
platform?: NodeJS.Platform;
/** the pane's size at launch (already clamped); DEFAULT_PANE_COLS × DEFAULT_PANE_ROWS when absent */
cols?: number;
rows?: number;
}
/**
* magmux's environment: the parent's minus the stripped, terminal-identity and host-
* identity keys, plus the geometry, the slot env, the parent's config file, the pane
* markers, the snapshot, and finally `SHELL=<ctlDir>/sh-shim` (after the snapshot,
* which keeps the real `SHELL`). The markers and the config travel only here, in the
* spawn environment: the child honours them because no env file can set them
* (launch-env.ts).
*/
export function buildPaneEnv(input: PaneEnvInput): { magmuxEnv: Record<string, string> } {
const env: Record<string, string> = {};
for (const [k, v] of Object.entries(input.parentEnv)) {
if (v === undefined || isStrippedFromChildEnv(k)) continue;
env[k] = v;
}
env.COLUMNS = String(input.cols ?? DEFAULT_PANE_COLS);
env.LINES = String(input.rows ?? DEFAULT_PANE_ROWS);
// Two independent defaults; a caller's own value of either is kept. Each is checked on
// its own, because a caller that turns traffic off itself still needs the cursor
// default. Traffic off leaves Claude Code's tengu_native_cursor flag at its default
// false, so Claude draws
// its own reverse-video cursor on the first rune of the faint "Try …" placeholder,
// which magmux's input gate reads as text in the box (box_not_empty) and boot never
// becomes ready. CLAUDE_CODE_NATIVE_CURSOR restores the terminal's native cursor;
// Claude Code reads it as set or unset, so any non-empty value (even "0") turns it on.
if (input.parentEnv.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC === undefined)
env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
if (input.parentEnv.CLAUDE_CODE_NATIVE_CURSOR === undefined) env.CLAUDE_CODE_NATIVE_CURSOR = "1";
Object.assign(env, input.slotEnv);
if (input.configFile !== null) env.CLAUDISH_CONFIG = input.configFile;
env[ENV.CLAUDISH_PANE_CHILD] = "1";
env[ENV.CLAUDISH_PANE_CWD] = input.cwd;
delete env[ENV.CLAUDISH_PANE_ENV];
const snapshot: Record<string, string> = {};
for (const [k, v] of Object.entries(env)) {
if (isPaneShellManagedKey(k) || k === ENV.CLAUDISH_PANE_ENV) continue;
snapshot[k] = v;
}
const json = JSON.stringify(snapshot);
const entryBytes = Buffer.byteLength(`${ENV.CLAUDISH_PANE_ENV}=${json}`);
if ((input.platform ?? process.platform) === "linux" && entryBytes > LINUX_ENV_STRING_LIMIT)
throw new PaneEnvTooLargeError(
`pane environment snapshot is ${entryBytes} bytes, over Linux's 131072-byte limit per variable`
);
env[ENV.CLAUDISH_PANE_ENV] = json;
env.SHELL = join(input.ctlDir, "sh-shim");
return { magmuxEnv: env };
}
/* ───────────────────────────── child argv and flags ───────────────────────────── */
export function buildClaudishPaneArgv(
spawnModel: string,
sessionUuid: string,
turnDir: string,
callerFlags: string[]
): string[] {
return [
"-i",
"--model",
spawnModel,
"-y",
"--quiet",
"--session-id",
sessionUuid,
"--add-dir",
turnDir,
...callerFlags,
];
}
/** Our own argv, plus `--no-auto-approve`, which defeats `-y` (phase-2 s09). */
const OWN_ARGV = [
"-i",
"--interactive",
"--model",
"-m",
"-y",
"--auto-approve",
"--no-auto-approve",
"--quiet",
"-q",
"--session-id",
];
const TRANSPORT_BREAKERS = [
"-p",
"--print",
"--stdin",
"--output-format",
"--input-format",
"--include-partial-messages",
"--replay-user-messages",
"--json",
"--bg",
"--background",
];
const IDENTITY_BREAKERS = [
"--resume",
"-r",
"--continue",
"-c",
"--from-pr",
"--teleport",
"--fork-session",
"-w",
"--worktree",
"--no-session-persistence",
];
/** Claude Code flags that only work with `--print` (X-M3). */
export const PRINT_ONLY_FLAGS = [
"--max-turns",
"--max-budget-usd",
"--fallback-model",
"--json-schema",
"--permission-prompt-tool",
];
/** claudish's own mode flags: each would start a different claudish mode in the pane (X-L2). */
const MODE_FLAGS = [
"--team",
"-f",
"--file",
"--grid",
"--probe",
"--models",
"--monitor",
"--advisor",
"--mcp",
"--kimi-login",
"--kimi-logout",
...CLAUDISH_EXITING_FLAGS,
];
/**
* Words index.ts treats as a SUBCOMMAND anywhere in argv (`args.includes("update")`,
* the first non-dash token, …): a caller flag VALUE equal to one of them would dispatch
* a subcommand instead of the REPL, which the child-side assertion cannot catch.
*/
export const SUBCOMMAND_WORDS = [
"update",
"init",
"profile",
"config",
"telemetry",
"stats",
"serve",
"providers",
"keychain",
"subscription",
"hooks",
"team",
"login",
"logout",
"quota",
"usage",
];
export type FlagCheck = { ok: true } | { ok: false; message: string };
function reservedMessage(flag: string): string | null {
if (PRINT_ONLY_FLAGS.includes(flag))
return `${flag} works only with --print; team slots and sessions are interactive panes, so it would be silently ignored`;
if (OWN_ARGV.includes(flag))
return `${flag} is set by claudish itself for a pane child (-i --model <m> -y --quiet --session-id <uuid>)`;
if (TRANSPORT_BREAKERS.includes(flag))
return `${flag} would break the interactive pane transport`;
if (IDENTITY_BREAKERS.includes(flag))
return `${flag} would move the session to another transcript or directory`;
if ((MODE_FLAGS as readonly string[]).includes(flag))
return `${flag} would start a different claudish mode inside the pane`;
return null;
}
/** Whether the flags visibly remove the Read tool (§2.3 rule 4). */
export function flagsRemoveRead(flags: string[]): boolean {
for (let i = 0; i < flags.length; i++) {
const [name, inline] = splitFlag(flags[i] as string);
const value = inline ?? flags[i + 1] ?? "";
if (name === "--disallowedTools" || name === "--disallowed-tools") {
if (/(^|[\s,])Read([\s,(]|$)/.test(value)) return true;
}
if (name === "--tools") {
if (!/(^|[\s,])Read([\s,(]|$)/.test(value)) return true;
}
}
return false;
}
function splitFlag(token: string): [string, string | undefined] {
if (!token.startsWith("-")) return [token, undefined];
const eq = token.indexOf("=");
return eq > 0 ? [token.slice(0, eq), token.slice(eq + 1)] : [token, undefined];
}
/**
* Claude Code flags that take a value: every option `claude --help` (2.1.291) prints with
* `<…>` or `[…]`, plus the `-file` variants it names in prose. Any other passthrough flag
* is a boolean to Claude Code, so a token after it is Claude Code's POSITIONAL PROMPT
* (`--verbose "do X"` boots the pane with a turn the server never typed), even though
* claudish's own walker reads it as the flag's value. Unknown flags are refused with a
* value rather than guessed at: a refusal is visible, a stray turn is not.
*/
export const CLAUDE_CODE_VALUE_FLAGS: readonly string[] = [
"--add-dir",
"--agent",
"--agents",
"--allowedTools",
"--allowed-tools",
"--append-system-prompt",
"--append-system-prompt-file",
"--autocompact",
"--betas",
"--cloud",
"-d",
"--debug",
"--debug-file",
"--disallowedTools",
"--disallowed-tools",
"--effort",
"--environment",
"--fallback-model",
"--file",
"--from-pr",
"--input-format",
"--json-schema",
"--max-budget-usd",
"--mcp-config",
"--model",
"-n",
"--name",
"--output-format",
"--permission-mode",
"--permission-prompt-tool",
"--permission-prompts",
"--plugin-dir",
"--plugin-url",
"--prompt-suggestions",
"--remote-control",
"--remote-control-session-name-prefix",
"-r",
"--resume",
"--session-id",
"--setting-sources",
"--settings",
"--system-prompt",
"--system-prompt-file",
"--system-prompt-snapshot",
"--teleport",
"--tools",
"-w",
"--worktree",
];
/** A value token after a passthrough flag Claude Code reads as a boolean. */
function booleanFlagValue(c: PassthroughClassification): { flag: string; value: string } | null {
for (const t of c.tokens) {
if (t.kind !== "passthrough-value") continue;
const flag = splitFlag(c.tokens.find((x) => x.index === t.index - 1)?.token ?? "")[0];
if (!CLAUDE_CODE_VALUE_FLAGS.includes(flag)) return { flag, value: t.token };
}
return null;
}
/**
* The server-side check of `claude_flags` (D18): reserved tokens, subcommand words, and
* any positional token or `--` (claudish would turn a positional into a `-p` prompt),
* including a value after a flag Claude Code reads as a boolean.
*/
export function checkChildFlags(flags: string[]): FlagCheck {
for (const token of flags) {
if (typeof token !== "string") return { ok: false, message: "claude_flags must be strings" };
const [name] = splitFlag(token);
const msg = token.startsWith("-") ? reservedMessage(name) : null;
if (msg) return { ok: false, message: msg };
if (SUBCOMMAND_WORDS.includes(token))
return {
ok: false,
message: `"${token}" is a claudish subcommand name and would start that subcommand inside the pane`,
};
}
// `--flag=value` is one token to parseArgs as well, so the original tokens are classified.
const c = classifyPassthroughTokens(flags);
if (c.separatorAt !== null)
return {
ok: false,
message:
"claude_flags may not contain `--`: claudish would treat what follows as a prompt; claudish takes one value per flag: write `--allowedTools Read,Bash`",
};
if (c.positionals.length > 0)
return {
ok: false,
message: `claude_flags contains a positional token (${JSON.stringify(c.positionals[0])}); claudish takes one value per flag: write \`--allowedTools Read,Bash\``,
};
const stray = booleanFlagValue(c);
if (stray)
return {
ok: false,
message: `claude_flags: ${stray.flag} takes no value in Claude Code, so ${JSON.stringify(stray.value)} would become the session's first prompt; pass the flag alone`,
};
return { ok: true };
}
/** Known claudish flags (exported for the drift test). */
export const KNOWN_CLAUDISH_FLAGS: readonly string[] = Object.keys(CLAUDISH_FLAG_ARITY);
/* ───────────────────────────── magmux binary ───────────────────────────── */
/**
* The first magmux that binds and dials its socket at any path depth (0.18.0). It also carries
* what 0.17.0 introduced: the Claude Code input gate with a declared transcript
* (`--session-id`, `--transcript`, and `list`'s `bound`/`sessionId`/`transcriptPath`). A
* pre-release such as `0.18.0-rc1` passes: `versionAtLeast` compares the numeric triple only.
*/
export const MIN_MAGMUX_VERSION = "0.18.0";
export class MagmuxUnavailableError extends Error {
readonly code = "magmux_unavailable";
}
export function versionAtLeast(v: string, min: string): boolean {
const a = v.split(/[.-]/).map((x) => Number.parseInt(x, 10));
const b = min.split(".").map((x) => Number.parseInt(x, 10));
for (let i = 0; i < 3; i++) {
const x = a[i] ?? 0;
const y = b[i] ?? 0;
if (!Number.isFinite(x)) return false;
if (x !== y) return x > y;
}
return true;
}
type MagmuxBinary = { binary: string; version: string };
/** Successes only: a failed probe is never cached, so the next caller probes again. */
const magmuxCache = new Map<string, MagmuxBinary>();
/** The probe in flight per key: six slots starting at once run `--version` once, not six times. */
const magmuxProbes = new Map<string, Promise<MagmuxBinary>>();
/** The magmux binary and its version (≥ `MIN_MAGMUX_VERSION`), cached per process. Never a `-p` fallback. */
export async function assertMagmuxAvailable(binary?: string): Promise<MagmuxBinary> {
const key = binary ?? "";
const cached = magmuxCache.get(key);
if (cached) return cached;
const inFlight = magmuxProbes.get(key);
if (inFlight) return inFlight;
const probe = (async () => {
try {
const result = await probeMagmux(binary);
magmuxCache.set(key, result);
return result;
} finally {
magmuxProbes.delete(key);
}
})();
magmuxProbes.set(key, probe);
return probe;
}
async function probeMagmux(binary?: string): Promise<MagmuxBinary> {
const found = binary ?? findMagmuxBinaryOrNull();
if (!found)
throw new MagmuxUnavailableError(
"magmux_unavailable: magmux not found (bundled package or PATH); install it: brew install MadAppGang/tap/magmux"
);
let version = await readMagmuxVersion(found);
// Under load a run has exited 0 with no version in its output, and six concurrent probes
// refused a good 0.17.0 as "version unknown". Ask once more before refusing; a real version
// below the floor is an answer and is not retried.
if (!version) version = await readMagmuxVersion(found);
if (!version || !versionAtLeast(version, MIN_MAGMUX_VERSION))
throw new MagmuxUnavailableError(
`magmux_unavailable: ${found} is version ${version || "unknown"}; panes need >= ${MIN_MAGMUX_VERSION} (a socket at any path depth, and the Claude Code input gate bound to a named transcript); upgrade: brew upgrade MadAppGang/tap/magmux`
);
return { binary: found, version };
}
/** How long one `magmux --version` run may take before it is killed and counted as no answer. */
const MAGMUX_VERSION_TIMEOUT_MS = 5000;
/** The `X.Y.Z` from one `<binary> --version` run, read from stdout and stderr together; "" when absent. */
async function readMagmuxVersion(found: string): Promise<string> {
const out = await runMagmuxVersion(found, MAGMUX_VERSION_TIMEOUT_MS);
return out.match(/(\d+\.\d+\.\d+)/)?.[1] ?? "";
}
/**
* One `<binary> --version` run, bounded by a deadline that does NOT depend on the child exiting.
* execFile's own `timeout` only sends a signal and then waits for the child to close: a child that
* ignores SIGTERM (or whose exit is never observed) kept the promise pending, and because
* `assertMagmuxAvailable` hands one in-flight probe to every caller, every later pane start in the
* process hung with it. On expiry the run rejects at once, the child is SIGKILLed, and its pipes
* are released (a grandchild may still hold them open).
*/
function runMagmuxVersion(found: string, timeoutMs: number): Promise<string> {
return new Promise((resolveRun, rejectRun) => {
let settled = false;
let child: ChildProcess | undefined;
const timer = setTimeout(() => {
fail(`no answer in ${timeoutMs} ms`);
try {
child?.kill("SIGKILL");
} catch {
// already gone
}
child?.stdout?.destroy();
child?.stderr?.destroy();
}, timeoutMs);
const settle = (): boolean => {
if (settled) return false;
settled = true;
clearTimeout(timer);
return true;
};
const fail = (detail: string): void => {
if (!settle()) return;
rejectRun(
new MagmuxUnavailableError(`magmux_unavailable: ${found} --version failed: ${detail}`)
);
};
try {
// async: the first create_session or team run must not stall the MCP server's event
// loop for up to 5 s (every other session's frames and socket share it)
child = execFile(found, ["--version"], { encoding: "utf8" }, (error, stdout, stderr) => {
if (error) return fail(error.message);
if (settle()) resolveRun(`${stdout}\n${stderr}`);
});
} catch (e) {
fail(e instanceof Error ? e.message : String(e));
}
});
}
/* ───────────────────────────── launcher ───────────────────────────── */
export interface ClaudishLaunch {
command: string;
prefixArgs: string[];
}
export class ClaudishNotFoundError extends Error {
readonly code = "pane_lost";
}
/** Which claudish the launcher `exec`s: `CLAUDISH_BIN` (`*.ts` → `<bun> --no-env-file run <file>`), else PATH. */
export function resolveClaudishLaunch(
parentEnv: Record<string, string | undefined>
): ClaudishLaunch {
const t = resolveClaudishSpawn(parentEnv as NodeJS.ProcessEnv);
if (t.command.includes("/")) return t;
const found = Bun.which(t.command, { PATH: parentEnv.PATH ?? "" });
if (!found) throw new ClaudishNotFoundError(`${t.command} not found on PATH`);
return { command: found, prefixArgs: t.prefixArgs };
}
/** POSIX single-quote escaping. */
export function shq(s: string): string {
return `'${s.replaceAll("'", `'\\''`)}'`;
}
/** The launcher: `cd` to the realpath cwd, then `exec` claudish (no watcher, no PATH line). */
export function launcherScript(cwd: string, launch: ClaudishLaunch, argv: string[]): string {
const words = [launch.command, ...launch.prefixArgs, ...argv].map(shq).join(" ");
return `cd -- ${shq(cwd)} || exit 97\nexec ${words}\n`;
}
export const SHELL_SHIM = '#!/bin/sh\n[ "$1" = -l ] && shift\nexec /bin/sh "$@"\n';
/** The `-e` value. It never names `claude`: the pane is declared, not a direct launch. */
export function paneCommand(ctlDir: string): string {
const cmd = `. ${shq(join(ctlDir, "pane-launch.sh"))}`;
if (/claude /.test(cmd) || /claude$/.test(cmd) || /(^|\/)claude['"]?$/.test(cmd))
throw new Error(`pane command would attach magmux's Claude Code controller: ${cmd}`);
return cmd;
}
export interface LaunchDirs {
/** control directory: pane-launch.sh, sh-shim, magmux.pid, group — never shown to the model */
ctlDir: string;
/** turn directory: turn-<n>.md only; the child's `--add-dir` (R3-M2) */
turnDir: string;
}
export function createLaunchDirs(root: string): LaunchDirs {
const ctlDir = mkdtempSync(join(root, "launch-"));
chmodSync(ctlDir, 0o700);
const turnDir = mkdtempSync(join(root, "launch-"));
chmodSync(turnDir, 0o700);
return { ctlDir, turnDir };
}
export function writeLauncherFiles(ctlDir: string, script: string): void {
writeFileSync(join(ctlDir, "pane-launch.sh"), script, { mode: 0o600, flag: "wx" });
writeFileSync(join(ctlDir, "sh-shim"), SHELL_SHIM, { mode: 0o700, flag: "wx" });
}
/* ───────────────────────────── spawns ───────────────────────────── */
/**
* The pane watcher (D15 layer 1): a detached `/bin/sh` whose stdin is a pipe from this
* process. EOF on it — this process ended, by any means — makes it verify and kill the
* pane's group and magmux, then clean the files; `done` ends it after a clean reap.
*/
export function spawnPaneWatcher(args: WatcherArgs): ChildProcess {
const proc = spawn("/bin/sh", watcherArgv(args), {
stdio: ["pipe", "ignore", "ignore"],
detached: true,
env: { PATH: "/bin:/usr/bin:/usr/sbin:/sbin", LC_ALL: "C" },
});
// EPIPE on `done\n` means the watcher is already gone, which is not an error (R3-M1).
proc.stdin?.on("error", () => {});
proc.on("error", () => {});
proc.unref();
(proc.stdin as unknown as { unref?: () => void } | null)?.unref?.();
return proc;
}
/**
* Fatal magmux stderr: an invalid `--id` (magmux ignores it and binds under its pid), an
* unusable `--sock-dir` / `MAGMUX_SOCK_DIR` (magmux exits 1), or a failed socket bind.
*/
export const FATAL_MAGMUX_STDERR =
/ignoring --id|magmux: (?:--sock-dir|MAGMUX_SOCK_DIR) |magmux: socket/;
export interface MagmuxSpawnInput {
binary: string;
paneId: string;
sockRoot: string;
ctlDir: string;
cwd: string;
/**
* magmux's environment (`buildPaneEnv`). It is built from the same parent environment
* the transcript path is derived from, so a `CLAUDE_CONFIG_DIR` the session uses is in
* magmux's own environment too, where magmux resolves the session registry.
*/
env: Record<string, string>;
/** the `--session-id` claudish passes Claude Code */
sessionUuid: string;
/** the transcript claudish's follower reads; made absolute here (magmux requires it) */
transcriptPath: string;
}
/**
* magmux's argv. The declaration comes before `-e`, which it binds; `--id <paneId>
* --sock-dir` stays adjacent, because that pair is how the reap, the sweep and the pane
* watcher recognise this pane's magmux (`magmuxNeedle`).
*/
export function paneMagmuxArgv(input: Omit<MagmuxSpawnInput, "binary" | "cwd" | "env">): string[] {
return [
"--headless",
"--no-status",
"--controller",
"claude-code",
"--session-id",
input.sessionUuid,
"--transcript",
resolve(input.transcriptPath),
"--id",
input.paneId,
"--sock-dir",
input.sockRoot,
"-e",
paneCommand(input.ctlDir),
];
}
export function spawnPaneMagmux(input: MagmuxSpawnInput): ChildProcess {
const proc = spawn(input.binary, paneMagmuxArgv(input), {
cwd: input.cwd,
env: input.env,
stdio: ["ignore", "ignore", "pipe"],
detached: true,
});
proc.on("error", () => {});
return proc;
}