Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* The interactive driver (hook-system architecture §7.5, §11.3 "Interactive driver").
*
* A HEADLESS magmux stands in for the visible one: the driver gets its socket path and
* pane id (the injection seam), and the pane runs the fake interactive child in scripted
* mode (`fake-scripted`, `FAKE_SCRIPT`, `FAKE_KEYLOG`). A second `MagmuxClient` plays the
* human: it types into the same pane, as a person at the keyboard would.
*
* The binding is a test double whose `settle()` returns a promise the test resolves,
* except where a test says "real binding". The last two blocks drive production code
* end to end: the own-pane search inside a real two-pane magmux, and the real
* `claudish -i` (ambient mode, minted session id, `--add-dir`) with the proxied fake
* and a stub upstream, where a `responseEnd` annotation crosses the in-process sink
* into `sessionIdle`, whose injection becomes the next turn.
*/
import { afterAll, describe, expect, test } from "bun:test";
import { type ChildProcess, spawn } from "node:child_process";
import { createHash, randomBytes, randomUUID } from "node:crypto";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { MagmuxClient } from "../../pane/magmux-client.js";
import {
FAKE_CHILD,
MAGMUX,
NO_MAGMUX_MESSAGE,
type PaneTestEnv,
killLeftovers,
makePaneTestEnv,
writeFakeClaudeWrapper,
} from "../../pane/test-helpers/hermetic-env.js";
import { TranscriptFollower } from "../../pane/transcript-follower.js";
import {
type StubUpstream,
startStubUpstream,
stubEndpointConfig,
} from "../../test-helpers/stub-upstream.js";
import { HookEngine } from "../engine.js";
import { InProcessSink } from "../injection/sinks.js";
import type { JournalEntry } from "../journal.js";
import type { HookDefinition } from "../public.js";
import { HookRegistry, type UserHookInput } from "../registry.js";
import type {
BindingPane,
HoldInjection,
HoldResult,
HoldTurnInfo,
SessionHookBinding,
} from "./binding.js";
import { InteractiveDriver, type InteractiveDriverOptions } from "./interactive-driver.js";
const T = 60_000;
const INDEX = join(import.meta.dir, "..", "..", "index.ts");
const PROBE = join(import.meta.dir, "test-helpers", "own-pane-probe.ts");
/* ───────────────────────────── the test double binding ───────────────────────────── */
interface SettleCall {
turn: HoldTurnInfo;
signal: AbortSignal;
resolve(r: HoldResult): void;
}
function controlled(o: { idle?: boolean } = {}) {
const calls: SettleCall[] = [];
const dropped: Array<{ text: string; reason: string }> = [];
const delivered: Array<{ text: string; at: number }> = [];
const abandoned: Array<{ text: string; reason: string }> = [];
const blocked: Array<{ kind: string; text: string }> = [];
const ends: Array<{ state: string; exitCode: number | null }> = [];
let starts = 0;
let pane: BindingPane | null = null;
const binding: SessionHookBinding = {
maxConsecutive: 3,
hasIdleWork: () => o.idle ?? true,
settle: (turn, signal) =>
new Promise<HoldResult>((resolve) => calls.push({ turn, signal, resolve })),
holdBoundMs: () => 30_000,
fireStart() {
starts++;
},
fireBlocked: (b) => void blocked.push(b),
fireEnd: (e) => void ends.push(e),
attach(p) {
pane = p;
},
noteDropped: (item, reason) => void dropped.push({ text: item.text, reason }),
noteDelivered: (item) => void delivered.push({ text: item.text, at: Date.now() }),
abandon: (res, reason) => {
for (const i of res.injections) abandoned.push({ text: i.text, reason });
},
};
return {
binding,
calls,
dropped,
abandoned,
delivered,
blocked,
ends,
starts: () => starts,
pane: () => pane as BindingPane | null,
};
}
const inject = (text: string): HoldResult => ({
injections: [{ text, hookIds: ["hook:t/x"], source: "sessionIdle" }],
});
const nothing: HoldResult = { injections: [] };
function engineOf(...defs: Array<Omit<HookDefinition, "apiVersion">>) {
const journal: JournalEntry[] = [];
const users: UserHookInput[] = defs.map((d, i) => ({
id: `hook:t/${d.id}`,
module: "/hooks/t.ts",
moduleIndex: 0,
exportIndex: i,
def: { apiVersion: 1, ...d } as HookDefinition,
}));
const engine = new HookEngine({
registry: new HookRegistry([], users, undefined),
config: {},
hostMode: "interactive",
journalSink: (e) => journal.push(e),
warn: () => {},
drainTelemetryOutbox: false,
});
return { engine, journal };
}
/* ───────────────────────────── the rig ───────────────────────────── */
interface TurnScript {
say?: string;
ask?: string;
noWitness?: boolean;
delayMs?: number;
rewake?: {
delayMs: number;
say: string;
workingMs?: number;
quietMs?: number;
gateFile?: string;
};
}
interface Rig {
t: PaneTestEnv;
uuid: string;
sock: string;
transcript: string;
turnDir: string;
magmux: ChildProcess;
human: MagmuxClient;
driver: InteractiveDriver | null;
sink: InProcessSink;
keylog(): string[];
/** type into the pane as the human does */
type(text: string, enter?: boolean): Promise<void>;
startDriver(o?: Partial<InteractiveDriverOptions>): Promise<InteractiveDriver>;
}
const rigs = new Set<Rig>();
afterAll(() => {
for (const r of rigs) cleanupRig(r);
});
function cleanupRig(r: Rig): void {
rigs.delete(r);
r.human.close();
try {
if (r.magmux.pid) process.kill(-r.magmux.pid, "SIGKILL");
} catch {
// gone
}
killLeftovers({ sockRoot: r.t.sockRoot, ids: [r.uuid] });
r.t.cleanup();
}
async function finish(r: Rig): Promise<void> {
await r.driver?.stop({ state: "COMPLETED", reason: null, exitCode: 0 });
cleanupRig(r);
}
const shq = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
/** Spawn a headless magmux whose pane 0 runs the scripted fake, and dial it as the human. */
async function rig(
script: TurnScript[],
o: {
binding?: SessionHookBinding;
extraEnv?: Record<string, string>;
driver?: Partial<InteractiveDriverOptions>;
startDriver?: boolean;
} = {}
): Promise<Rig> {
const t = makePaneTestEnv({
FAKE_SCRIPT: JSON.stringify(script),
CONTRACT_FAKE_MAX_MS: "60000",
COLUMNS: "160",
LINES: "50",
...o.extraEnv,
});
t.env.FAKE_KEYLOG = join(t.tmp, "keylog.txt");
mkdirSync(t.sockRoot, { recursive: true });
const uuid = randomUUID();
const id = `drv${randomBytes(3).toString("hex")}`;
const sock = join(t.sockRoot, `magmux-${id}.sock`);
const turnDir = mkdtempSync(join(t.tmp, "turns-"));
const cmd = `exec ${shq(process.execPath)} ${shq(FAKE_CHILD)} --model fake-scripted --session-id ${uuid}`;
const magmux = spawn(
MAGMUX as string,
["--headless", "--no-status", "--id", id, "--sock-dir", t.sockRoot, "-e", cmd],
{ cwd: t.cwd, env: t.env, stdio: ["ignore", "ignore", "ignore"], detached: true }
);
magmux.on("error", () => {});
const human = await MagmuxClient.connect(sock, { timeoutMs: 10_000 });
const sink = new InProcessSink(undefined, undefined, () => {});
const r: Rig = {
t,
uuid,
sock,
transcript: t.transcriptPathFor(uuid),
turnDir,
magmux,
human,
driver: null,
sink,
keylog: () => {
const p = t.env.FAKE_KEYLOG as string;
return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean) : [];
},
async type(text, enter = true) {
const res = await human.request({ type: "send", pane: 0, text, typed: true, enter });
if (!res.ok) throw new Error(`human send failed: ${res.code} ${res.error}`);
},
async startDriver(extra = {}) {
const d = new InteractiveDriver({
mode: "wrap",
sockPath: sock,
pane: 0,
cwd: t.cwd,
sessionId: uuid,
projectsRoot: join(t.configDir, "projects"),
turnDir,
readAvailable: true,
model: "fake-scripted",
sink,
warn: () => {},
...(o.binding ? { binding: o.binding } : {}),
...o.driver,
...extra,
// merged last, so a test's own timings refine the fast defaults, never replace them
timings: {
tickMs: 100,
typingHoldMs: 300,
replStableMs: 200,
corroborationMs: 200,
...o.driver?.timings,
...extra.timings,
},
});
r.driver = d;
await d.start();
return d;
},
};
rigs.add(r);
if (o.startDriver !== false) await r.startDriver();
return r;
}
async function until(pred: () => boolean, what: string, ms = 20_000): Promise<void> {
const end = Date.now() + ms;
while (!pred()) {
if (Date.now() > end) throw new Error(`timed out waiting for ${what}`);
await Bun.sleep(25);
}
}
const sha8 = (s: string) => createHash("sha1").update(s).digest("hex").slice(0, 8);
/* ───────────────────────────── turns and the latch ───────────────────────────── */
describe.skipIf(!MAGMUX)(`interactive driver: turns ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`, () => {
test(
"the human witness opens turns; one settle per settled turn across ticks; sessionStart at the first empty box",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], { binding: dbl.binding });
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
expect(dbl.starts()).toBe(1);
await r.type("first prompt");
await until(() => dbl.calls.length === 1, "the first settle");
expect(dbl.calls[0]?.turn).toMatchObject({
index: 1,
answer: "A1",
hookCaused: false,
apiError: false,
});
expect(d.snapshot().phase).toBe("SETTLING");
// ≥ 10 ticks and frames: the latch holds, nothing settles the turn again
await Bun.sleep(1_200);
expect(dbl.calls.length).toBe(1);
dbl.calls[0]?.resolve(nothing);
await until(() => d.snapshot().phase === "OPEN", "OPEN after the hold");
await Bun.sleep(600);
expect(dbl.calls.length).toBe(1);
await r.type("second prompt");
await until(() => dbl.calls.length === 2, "the second settle");
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2", hookCaused: false });
expect(d.snapshot()).toMatchObject({ callerAdmitted: 2, consecutiveHookTurns: 0 });
expect(dbl.starts()).toBe(1);
// the human's lines reached the fake; the driver typed nothing
expect(r.keylog()).toEqual(["first prompt", "second prompt"]);
} finally {
await finish(r);
}
},
T
);
test(
"a command-line prompt written before boot-ready opens turn 1 (offset 0)",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }], {
binding: dbl.binding,
extraEnv: { FAKE_INITIAL_PROMPT: "prompt from argv" },
startDriver: false,
});
try {
// The record and its answer are on disk BEFORE the driver exists.
await until(
() =>
existsSync(r.transcript) &&
readFileSync(r.transcript, "utf8").includes("turn_duration"),
"the argv turn in the transcript"
);
// Control: a turn opened at the current size — the offset a driver would take if
// it did not open turn 1 at 0 — never sees the prompt.
const control = new TranscriptFollower(r.transcript, join(r.t.tmp, "none"));
control.poll();
control.openTurn({ index: 1, offset: control.size(), witness: { kind: "human" } });
control.poll();
expect(control.view().current?.acceptedAt).toBeNull();
const d = await r.startDriver();
await until(() => dbl.calls.length === 1, "the argv turn's settle");
expect(dbl.calls[0]?.turn).toMatchObject({ index: 1, answer: "A1", hookCaused: false });
expect(d.snapshot().callerAdmitted).toBe(1);
expect(r.keylog()).toEqual([]);
} finally {
await finish(r);
}
},
T
);
});
/* ───────────────────────────── delivery ───────────────────────────── */
describe.skipIf(!MAGMUX)(`interactive driver: delivery ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`, () => {
test(
"an injection returned at settle is typed as the next turn, which settles hook-caused",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], { binding: dbl.binding });
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
dbl.calls[0]?.resolve(inject("HOOK-PING"));
await until(() => r.keylog().includes("HOOK-PING"), "the injected line");
await until(() => dbl.calls.length === 2, "settle 2");
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2", hookCaused: true });
expect(dbl.calls[1]?.turn.consecutiveHookTurns).toBe(1);
expect(dbl.delivered.map((x) => x.text)).toEqual(["HOOK-PING"]);
expect(dbl.dropped).toEqual([]);
expect(d.snapshot()).toMatchObject({ callerAdmitted: 1, consecutiveHookTurns: 1 });
} finally {
await finish(r);
}
},
T
);
test(
"a long injection goes to a turn file in the --add-dir turn dir, and the child reads it",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, {}], { binding: dbl.binding });
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
const long = `line one of the hook's message\n${"x".repeat(700)}\nlast line`;
dbl.calls[0]?.resolve(inject(long));
await until(() => dbl.calls.length === 2, "settle 2");
const typed = r.keylog()[1] as string;
expect(typed).toStartWith(`Your task is in the file \`${join(r.turnDir, "turn-1.md")}\``);
expect(readdirSync(r.turnDir)).toEqual(["turn-1.md"]);
expect(readFileSync(join(r.turnDir, "turn-1.md"), "utf8")).toBe(long);
// the fake answers with the hash of what it READ: the whole text arrived
expect(dbl.calls[1]?.turn).toMatchObject({
index: 2,
hookCaused: true,
answer: `ANSWER fake-scripted ${sha8(long)}`,
});
} finally {
await finish(r);
}
},
T
);
test(
"the gate: never while the box holds text; only after the box was empty and unchanged for the typing hold",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], {
binding: dbl.binding,
driver: { timings: { typingHoldMs: 1_500 } },
});
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
await r.type("half-typed", false);
await Bun.sleep(400);
dbl.calls[0]?.resolve(inject("HOOK"));
await Bun.sleep(2_500);
expect(dbl.delivered).toEqual([]);
expect(r.keylog()).toEqual(["go"]);
expect(d.snapshot().pendingHookInputs).toBe(1);
// the human clears the box (ctrl-u): the hold restarts from that change
await r.type("\u0015", false);
const cleared = Date.now();
await until(() => dbl.delivered.length === 1, "delivery after the hold");
const waited = (dbl.delivered[0]?.at as number) - cleared;
expect(waited).toBeGreaterThanOrEqual(1_400);
expect(waited).toBeLessThan(4_000);
await until(() => r.keylog().includes("HOOK"), "the injected line");
expect(r.keylog()).not.toContain("half-typed");
} finally {
await finish(r);
}
},
T
);
test(
"a human prompt witnessed before delivery makes the pending injection stale",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], { binding: dbl.binding });
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
await r.type("draft", false);
// Let the draft reach the screen first: a keystroke inside the last frame before
// the send is the accepted residual race (§7.5), not what this test is about.
await Bun.sleep(600);
dbl.calls[0]?.resolve(inject("HOOK"));
await until(() => d.snapshot().phase === "OPEN", "OPEN");
// the human replaces the draft and submits it
await r.type("\u0015the human's own turn");
await until(() => dbl.calls.length === 2, "settle 2");
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2", hookCaused: false });
dbl.calls[1]?.resolve(nothing);
await until(() => dbl.dropped.length === 1, "the stale drop");
expect(dbl.dropped).toEqual([{ text: "HOOK", reason: "stale" }]);
await Bun.sleep(800);
expect(r.keylog()).toEqual(["go", "the human's own turn"]);
expect(dbl.delivered).toEqual([]);
expect(d.snapshot()).toMatchObject({ callerAdmitted: 2, pendingHookInputs: 0 });
} finally {
await finish(r);
}
},
T
);
test(
"never Esc: an injection queued during a question waits, and no key but its own line is ever sent",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { ask: "Which one?" }], { binding: dbl.binding });
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
dbl.calls[0]?.resolve(nothing);
await until(() => d.snapshot().phase === "OPEN", "OPEN");
await r.type("ask me");
await until(() => dbl.blocked.length === 1, "sessionBlocked");
expect(dbl.blocked[0]?.kind).toBe("question");
const pane = dbl.pane();
expect(pane).not.toBeNull();
pane?.queueInjections([
{ text: "HOOK", hookIds: ["hook:t/x"], source: "sessionStart" } satisfies HoldInjection,
]);
await Bun.sleep(2_500);
expect(r.keylog()).toEqual(["go", "ask me"]);
expect(r.keylog()).not.toContain("<ESC>");
expect(dbl.delivered).toEqual([]);
expect(d.snapshot()).toMatchObject({ phase: "RUNNING", pendingHookInputs: 1 });
expect(dbl.blocked.length).toBe(1);
} finally {
await finish(r);
}
},
T
);
test(
"acceptance: an injected line whose witness never appears is dropped send_not_accepted",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { noWitness: true }], {
binding: dbl.binding,
driver: { timings: { acceptMs: 1_000 } },
});
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
dbl.calls[0]?.resolve(inject("HOOK"));
await until(() => r.keylog().includes("HOOK"), "the typed line");
expect(d.snapshot().phase).toBe("ADMITTING");
await until(() => dbl.dropped.length === 1, "the acceptance timeout", 5_000);
expect(dbl.dropped).toEqual([{ text: "HOOK", reason: "send_not_accepted" }]);
expect(d.snapshot().phase).toBe("OPEN");
expect(dbl.calls.length).toBe(1);
} finally {
await finish(r);
}
},
T
);
});
/* ───────────────────────────── re-wake (D23) ───────────────────────────── */
describe.skipIf(!MAGMUX)(
`interactive driver: a lost send reply ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`,
() => {
/**
* The driver's send of `text` reaches magmux (with `enter` as given here), and its
* reply is then reported lost (`client_timeout`), as a dropped socket would.
*/
function loseReplyOf(text: string, enter: boolean): () => void {
const proto = MagmuxClient.prototype as unknown as {
request(msg: Record<string, unknown>, ms?: number): Promise<unknown>;
};
const original = proto.request;
proto.request = async function (this: unknown, msg: Record<string, unknown>, ms?: number) {
if (msg.type !== "send" || msg.text !== text) return original.call(this, msg, ms);
await original.call(this, { ...msg, enter }, ms);
return { ok: false, code: "client_timeout", error: "no reply (test)" };
};
return () => {
proto.request = original;
};
}
/**
* The driver's send of `text` is typed without its Enter, then the connection
* closes before the reply: the old client can deliver nothing more.
*/
function dropConnectionAfter(text: string): () => void {
const proto = MagmuxClient.prototype as unknown as {
request(msg: Record<string, unknown>, ms?: number): Promise<unknown>;
};
const original = proto.request;
proto.request = async function (
this: MagmuxClient,
msg: Record<string, unknown>,
ms?: number
) {
if (msg.type !== "send" || msg.text !== text) return original.call(this, msg, ms);
await original.call(this, { ...msg, enter: false }, ms);
// as `onClose` does: the reply is reported lost once the socket has closed
this.close();
while (!this.isClosed) await Bun.sleep(5);
return { ok: false, code: "client_lost", error: "connection closed (test)" };
};
return () => {
proto.request = original;
};
}
test(
"the connection closed after the line was typed, its Enter lost: Enter goes through the new connection",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], { binding: dbl.binding });
const restore = dropConnectionAfter("HOOK-LOST");
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
dbl.calls[0]?.resolve(inject("HOOK-LOST"));
await until(() => dbl.calls.length === 2, "settle 2", 25_000);
expect(dbl.dropped).toEqual([]);
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2", hookCaused: true });
expect(r.keylog()).toEqual(["go", "HOOK-LOST"]);
} finally {
restore();
await finish(r);
}
},
T
);
for (const enter of [true, false]) {
test(
`the line was typed${enter ? " and entered" : ", its Enter lost"}: the injection is accepted as the hook's turn`,
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], { binding: dbl.binding });
const restore = loseReplyOf("HOOK-LOST", enter);
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
dbl.calls[0]?.resolve(inject("HOOK-LOST"));
await until(() => dbl.calls.length === 2, "settle 2", 25_000);
expect(dbl.dropped).toEqual([]);
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2", hookCaused: true });
expect(d.snapshot()).toMatchObject({ callerAdmitted: 1, consecutiveHookTurns: 1 });
expect(r.keylog()).toEqual(["go", "HOOK-LOST"]);
} finally {
restore();
await finish(r);
}
},
T
);
}
}
);
describe.skipIf(!MAGMUX)(`interactive driver: re-wake ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`, () => {
test(
"a notification during a pending injection neither drops it stale nor resets the cap; the turn settles again with its index",
async () => {
const dbl = controlled();
const r = await rig(
[{ say: "A1", rewake: { delayMs: 1_200, say: "A1b" } }, { say: "A2" }, { say: "A3" }],
{ binding: dbl.binding, driver: { timings: { typingHoldMs: 3_500 } } }
);
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
dbl.calls[0]?.resolve(inject("HOOK"));
await until(() => d.snapshot().phase === "OPEN", "OPEN with the injection pending");
expect(d.snapshot().pendingHookInputs).toBe(1);
// the background notification wakes the model: the SAME turn settles again
await until(() => dbl.calls.length === 2, "the re-woken turn's settle");
expect(dbl.calls[1]?.turn).toMatchObject({ index: 1, hookCaused: false });
expect(dbl.calls[1]?.turn.answer).toContain("A1b");
expect(d.snapshot()).toMatchObject({ callerAdmitted: 1, consecutiveHookTurns: 0 });
expect(dbl.dropped).toEqual([]);
dbl.calls[1]?.resolve(nothing);
// the injection survived and is delivered once the gate opens
await until(() => r.keylog().includes("HOOK"), "the injection", 10_000);
await until(() => dbl.calls.length === 3, "the hook turn's settle");
expect(dbl.calls[2]?.turn).toMatchObject({ index: 2, hookCaused: true, answer: "A2" });
expect(dbl.dropped).toEqual([]);
} finally {
await finish(r);
}
},
T
);
test(
"a re-wake DURING the hold aborts it with reason rewake; the same turn is held again",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1", rewake: { delayMs: 1_000, say: "A1b" } }], {
binding: dbl.binding,
});
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
await until(() => dbl.calls[0]?.signal.aborted === true, "the hold's abort");
expect(dbl.calls[0]?.signal.reason).toBe("rewake");
await until(() => dbl.calls.length === 2, "the second hold of turn 1");
expect(dbl.calls[1]?.turn.index).toBe(1);
// a late result of the abandoned hold changes nothing
dbl.calls[0]?.resolve(inject("LATE"));
dbl.calls[1]?.resolve(nothing);
await Bun.sleep(1_000);
expect(r.keylog()).toEqual(["go"]);
expect(d.snapshot()).toMatchObject({ phase: "OPEN", callerAdmitted: 1 });
} finally {
await finish(r);
}
},
T
);
test(
"a human prompt DURING the hold aborts it with reason caller",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }, { say: "A2" }], { binding: dbl.binding });
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
await r.type("again");
await until(() => dbl.calls[0]?.signal.aborted === true, "the hold's abort");
expect(dbl.calls[0]?.signal.reason).toBe("caller");
dbl.calls[0]?.resolve(inject("HOOK"));
await until(() => dbl.calls.length === 2, "settle 2");
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2", hookCaused: false });
dbl.calls[1]?.resolve(nothing);
await Bun.sleep(800);
expect(r.keylog()).toEqual(["go", "again"]);
} finally {
await finish(r);
}
},
T
);
test(
"a re-wake already in the transcript when the hold's result arrives: nothing is typed; the result is abandoned rewake",
async () => {
const dbl = controlled();
// the fake starts its re-wake when this file exists: after the test saw the hold
const gate = join(tmpdir(), `claudish-rewake-gate-${randomUUID()}`);
const r = await rig(
[
{ say: "A1", rewake: { gateFile: gate, delayMs: 100, quietMs: 3_000, say: "A1-B" } },
{ say: "A2" },
],
{ binding: dbl.binding }
);
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
await r.type("go");
await until(() => dbl.calls.length === 1, "settle 1");
writeFileSync(gate, "");
// The re-wake's records land with no redraw: the screen still shows the idle box,
// and the driver's last poll is older than them. Resolve the instant they exist.
const end = Date.now() + 20_000;
while (!readFileSync(r.transcript, "utf8").includes("A1-B")) {
if (Date.now() > end) throw new Error("timed out waiting for the re-wake's records");
await Bun.sleep(2);
}
dbl.calls[0]?.resolve(inject("HOOK-LATE"));
await until(
() => dbl.calls.length === 2 || r.keylog().includes("HOOK-LATE"),
"the re-woken turn's settle, or the injection typed over it"
);
expect(r.keylog()).toEqual(["go"]);
// Either the result came back (abandoned rewake), or, rarely, the driver's own
// backstop poll saw the records first and ended the hold before it arrived.
if ((dbl.calls[0]?.signal.reason as string | undefined) !== "rewake")
expect(dbl.abandoned).toEqual([{ text: "HOOK-LATE", reason: "rewake" }]);
expect(dbl.delivered).toEqual([]);
expect(dbl.calls[1]?.turn.index).toBe(1);
expect(dbl.calls[1]?.turn.answer).toContain("A1-B");
expect(d.snapshot()).toMatchObject({ callerAdmitted: 1, consecutiveHookTurns: 0 });
} finally {
rmSync(gate, { force: true });
await finish(r);
}
},
T
);
});
/* ───────────────────────────── the session id from requests ───────────────────────────── */
describe.skipIf(!MAGMUX)(
`interactive driver: session from requests ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`,
() => {
test(
"--resume: no id at boot; the first request's id opens the turn at its last human prompt",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1", delayMs: 400 }, { say: "A2" }], {
binding: dbl.binding,
driver: { sessionId: null },
});
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
expect(d.snapshot()).toMatchObject({ phase: "NONE", sessionId: null });
await r.type("resumed prompt");
// Claude Code writes the prompt, THEN sends the request that names the session.
await until(
() =>
existsSync(r.transcript) &&
readFileSync(r.transcript, "utf8").includes("resumed prompt"),
"the prompt record"
);
r.sink.noteSessionId(r.uuid);
expect(d.snapshot().sessionId).toBe(r.uuid);
await until(() => dbl.calls.length === 1, "the turn's settle");
expect(dbl.calls[0]?.turn).toMatchObject({ index: 1, answer: "A1", hookCaused: false });
dbl.calls[0]?.resolve(nothing);
// a late request naming no other session changes nothing; the next turn is followed
r.sink.noteSessionId(r.uuid);
await r.type("next");
await until(() => dbl.calls.length === 2, "the next settle");
expect(dbl.calls[1]?.turn).toMatchObject({ index: 2, answer: "A2" });
} finally {
await finish(r);
}
},
T
);
test(
"an id whose transcript never appears is not followed",
async () => {
const dbl = controlled();
const r = await rig([{ say: "A1" }], {
binding: dbl.binding,
driver: { timings: { tickMs: 100 } },
});
try {
const d = r.driver as InteractiveDriver;
await until(() => d.snapshot().booted, "boot");
r.sink.noteSessionId(randomUUID());
await Bun.sleep(500);
expect(d.snapshot().sessionId).toBe(r.uuid);
await r.type("still followed");
await until(() => dbl.calls.length === 1, "the settle on the original session");
} finally {
await finish(r);
}
},
T
);
}
);
/* ───────────────────────────── real binding: sessionStart, sessionEnd ───────────────────────────── */
describe.skipIf(!MAGMUX)(
`interactive driver: real binding ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`,
() => {
test(
"a sessionStart injection is typed at the first idle; stop() fires sessionEnd and waits for it",
async () => {
let endSeen = null as { state: string; exitCode: number | null } | null;
const { engine, journal } = engineOf(
{
id: "start",
on: { sessionStart: () => [{ type: "injectUserTurn", text: "START-PING" }] },
},
{
id: "end",
on: {
sessionEnd: async (ctx) => {
await Bun.sleep(300);
endSeen = { state: ctx.outcome.state, exitCode: ctx.outcome.exitCode };
return [];
},
},
}
);
const r = await rig([{ say: "S1" }], { startDriver: false });
try {
const d = await r.startDriver({ engine });
await until(() => r.keylog().includes("START-PING"), "the sessionStart injection");
await until(() => d.snapshot().settles === 1, "its turn's settle");
expect(d.snapshot()).toMatchObject({ consecutiveHookTurns: 1, callerAdmitted: 0 });
expect(
journal.some(
(j) =>
j.hookId === "hook:t/start" &&
j.decision === "delivered" &&
j.action === "injectUserTurn"
)
).toBe(true);
const t0 = Date.now();
await d.stop({ state: "COMPLETED", reason: null, exitCode: 0 });
expect(endSeen).toEqual({ state: "COMPLETED", exitCode: 0 });
expect(Date.now() - t0).toBeLessThan(1_500);
} finally {
await finish(r);
}
},
T
);
test(
"stop() waits at most 1.5 s for a sessionEnd hook that never returns",
async () => {
const { engine } = engineOf({
id: "hang",
on: { sessionEnd: () => new Promise(() => {}) },
});
const r = await rig([], { startDriver: false });
try {
const d = await r.startDriver({ engine });
await until(() => d.snapshot().booted, "boot");
const t0 = Date.now();
await d.stop({ state: "COMPLETED", reason: null, exitCode: 0 });
const took = Date.now() - t0;
expect(took).toBeGreaterThanOrEqual(1_000);
expect(took).toBeLessThan(2_500);
} finally {
await finish(r);
}
},
T
);
}
);
/* ───────────────────────────── ambient: the own pane ───────────────────────────── */
describe.skipIf(!MAGMUX)(`ambient: own pane ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`, () => {
test(
"found via list + ancestry: pane 1 of a grid, not 0, in both layouts",
async () => {
const t = makePaneTestEnv();
mkdirSync(t.sockRoot, { recursive: true });
const procs: ChildProcess[] = [];
try {
for (const layout of ["exec", "child-of-shell"] as const) {
const out = join(t.tmp, `probe-${layout}.json`);
const run = `${shq(process.execPath)} ${shq(PROBE)} ${shq(out)}`;
const id = `own${randomBytes(3).toString("hex")}`;
const m = spawn(
MAGMUX as string,
[
"--headless",
"--no-status",
"--id",
id,
"--sock-dir",
t.sockRoot,
"-e",
"sleep 30",
"-e",
// (a) the probe IS the pane process; (b) a shell stays the pane process
layout === "exec" ? `exec ${run}` : `${run}; sleep 1`,
],
{ cwd: t.cwd, env: t.env, stdio: "ignore", detached: true }
);
m.on("error", () => {});
procs.push(m);
await until(() => existsSync(out), `the probe's answer (${layout})`);
const got = JSON.parse(readFileSync(out, "utf8"));
expect(got.pane).toBe(1);
expect(got.listed.panes.find((p: { pane: number }) => p.pane === 0).pid).not.toBe(
got.pid
);
}
} finally {
for (const m of procs)
try {
if (m.pid) process.kill(-m.pid, "SIGKILL");
} catch {
// gone
}
killLeftovers({ sockRoot: t.sockRoot });
t.cleanup();
}
},
T
);
});
/* ───────────────────────────── end to end: claudish -i ───────────────────────────── */
/**
* The hermetic twin of live check 1: the REAL `claudish -i` runs inside a magmux pane,
* so it is in AMBIENT mode (the pane exports `MAGMUX_SOCK`): it mints the session id,
* adds the turn dir, installs the in-process sink, finds its own pane by ancestry and
* starts the driver. Claude Code is the proxied fake; its every turn goes through
* claudish's proxy to the stub upstream. The child's hooks come from `CLAUDISH_CONFIG`:
* `responseEnd` annotates each response (through the in-process sink), and
* `sessionIdle` injects HOOK-PING once, only when that annotation arrived.
*/
const E2E_HOOKS = (endMarker: string) => `import { renameSync, writeFileSync } from "node:fs";
export default [{
apiVersion: 1,
id: "ping",
on: {
responseEnd(ctx) {
return [{ type: "annotateTurn", key: "seen", value: ctx.response.text }];
},
sessionIdle(ctx) {
if (ctx.turn.hookCaused) return [];
if (!ctx.turn.annotations.some((a) => a.key === "seen" && a.value === "STUB-ONE")) return [];
return [{ type: "injectUserTurn", text: "HOOK-PING" }];
},
sessionEnd(ctx) {
// Written whole and renamed into place: the test polls for the file, and a
// plain write is visible empty before its JSON lands.
writeFileSync(${JSON.stringify(`${endMarker}.tmp`)}, JSON.stringify({ session: ctx.session, outcome: ctx.outcome }));
renameSync(${JSON.stringify(`${endMarker}.tmp`)}, ${JSON.stringify(endMarker)});
return [];
},
},
}];
`;
describe.skipIf(!MAGMUX)(`end to end: claudish -i ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`, () => {
let stub: StubUpstream | null = null;
afterAll(() => stub?.stop());
test("ambient claudish -i: a sessionIdle injection fed by a responseEnd annotation becomes the next turn", async () => {
stub = startStubUpstream({
format: "openai-sse",
script: [{ parts: [{ text: "STUB-ONE" }] }, { parts: [{ text: "STUB-TWO" }] }],
});
const t = makePaneTestEnv({ COLUMNS: "160", LINES: "50", CONTRACT_FAKE_MAX_MS: "80000" });
mkdirSync(t.sockRoot, { recursive: true });
const endMarker = join(t.tmp, "session-end.json");
const module = join(t.tmp, "e2e-hooks.js");
writeFileSync(module, E2E_HOOKS(endMarker));
const config = join(t.tmp, "claudish-config.json");
writeFileSync(
config,
JSON.stringify({ ...stubEndpointConfig(stub), hooks: { modules: [module] } }, null, 2)
);
const dump = join(t.tmp, "fake-claude-dump.json");
Object.assign(t.env, {
CLAUDE_PATH: writeFakeClaudeWrapper(t.tmp),
CLAUDISH_CONFIG: config,
FAKE_CLAUDE_PROXY: "1",
FAKE_CLAUDE_DUMP: dump,
FAKE_KEYLOG: join(t.tmp, "keylog.txt"),
});
const id = `e2e${randomBytes(3).toString("hex")}`;
const sock = join(t.sockRoot, `magmux-${id}.sock`);
const cmd = `exec ${shq(process.execPath)} --no-env-file ${shq(INDEX)} -i --model stub@fake-model -y --quiet --no-recovery`;
const m = spawn(
MAGMUX as string,
["--headless", "--no-status", "--id", id, "--sock-dir", t.sockRoot, "-e", cmd],
{ cwd: t.cwd, env: t.env, stdio: "ignore", detached: true }
);
m.on("error", () => {});
const human = await MagmuxClient.connect(sock, { timeoutMs: 10_000 });
const keylog = () => {
const p = t.env.FAKE_KEYLOG as string;
return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean) : [];
};
try {
// Claude Code's argv: the minted id and the turn dir lead, `--settings` ends the list
await until(() => existsSync(dump), "the fake Claude Code's argv dump", 30_000);
const argv = JSON.parse(readFileSync(dump, "utf8")).argv as string[];
expect(argv[0]).toBe("--session-id");
const sid = argv[1] as string;
expect(sid).toMatch(/^[0-9a-f-]{36}$/);
expect(argv[2]).toBe("--add-dir");
expect(argv[4]).toBe("--settings");
// wait for the REPL, then type as the human
await Bun.sleep(1_500);
const sent = await human.request({
type: "send",
pane: 0,
text: "Reply first.",
typed: true,
enter: true,
});
expect(sent.ok).toBe(true);
await until(() => keylog().includes("HOOK-PING"), "the injected turn", 40_000);
const transcript = t.transcriptPathFor(sid);
await until(
() => existsSync(transcript) && readFileSync(transcript, "utf8").includes("STUB-TWO"),
"the injected turn's answer",
30_000
);
const records = readFileSync(transcript, "utf8")
.split("\n")
.filter(Boolean)
.map((l) => JSON.parse(l));
const texts = records.map((r) =>
r.type === "user"
? `user:${typeof r.message?.content === "string" ? r.message.content : ""}`
: r.type === "assistant"
? `assistant:${(r.message?.content ?? []).map((b: { text?: string }) => b.text ?? "").join("")}`
: null
);
const order = texts.filter((x): x is string => x !== null);
expect(order).toEqual([
"user:Reply first.",
"assistant:STUB-ONE",
"user:HOOK-PING",
"assistant:STUB-TWO",
]);
expect(stub.requests.length).toBe(2);
expect(keylog()).toEqual(["Reply first.", "HOOK-PING"]);
// the human quits: sessionEnd runs before claudish exits
await human.request({ type: "send", pane: 0, text: "/exit", typed: true, enter: true });
await until(() => existsSync(endMarker), "sessionEnd", 15_000);
const end = JSON.parse(readFileSync(endMarker, "utf8"));
expect(end.outcome).toEqual({ state: "COMPLETED", reason: null, exitCode: 0 });
expect(end.session).toMatchObject({ kind: "interactive", id: sid, claudeSessionId: sid });
} finally {
human.close();
try {
if (m.pid) process.kill(-m.pid, "SIGKILL");
} catch {
// gone
}
killLeftovers({ sockRoot: t.sockRoot });
t.cleanup();
}
}, 90_000);
});