Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(pane): ask magmux for the exit code when the child dies while the socket is down

Jack Rudenkof0feba30a60e
diff --git a/packages/cli/src/pane/pane-exit-code.followup.test.ts b/packages/cli/src/pane/pane-exit-code.followup.test.ts
new file mode 100644
index 00000000..195268c8
--- /dev/null
+++ b/packages/cli/src/pane/pane-exit-code.followup.test.ts
@@ -0,0 +1,159 @@
+/**
+ * F2: the child's exit code survives a magmux socket drop.
+ *
+ * Real magmux plus the fake interactive child (scenario `exit_mid_turn`, which exits with
+ * code 3 about 300 ms after it receives a prompt). The test drops the session's socket while
+ * the prompt is being delivered, and keeps the magmux socket path unreachable (renamed away,
+ * the listener itself stays alive) so the session cannot simply reconnect and see the exit
+ * event. Then the child exits.
+ *
+ * - reachable-after-exit: the socket path comes back as soon as the child is gone. magmux
+ * still holds the pane and knows the code, so the session must report 3. (Whichever way
+ * the session learns it, through its own reconnect or by asking, the outcome is the same.)
+ * - unreachable: the path never comes back. magmux cannot be asked, so the session finishes
+ * without a code, and does so promptly (a bounded attempt, not a hang).
+ *
+ * Timing note: the one-second liveness tick means "reachable" can in principle lose a race
+ * if the host is badly overloaded; re-run alone before calling a failure real.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, renameSync } from "node:fs";
+import {
+ type GateRun,
+ clientOf,
+ disposeGatePanes,
+ gateUntil,
+ startGatePane,
+} from "./test-helpers/gated-pane.js";
+import { MAGMUX, NO_MAGMUX_MESSAGE } from "./test-helpers/hermetic-env.js";
+
+const T = 90_000;
+/** Generous for a loaded host; the old behaviour finishes in ~1 s, a hang would be far over. */
+const PROMPT_FINISH_MS = 12_000;
+
+afterEach(async () => {
+ await disposeGatePanes();
+});
+
+function alive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (e) {
+ return (e as NodeJS.ErrnoException).code === "EPERM";
+ }
+}
+
+async function until(check: () => boolean, label: string, ms: number): Promise<void> {
+ const end = Date.now() + ms;
+ while (!check()) {
+ if (Date.now() > end) throw new Error(`timed out waiting for ${label}`);
+ await Bun.sleep(5);
+ }
+}
+
+/** Start an idle interactive pane whose first prompt makes the child exit with code 3. */
+async function startExiting(): Promise<GateRun> {
+ const r = await startGatePane("exit_mid_turn", { shape: "interactive" });
+ await gateUntil(r, (s) => s.state === "AWAITING_INPUT", 45_000);
+ return r;
+}
+
+/**
+ * Send the prompt; the instant the first send is on the wire, hide the socket path and close
+ * the session's client. Returns the child's pid and the paths needed to put the socket back.
+ */
+async function dropDuringDelivery(r: GateRun): Promise<{ pid: number; hidden: string }> {
+ const pid = r.s.snapshot().panePid;
+ if (!pid) throw new Error("the pane has no pid to watch");
+ const sock = r.s.sockPath;
+ const hidden = `${sock}.hidden`;
+ const client = clientOf(r);
+ const real = client.request.bind(client);
+ let dropped = false;
+ client.request = async (message, timeout) => {
+ const delivery = real(message, timeout);
+ if (message.type === "send" && typeof message.text === "string" && !dropped) {
+ dropped = true;
+ await Bun.sleep(100);
+ renameSync(sock, hidden);
+ client.close();
+ }
+ return delivery;
+ };
+ r.s.send("go");
+ await until(() => dropped, "the socket drop", 20_000);
+ return { pid, hidden };
+}
+
+describe.skipIf(!MAGMUX)(
+ `F2 exit code after a socket drop (${MAGMUX ? "real magmux" : NO_MAGMUX_MESSAGE})`,
+ () => {
+ test(
+ "F2-0 control: without any drop the child's exit code 3 is reported",
+ async () => {
+ const r = await startExiting();
+ r.s.send("go");
+ const snap = await gateUntil(r, (s) => s.exitCode !== null || s.state === "FAILED", 45_000);
+ expect(snap.exitCode).toBe(3);
+ },
+ T
+ );
+
+ for (const lagMs of [0, 1000]) {
+ test(
+ `F2-1 socket dropped, child exits, magmux reachable ${lagMs} ms later: the session reports code 3`,
+ async () => {
+ const r = await startExiting();
+ const { pid, hidden } = await dropDuringDelivery(r);
+ const sock = r.s.sockPath;
+ await until(() => !alive(pid), "the child to exit", 45_000);
+ // The old liveness-only path gives up about a second after the exit. With 0 ms the
+ // session's own redial can see the exit event; with 1000 ms only an attempt made
+ // at the moment the child is found gone, and bounded to a second or two, can.
+ // magmux itself holds the pane and its code throughout.
+ await Bun.sleep(lagMs);
+ if (existsSync(hidden)) renameSync(hidden, sock);
+ const snap = await Promise.race([
+ r.s.terminal,
+ Bun.sleep(PROMPT_FINISH_MS).then(() => {
+ throw new Error(`no terminal state in ${PROMPT_FINISH_MS} ms after the child exited`);
+ }),
+ ]);
+ expect(snap.exitCode).toBe(3);
+ expect(snap.state).toBe("FAILED");
+ },
+ T
+ );
+ }
+
+ test(
+ "F2-2 socket dropped, child exits, magmux unreachable: finishes promptly with no exit code",
+ async () => {
+ const r = await startExiting();
+ const { pid, hidden } = await dropDuringDelivery(r);
+ const sock = r.s.sockPath;
+ await until(() => !alive(pid), "the child to exit", 45_000);
+ const goneAt = Date.now();
+ try {
+ const snap = await Promise.race([
+ r.s.terminal,
+ Bun.sleep(PROMPT_FINISH_MS).then(() => {
+ throw new Error(
+ `the session was still unfinished ${PROMPT_FINISH_MS} ms after the child exited with magmux unreachable`
+ );
+ }),
+ ]);
+ expect(Date.now() - goneAt).toBeLessThan(PROMPT_FINISH_MS);
+ expect(snap.exitCode).toBeNull();
+ expect(["FAILED", "COMPLETED", "CANCELLED", "EMPTY", "TIMEOUT"]).toContain(snap.state);
+ } finally {
+ // Put the path back so the pane can be reaped and the no-orphan check can pass.
+ if (existsSync(hidden)) renameSync(hidden, sock);
+ }
+ },
+ T
+ );
+ }
+);
diff --git a/packages/cli/src/pane/pane-session-liveness-exit.test.ts b/packages/cli/src/pane/pane-session-liveness-exit.test.ts
new file mode 100644
index 00000000..3e6bfa43
--- /dev/null
+++ b/packages/cli/src/pane/pane-session-liveness-exit.test.ts
@@ -0,0 +1,127 @@
+/**
+ * A liveness exit (ESRCH while the magmux socket is down) asks magmux for the exit code before
+ * finishing, bounded, and finishes without a code when magmux cannot answer.
+ *
+ * The session is never started: no client is attached, which is the disconnected state, and
+ * `magmux` stays null, so no redial runs beside the query. magmux itself is a small unix-socket
+ * server speaking its NDJSON `list` reply.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { PaneSessionImpl, type PaneSessionOptions } from "./pane-session.js";
+
+type ListAnswer = "dead-with-code" | "silent";
+
+const cleanups: Array<() => Promise<void> | void> = [];
+afterEach(async () => {
+ for (const c of cleanups.splice(0).reverse()) await c();
+});
+
+/** A pid that existed and is gone: spawned, exited and reaped by this process. */
+async function deadPid(): Promise<number> {
+ const child = spawn("true");
+ await new Promise((resolve) => child.once("exit", resolve));
+ return child.pid!;
+}
+
+function fakeMagmux(sockPath: string, answer: ListAnswer, exitCode: number): void {
+ const server = Bun.listen({
+ unix: sockPath,
+ socket: {
+ data(socket, data) {
+ for (const line of data.toString().split("\n").filter(Boolean)) {
+ const msg = JSON.parse(line) as { id: string; type: string };
+ if (answer === "silent" || msg.type !== "list") continue;
+ socket.write(
+ `${JSON.stringify({
+ type: "reply",
+ id: msg.id,
+ ok: true,
+ result: { panes: [{ pane: 0, pid: 1, dead: true, exitCode }] },
+ })}\n`
+ );
+ }
+ },
+ },
+ });
+ cleanups.push(() => server.stop(true));
+}
+
+function session(): { session: PaneSessionImpl; sockPath: string } {
+ // A short root: a unix socket path is limited to ~104 bytes on macOS.
+ const root = mkdtempSync("/tmp/plx-");
+ cleanups.push(() => rmSync(root, { recursive: true, force: true }));
+ const configDir = join(root, "config");
+ const ctlDir = join(root, "launch-ctl000");
+ const turnDir = join(root, "launch-turn00");
+ for (const dir of [configDir, ctlDir, turnDir]) mkdirSync(dir);
+ const opts: PaneSessionOptions = {
+ kind: "s",
+ label: "liveness-exit-test",
+ callerFlags: [],
+ spawnModel: "liveness-exit-test",
+ cwd: root,
+ sessionUuid: crypto.randomUUID(),
+ transcriptPath: join(root, "transcript.jsonl"),
+ slotEnv: {},
+ shape: "interactive",
+ readAvailable: true,
+ parentEnv: { HOME: root, CLAUDE_CONFIG_DIR: configDir },
+ decide: () => "continue",
+ onBlocked: () => "wait",
+ };
+ const sockPath = join(root, "m.sock");
+ const s = new PaneSessionImpl(opts, { paneId: "liveness", sockPath, root, ctlDir, turnDir });
+ cleanups.push(async () => {
+ (s as any).reapPromise = Promise.resolve();
+ await s.shutdownReap("liveness test cleanup");
+ });
+ return { session: s, sockPath };
+}
+
+async function livenessExit(s: PaneSessionImpl): Promise<{ exitCode: number | null; ms: number }> {
+ (s as any).panePidValue = await deadPid();
+ const started = Date.now();
+ (s as any).checkLiveness();
+ const deadline = Date.now() + 5000;
+ while (!(s as any).paneExited && Date.now() < deadline) await Bun.sleep(5);
+ expect((s as any).paneExited).toBe(true);
+ return { exitCode: s.snapshot().exitCode, ms: Date.now() - started };
+}
+
+describe("liveness exit after a socket drop", () => {
+ test("takes the exit code magmux still holds", async () => {
+ const { session: s, sockPath } = session();
+ fakeMagmux(sockPath, "dead-with-code", 3);
+ const { exitCode } = await livenessExit(s);
+ expect(exitCode).toBe(3);
+ expect(s.snapshot().detail ?? "").toContain("pane child exited with code 3");
+ });
+
+ test("redials: takes the code when the socket comes back a second after the exit is seen", async () => {
+ const { session: s, sockPath } = session();
+ setTimeout(() => fakeMagmux(sockPath, "dead-with-code", 3), 1000);
+ const { exitCode, ms } = await livenessExit(s);
+ expect(exitCode).toBe(3);
+ expect(ms).toBeGreaterThanOrEqual(900);
+ });
+
+ test("finishes without a code within the bound when magmux is unreachable", async () => {
+ const { session: s } = session();
+ const { exitCode, ms } = await livenessExit(s);
+ expect(exitCode).toBeNull();
+ expect(s.snapshot().detail ?? "").toContain("pane child exited (code unknown)");
+ expect(ms).toBeLessThan(2900);
+ });
+
+ test("finishes without a code within the bound when magmux does not answer", async () => {
+ const { session: s, sockPath } = session();
+ fakeMagmux(sockPath, "silent", 3);
+ const { exitCode, ms } = await livenessExit(s);
+ expect(exitCode).toBeNull();
+ expect(ms).toBeGreaterThanOrEqual(1900);
+ expect(ms).toBeLessThan(2900);
+ });
+});
diff --git a/packages/cli/src/pane/pane-session.ts b/packages/cli/src/pane/pane-session.ts
index cbc5605c..b3227cfc 100644
--- a/packages/cli/src/pane/pane-session.ts
+++ b/packages/cli/src/pane/pane-session.ts
@@ -233,6 +233,17 @@ export const GATE_GRACE_MS = SECONDARY_QUIET_MS;
* The event stays the primary path (it carries `lastLine`); this is its backstop.
*/
const GATE_DEAD_BACKSTOP_MS = 1_000;
+/**
+ * The longest a liveness exit (ESRCH while disconnected) waits for magmux to name the code.
+ * magmux keeps a dead pane's code after the socket drops, and whatever dropped the socket can
+ * hold the path away for a moment, so the query redials until this bound rather than asking
+ * once. Two seconds covers a socket that comes back within about a second of the exit being
+ * seen (the liveness check itself runs once a second); it is also all a magmux that is gone,
+ * wedged or slow can add to the finish.
+ */
+const EXIT_CODE_QUERY_MS = 2_000;
+/** The redial period inside EXIT_CODE_QUERY_MS, and the `list` re-ask period. */
+const EXIT_CODE_RETRY_MS = 50;
/** Gate reasons that carry no dialog kind: a static screen under one is named from its words. */
const GATE_KINDLESS_REASONS: ReadonlySet<string> = new Set([
"starting",
@@ -655,6 +666,8 @@ export class PaneSessionImpl implements PaneSession, RegisteredPane {
private stderrHead = "";
private paneClosed = false;
private paneExited = false;
+ /** A liveness exit is asking magmux for the code; the exit path waits for the answer. */
+ private exitCodeQuery = false;
private reaping = false;
private fastReap = false;
private reapPromise: Promise<void> | null = null;
@@ -1283,9 +1296,16 @@ export class PaneSessionImpl implements PaneSession, RegisteredPane {
}
}
- /** While disconnected, the pane's liveness is `kill(panePid, 0)` every second (X-M12). */
+ /**
+ * While disconnected, the pane's liveness is `kill(panePid, 0)` every second (X-M12).
+ *
+ * ESRCH means magmux has already reaped the child, so magmux knows its exit code even though
+ * our socket is gone. Before finishing, a bounded query asks it (`exitCodeFromMagmux`); the
+ * code is then stored together with `paneExited`, as `onPaneExit` does (H-27). Unreachable or
+ * silent, the exit goes on without a code, exactly as before.
+ */
private checkLiveness(): void {
- if (this.client || !this.panePidValue || this.paneExited) return;
+ if (this.client || !this.panePidValue || this.paneExited || this.exitCodeQuery) return;
const now = Date.now();
if (now - this.lastLivenessAt < 1000) return;
this.lastLivenessAt = now;
@@ -1293,10 +1313,64 @@ export class PaneSessionImpl implements PaneSession, RegisteredPane {
process.kill(this.panePidValue, 0);
} catch (e) {
if ((e as NodeJS.ErrnoException).code === "ESRCH") {
- this.paneExited = true;
- this.applyExitPath(null);
+ this.exitCodeQuery = true;
+ void this.exitCodeFromMagmux().then((code) => {
+ this.exitCodeQuery = false;
+ // a redial that attached meanwhile saw the dead pane and took the exit path with its code
+ if (this.paneExited || isTerminalPhase(this.phase)) return;
+ this.paneExited = true;
+ this.exitCode = code;
+ this.step(() => this.applyExitPath(code));
+ });
+ }
+ }
+ }
+
+ /**
+ * Pane 0's exit code from magmux over a fresh connection, or null when magmux cannot be
+ * reached, does not answer, or does not report the pane dead with a numeric code within
+ * EXIT_CODE_QUERY_MS. Its own dial loop, not the redial loop: that one backs off to a second
+ * between attempts, and its attach does far more than this needs. Never throws.
+ */
+ private async exitCodeFromMagmux(): Promise<number | null> {
+ const deadline = Date.now() + EXIT_CODE_QUERY_MS;
+ const left = () => deadline - Date.now();
+ const client = await this.dialWithin(left);
+ if (!client) return null;
+ try {
+ // magmux marks the pane dead once it has reaped the child; ESRCH says it has, but the
+ // mark may trail the reap by a moment, so ask again until the bound.
+ while (left() > 0) {
+ const r = await client.request<{ panes?: Array<Record<string, unknown>> }>(
+ { type: "list" },
+ Math.max(1, left())
+ );
+ if (!r.ok) return null;
+ const p0 = r.result.panes?.find((p) => p.pane === 0);
+ if (!p0) return null;
+ if (p0.dead === true) return typeof p0.exitCode === "number" ? p0.exitCode : null;
+ await Bun.sleep(Math.min(EXIT_CODE_RETRY_MS, Math.max(0, left())));
+ }
+ return null;
+ } finally {
+ client.close();
+ }
+ }
+
+ /** A fresh magmux connection, redialled every EXIT_CODE_RETRY_MS while `left()` is positive. */
+ private async dialWithin(left: () => number): Promise<MagmuxClient | null> {
+ while (left() > 0 && !this.reaping && !isTerminalPhase(this.phase)) {
+ try {
+ // a connect that never completes must not outlive the bound either
+ const dial = MagmuxClient.dial(this.sockPath);
+ const client = await Promise.race([dial, Bun.sleep(Math.max(0, left())).then(() => null)]);
+ if (!client) void dial.then((late) => late.close()).catch(() => {});
+ return client;
+ } catch {
+ await Bun.sleep(Math.min(EXIT_CODE_RETRY_MS, Math.max(0, left())));
}
}
+ return null;
}
private t(key: keyof NonNullable<PaneSessionOptions["timings"]>, dflt: number): number {
@@ -2950,8 +3024,8 @@ export class PaneSessionImpl implements PaneSession, RegisteredPane {
/**
* §2.2 rule 2: interactive, IDLE, exit 0, after /exit or ≥ 1 settled turn, nothing
- * admitted. An exit seen only as ESRCH while the socket is lost has no code: after a
- * delivered /exit that is still the clean exit it asked for.
+ * admitted. An exit seen only as ESRCH while the socket is lost has no code when magmux could
+ * not name it either: after a delivered /exit that is still the clean exit it asked for.
*/
private cleanIdleExit(code: number | null): boolean {
if (this.phase !== "IDLE" || this.shape !== "interactive") return false;