Skip to content

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

46.2 KB
Raw Blame
/**
 * PaneSession against REAL magmux and the fake interactive child (architecture §12.3).
 * Every test builds its own hermetic env and sockRoot and ends with the no-orphan check:
 * no process whose argv carries the sockRoot or the session id, nothing left in the pane
 * pgid, and no socket, record or launcher dir in the sockRoot.
 */

import { afterAll, describe, expect, test } from "bun:test";
import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import type { SlotState } from "./contract.js";
import {
  type PaneBlock,
  type PaneSession,
  type PaneSessionOptions,
  REPL_STABLE_MS,
  startPaneSession,
} from "./pane-session.js";
import { inputBox, readBoot } from "./screen-classifier.js";
import type { ScreenState } from "./screen-model.js";
import { type ObservedClient, observeClients } from "./test-helpers/client-observer.js";
import {
  MAGMUX,
  NO_MAGMUX_MESSAGE,
  type PaneTestEnv,
  killLeftovers,
  makePaneTestEnv,
  newSessionUuid,
  waitNoOrphans,
} from "./test-helpers/hermetic-env.js";
import type { FinalVerdict, PaneSnapshot, SettledTurn } from "./types.js";

const sha8 = (s: string) => createHash("sha1").update(s).digest("hex").slice(0, 8);

/** A later admission's bound for the tests that wait one out: one magmux send budget. */
const LATER_ADMIT_BOUND_MS = 16_000;

/** Runs not yet finished: a test that throws before `finish` is cleaned up at the end. */
const open = new Set<Run>();
afterAll(async () => {
  for (const r of open) {
    r.unobserve();
    r.s.cancel();
    await r.s.reaped();
    killLeftovers({ sockRoot: r.t.sockRoot, ids: [r.uuid] });
    r.t.cleanup();
  }
});

interface Run {
  s: PaneSession;
  t: PaneTestEnv;
  uuid: string;
  transitions: Array<[SlotState, SlotState]>;
  turns: SettledTurn[];
  blocks: PaneBlock[];
  submits: Array<{ text: string; at: number }>;
  sendLog: SendLog;
  /** Stop handing this run's new magmux clients to its send observer. */
  unobserve: () => void;
}

/** Every `send` the run's magmux clients carried, recorded from the moment each client exists. */
interface SendLog {
  /** Set once `startPaneSession` returns; until then a send's box reads null. */
  session: PaneSession | null;
  /** Sends issued before `start` returned: no test could have attached a trace that early. */
  early: InputSend[];
  /** The live lists `traceInput` handed out. */
  traces: InputSend[][];
}

/** team-like policy: verdict at the first settle; api error → FAILED; question → FAILED blocked */
function teamDecide(turn: SettledTurn): FinalVerdict {
  if (turn.apiError) return { state: "FAILED", reason: "api_error", detail: turn.apiError.text };
  if (turn.delivery.complete === false) return { state: "FAILED", reason: "prompt_not_read" };
  if (!turn.answer.trim()) return { state: "EMPTY", reason: "empty_output" };
  return { state: "COMPLETED" };
}

async function start(
  scenario: string,
  over: Partial<PaneSessionOptions> & { env?: Record<string, string> } = {}
): Promise<Run> {
  const t = makePaneTestEnv({ CONTRACT_FAKE_MAX_MS: "60000", ...over.env });
  t.env.FAKE_SUBMIT_LOG = join(t.tmp, "submits.jsonl");
  const uuid = newSessionUuid();
  const transitions: Array<[SlotState, SlotState]> = [];
  const turns: SettledTurn[] = [];
  const blocks: PaneBlock[] = [];
  const { env: _e, decide, onBlocked, timings, ...rest } = over;
  // A one-shot pane's first gated send can leave from inside `attach()`, before
  // `startPaneSession` returns: observe each client as it is created, not `s.client` later.
  const sendLog: SendLog = { session: null, early: [], traces: [] };
  const unobserve = observeClients(t.sockRoot, recordSends(sendLog));
  const s = await startPaneSession({
    kind: "t",
    label: "01",
    callerFlags: [],
    spawnModel: scenario.startsWith("contract") ? scenario : `fake-${scenario}`,
    cwd: t.cwd,
    sessionUuid: uuid,
    transcriptPath: t.transcriptPathFor(uuid),
    slotEnv: {},
    shape: "one-shot",
    initialPrompt: "Reply with exactly PEAR.",
    readAvailable: true,
    parentEnv: t.env,
    sockRoot: t.sockRoot,
    decide: (turn) => {
      turns.push(turn);
      return decide ? decide(turn) : teamDecide(turn);
    },
    onBlocked: (b) => {
      blocks.push(b);
      return onBlocked ? onBlocked(b) : { state: "FAILED", reason: "blocked", detail: b.text };
    },
    onTransition: (x) => transitions.push([x.from, x.to]),
    timings: {
      replStableMs: 200,
      bootStaticMs: 800,
      corroborationMs: 200,
      ...timings,
    },
    ...rest,
  }).catch((error: unknown) => {
    unobserve();
    throw error;
  });
  sendLog.session = s;
  const run: Run = {
    s,
    t,
    uuid,
    transitions,
    turns,
    blocks,
    submits: [],
    sendLog,
    unobserve,
  };
  open.add(run);
  return run;
}

/** Run to terminal, then reap, and prove nothing is left. */
async function finish(r: Run, ms = 20_000): Promise<PaneSnapshot> {
  try {
    const snap = await Promise.race([
      r.s.terminal,
      Bun.sleep(ms).then(() => {
        throw new Error(`no terminal state in ${ms} ms: ${JSON.stringify(r.s.snapshot())}`);
      }),
    ]);
    return snap;
  } finally {
    open.delete(r);
    r.unobserve();
    r.s.cancel();
    await r.s.reaped();
    const log = r.t.env.FAKE_SUBMIT_LOG as string;
    if (existsSync(log))
      r.submits = readFileSync(log, "utf8")
        .trim()
        .split("\n")
        .filter(Boolean)
        .map((line) => JSON.parse(line));
    const left = await waitNoOrphans({
      sockRoot: r.t.sockRoot,
      ids: [r.uuid],
      pgids: [r.s.snapshot().panePid ?? 0],
    });
    killLeftovers({ sockRoot: r.t.sockRoot, ids: [r.uuid] });
    r.t.cleanup();
    expect(left).toEqual({ processes: [], files: [] });
  }
}

/**
 * End a session the test leaves idle (interactive, AWAITING_INPUT), then reap and prove
 * nothing is left. `finish` alone waits for a terminal state, which an idle interactive
 * fake reaches only at its 20 s safety exit: every such test cost ~20 s of wall time.
 */
async function close(r: Run): Promise<PaneSnapshot> {
  r.s.cancel();
  return finish(r);
}

async function until(
  r: Run,
  pred: (s: PaneSnapshot) => boolean,
  ms = 15_000
): Promise<PaneSnapshot> {
  const end = Date.now() + ms;
  for (;;) {
    const s = r.s.snapshot();
    if (pred(s)) return s;
    if (Date.now() > end) throw new Error(`condition not met in ${ms} ms: ${JSON.stringify(s)}`);
    await Bun.sleep(50);
  }
}

function screenOf(r: Run): ScreenState {
  return screenOfSession(r.s);
}

function screenOfSession(s: PaneSession): ScreenState {
  const capture = s.capture(undefined, { spans: true });
  if (!("lines" in capture)) throw new Error("expected a full capture");
  return {
    ...capture,
    spans: capture.spans ?? [],
    alt: false,
    changedAt: 0,
    aboveBoxChangedAt: 0,
  };
}

type Request = (m: Record<string, unknown>, ms?: number) => Promise<unknown>;
interface InputSend {
  message: Record<string, unknown>;
  box: string | null;
  at: number;
}

/** The client observer for one run: wrap each new client's `request` once, recording sends. */
function recordSends(log: SendLog): (client: ObservedClient) => void {
  const seen = new WeakSet<ObservedClient>();
  return (client) => {
    if (seen.has(client)) return;
    seen.add(client);
    const real = client.request.bind(client);
    client.request = async (message, ms) => {
      if (message.type === "send") {
        const send: InputSend = {
          message: { ...message },
          box: log.session ? (inputBox(screenOfSession(log.session))?.text ?? null) : null,
          at: Date.now(),
        };
        if (!log.session) log.early.push(send);
        for (const trace of log.traces) trace.push(send);
      }
      return real(message, ms);
    };
  };
}

/**
 * Observe actual sends without replacing the gate's decisions: every send from this call
 * on, plus any issued while `start` was still running (a one-shot pane's first gated send).
 */
function traceInput(r: Run): InputSend[] {
  const sends = [...r.sendLog.early];
  r.sendLog.traces.push(sends);
  return sends;
}

const T = 40_000;

describe.skipIf(!MAGMUX)(
  `PaneSession, real magmux + fake child (${MAGMUX ? "" : NO_MAGMUX_MESSAGE})`,
  () => {
    describe("production boot stability", () => {
      test("the production REPL_STABLE_MS is 3000 ms", () => {
        expect(REPL_STABLE_MS).toBe(3000);
      });

      test(
        "no_boot_reset: the gate waits its 3.5 second raw-terminal floor before typing",
        async () => {
          // Explicit undefined removes the helper's short test seam: exercise the production default.
          const r = await start("no_boot_reset", { timings: { replStableMs: undefined } });
          const sends = traceInput(r);
          try {
            await until(r, () => readBoot(screenOf(r)).kind === "repl");
            const firstEmptyBox = Date.now();
            expect(r.s.snapshot().state).toBe("STARTING");
            await r.s.ready;
            const snap = await finish(r);
            expect(snap.state).toBe("COMPLETED");
            // Measure actual typing, not a sleep that can overshoot under concurrent process tests.
            // The screen polling above can observe the first frame up to 50 ms late.
            expect((sends[0]?.at ?? 0) - firstEmptyBox).toBeGreaterThanOrEqual(3350);
            expect(sends[0]?.message.text).toBe("Reply with exactly PEAR.");
            expect(sends[0]?.message).toMatchObject({ typed: true, enter: true });
            expect(sends).toHaveLength(1);
          } finally {
            if (open.has(r)) await close(r);
          }
        },
        T
      );
    });

    describe.concurrent("happy path and delivery", () => {
      test(
        "answer: STARTING → RUNNING → COMPLETED on turn_duration, the typed line's hash, all reaped",
        async () => {
          const r = await start("answer");
          await r.s.ready;
          expect(r.s.snapshot().state).toBe("RUNNING");
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.transitions).toEqual([
            ["STARTING", "RUNNING"],
            ["RUNNING", "COMPLETED"],
          ]);
          expect(r.turns[0]?.answer).toBe(`ANSWER fake-answer ${sha8("Reply with exactly PEAR.")}`);
          expect(r.turns[0]?.settledBy).toBe("turn_duration");
          expect(r.turns[0]?.delivery.mode).toBe("typed");
          expect(snap.turnsCompleted).toBe(1);
          expect(snap.tokensIn).toBeGreaterThan(0);
          expect(snap.claudeCodeVersion).toBe("2.1.290");
        },
        T
      );

      test(
        "a multi-line prompt goes by file; Read coverage complete; the reconstructed hash equals the prompt's",
        async () => {
          const prompt = "First line.\n\tSecond line with a tab.\n! leading bang\nlast";
          const r = await start("answer", { initialPrompt: prompt });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          const turn = r.turns[0] as SettledTurn;
          expect(turn.delivery).toMatchObject({
            mode: "file",
            linesTotal: 4,
            linesRead: 4,
            complete: true,
          });
          expect(turn.answer).toBe(`ANSWER fake-answer ${sha8(prompt)}`);
          expect(snap.toolCalls).toBe(1);
        },
        T
      );

      test(
        "long_line: a 25,000-char line is split with ↩ and joined back losslessly",
        async () => {
          const prompt = `${"word ".repeat(5000)}\nend`;
          const r = await start("long_line", { initialPrompt: prompt });
          await finish(r);
          expect(r.turns[0]?.answer).toBe(`ANSWER fake-long_line ${sha8(prompt)}`);
          expect(r.turns[0]?.delivery.complete).toBe(true);
        },
        T
      );

      test(
        "narrate_then_read: the answer starts after the Read result; ^VERDICT: matches; preamble counted",
        async () => {
          const r = await start("narrate_then_read", {
            initialPrompt: "Review this.\nReply VERDICT: ok",
            decide: (turn) =>
              /^VERDICT:/.test(turn.answer)
                ? { state: "COMPLETED" }
                : { state: "EMPTY", reason: "shape_mismatch" },
          });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.turns[0]?.answer).toBe("VERDICT: ok");
          expect(r.turns[0]?.delivery.preambleBytes).toBeGreaterThan(0);
        },
        T
      );

      test(
        "partial_read / no_read: complete false → the team policy fails prompt_not_read",
        async () => {
          for (const sc of ["partial_read", "no_read"]) {
            const r = await start(sc, { initialPrompt: "a\nb\nc\nd\ne\nf" });
            const snap = await finish(r);
            expect(snap.state).toBe("FAILED");
            expect(snap.reason).toBe("prompt_not_read");
            expect(r.turns[0]?.delivery.complete).toBe(false);
            expect(r.turns[0]?.delivery.linesRead ?? 0).toBeLessThan(6);
          }
        },
        T * 2
      );

      test(
        "menu_eats_enter: magmux resends Enter inside one gated SUBMIT, never retypes",
        async () => {
          const prompt = "Reply with exactly PEAR.";
          const r = await start("menu_eats_enter", { env: { FAKE_GAP_MS_WITNESS: "5000" } });
          const sends = traceInput(r);
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(snap.anomalies).toContain("gate_resent_enter");
          expect(sends.map(({ message }) => message)).toMatchObject([
            { text: prompt, typed: true, enter: true },
          ]);
          expect(sends).toHaveLength(1);
          expect(r.submits.map(({ text }) => text)).toEqual([prompt]);
          expect(r.turns).toHaveLength(1);
          expect(r.turns[0]?.answer).toBe(`ANSWER fake-menu_eats_enter ${sha8(prompt)}`);
          expect(snap.turnsCompleted).toBe(1);
        },
        T
      );

      test(
        "I21: a published leftover draft is cleared before the next gated send",
        async () => {
          const r = await start("answer", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
          });
          await r.s.ready;
          const client = (r.s as unknown as { client: { request: Request } }).client;
          await client.request({
            type: "send",
            pane: 0,
            text: "Different unsent draft",
            typed: true,
            enter: false,
          });
          await until(r, () => r.s.diagnostics().gate?.reason === "box_not_empty");
          const sends = traceInput(r);
          const at = Date.now();
          r.s.send("Reply with exactly PEAR.");
          await until(r, (s) => s.turnsCompleted === 1 && s.state === "AWAITING_INPUT");
          expect(Date.now() - at).toBeLessThan(15_000);
          const snap = await close(r);
          expect(snap.anomalies).not.toContain("gate_busy:box_not_empty");
          expect(sends.map(({ message }) => message)).toMatchObject([
            { keys: ["ctrl-u"], enter: false, noGate: true },
            { text: "Reply with exactly PEAR.", typed: true, enter: true },
          ]);
          expect(sends).toHaveLength(2);
          expect(r.submits.map(({ text }) => text)).toEqual(["Reply with exactly PEAR."]);
        },
        T
      );

      test(
        "I7: enter_ignored_1 is accepted by magmux's resent_enter, with one submitted copy",
        async () => {
          const r = await start("enter_ignored_1", { env: { FAKE_GAP_MS_WITNESS: "5000" } });
          const sends = traceInput(r);
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(snap.anomalies).toContain("gate_resent_enter");
          expect(sends).toHaveLength(1);
          expect(sends[0]?.message).toMatchObject({
            text: "Reply with exactly PEAR.",
            typed: true,
            enter: true,
          });
          expect(r.submits.map(({ text }) => text)).toEqual(["Reply with exactly PEAR."]);
          expect(r.turns[0]?.answer).toBe(
            `ANSWER fake-enter_ignored_1 ${sha8("Reply with exactly PEAR.")}`
          );
        },
        T
      );

      test(
        "immediate_write: a witness written at once is still found (offset taken before delivery)",
        async () => {
          const snap = await finish(await start("immediate_write"));
          expect(snap.state).toBe("COMPLETED");
        },
        T
      );
    });

    describe.concurrent("settle paths", () => {
      test(
        "quiet: path S after the secondary window, with the anomaly",
        async () => {
          const r = await start("quiet", { timings: { secondaryQuietMs: 1000 } });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.turns[0]?.settledBy).toBe("quiet");
          expect(snap.anomalies).toContain("settled_without_turn_duration");
        },
        T
      );

      test(
        "quiet_no_summary: never settles (activity finishing); cancel → CANCELLED",
        async () => {
          const r = await start("quiet_no_summary", { timings: { secondaryQuietMs: 500 } });
          await until(r, (s) => s.activity === "finishing");
          await Bun.sleep(1500);
          expect(r.s.snapshot().state).toBe("RUNNING");
          expect(r.s.cancel()).toEqual({ changed: true, state: "CANCELLED" });
          expect(r.s.cancel()).toEqual({ changed: false, state: "CANCELLED" });
          const snap = await finish(r);
          expect(snap.reason).toBe("cancelled");
          expect(r.turns).toHaveLength(0);
        },
        T
      );

      test(
        "hookless_quiet: turn 2 settles by S once turn 1 proved the session hook-less",
        async () => {
          const r = await start("hookless_quiet", {
            shape: "interactive",
            decide: () => "continue",
            timings: { secondaryQuietMs: 800 },
          });
          await until(r, (s) => s.state === "AWAITING_INPUT" && s.turnsCompleted === 1);
          r.s.send("second turn please");
          await until(r, (s) => s.turnsCompleted === 2);
          expect(r.turns.map((t) => t.settledBy)).toEqual(["turn_duration", "quiet"]);
          await close(r);
        },
        T
      );

      // The secondary window is chosen ABOVE the re-wake gap (2 × the corpus p99, §2.8), so the
      // gap here is shorter than the window under test; a longer gap would open path S.
      test(
        "rewake: no settle before the late turn_duration; both texts in one answer",
        async () => {
          const r = await start("rewake", {
            env: { FAKE_GAP_MS_REWAKE: "2000" },
            timings: { secondaryQuietMs: 4000 },
          });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.turns).toHaveLength(1);
          expect(r.turns[0]?.answer).toContain("LATE second message");
          expect(r.turns[0]?.answer.startsWith("ANSWER")).toBe(true);
        },
        T
      );

      test(
        "slow_stop_hook: nothing settles during the hook (3 × window); P after it",
        async () => {
          const r = await start("slow_stop_hook", {
            env: { FAKE_GAP_MS_HOOK: "3000" },
            timings: { secondaryQuietMs: 1000 },
          });
          await until(r, (s) => s.activity === "finishing");
          const at = Date.now();
          const snap = await finish(r);
          expect(Date.now() - at).toBeGreaterThan(2000);
          expect(snap.state).toBe("COMPLETED");
          expect(r.turns[0]?.settledBy).toBe("turn_duration");
        },
        T
      );

      test(
        "bg_detached: a background shell in its own process group is ended by the reap",
        async () => {
          const pidFile = join("/tmp", `pane-bg-${process.pid}-${Date.now()}`);
          const r = await start("bg_detached", { env: { FAKE_BG_PID_FILE: pidFile } });
          await until(r, () => existsSync(pidFile));
          const pid = Number(readFileSync(pidFile, "utf8"));
          rmSync(pidFile, { force: true });
          try {
            const pgid = Number(
              execFileSync("ps", ["-o", "pgid=", "-p", String(pid)], {
                env: { ...process.env },
                encoding: "utf8",
              })
            );
            expect(pgid).toBe(pid); // its own group: a group signal to the pane never reaches it
            expect((await finish(r)).state).toBe("COMPLETED");
            let alive = true;
            for (let i = 0; i < 20 && alive; i++) {
              try {
                process.kill(pid, 0);
                await Bun.sleep(100);
              } catch {
                alive = false;
              }
            }
            expect(alive).toBe(false);
          } finally {
            try {
              process.kill(pid, "SIGKILL");
            } catch {
              // already ended by the reap
            }
          }
        },
        T
      );

      test(
        "bg_rewake: waits for the background agent (activity background), then settles",
        async () => {
          const r = await start("bg_rewake", { env: { FAKE_GAP_MS_BG: "1500" } });
          await until(r, (s) => s.activity === "background");
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.turns[0]?.answer).toContain("ANSWER");
        },
        T
      );

      test(
        "bg_server: settles at turn_duration with background_shell_open; the reap ends the shell",
        async () => {
          const r = await start("bg_server");
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(
            snap.anomalies.some((a) => a.startsWith("background_shell_open: fake-dev-server"))
          ).toBe(true);
        },
        T
      );

      test(
        "compaction keeps one answer; max_tokens ends in a max_output_tokens API error; null stop settles",
        async () => {
          const c = await start("compaction");
          await finish(c);
          expect(c.turns[0]?.answer).toContain("before compaction");
          expect(c.turns[0]?.answer).toContain("ANSWER");
          const m = await start("max_tokens");
          const ms = await finish(m);
          expect(ms.reason).toBe("api_error");
          expect(m.turns[0]?.apiError?.category).toBe("max_output_tokens");
          const n = await start("null_stop");
          await finish(n);
          expect(n.turns[0]?.stopReason).toBeNull();
        },
        T * 2
      );

      test(
        "api_error → FAILED api_error; refusal continues to the fallback answer",
        async () => {
          const a = await start("api_error");
          const as = await finish(a);
          expect(as.reason).toBe("api_error");
          expect(a.turns[0]?.apiError?.status).toBe(401);
          const f = await start("refusal");
          const fs = await finish(f);
          expect(fs.state).toBe("COMPLETED");
          expect(f.turns).toHaveLength(1);
        },
        T
      );
    });

    describe.concurrent("slash commands", () => {
      test(
        "local commands settle on their stdout (path L) and the prompt queued behind them is answered",
        async () => {
          const r = await start("answer", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
          });
          await r.s.ready;
          expect(r.s.send("/compact").ok).toBe(true);
          expect(r.s.send("/model haiku").ok).toBe(true);
          expect(r.s.send("/color yellow").ok).toBe(true);
          expect(r.s.send("Reply with exactly KIWI.").ok).toBe(true);
          await until(r, (s) => s.turnsCompleted === 4 && s.state === "AWAITING_INPUT");
          expect(r.turns.map((t) => t.settledBy)).toEqual([
            "local_command",
            "local_command",
            "local_command",
            "turn_duration",
          ]);
          expect(r.turns[0]?.answer).toBe("Compacted (ctrl+o to see full summary)");
          expect(r.turns[0]?.delivery.mode).toBe("command");
          expect(r.turns[1]?.answer).toBe("Set model to `haiku`");
          expect(r.turns[2]?.answer).toBe("Session color set to: yellow");
          expect(r.turns[3]?.answer).toBe(`ANSWER fake-answer ${sha8("Reply with exactly KIWI.")}`);
          r.s.cancel();
          await finish(r);
        },
        T
      );

      test(
        "a /compact that outlasts the admission bound stays admitted; the prompt queued behind it is answered",
        async () => {
          // 2.1.291 writes <command-name>/compact only when compaction FINISHES; a real one
          // takes minutes. Compaction here outlasts the admission bound by 5 s.
          const r = await start("answer", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
            admitTimeoutMs: 4000,
            env: { FAKE_GAP_MS_COMPACT: "9000" },
          });
          await r.s.ready;
          expect(r.s.send("/compact").ok).toBe(true);
          expect(r.s.send("Reply with exactly KIWI.").ok).toBe(true);
          await until(r, (s) => s.phase === "RUNNING"); // accepted, not merely admitting
          await Bun.sleep(5000); // past the admission bound, mid-compaction
          expect(r.s.snapshot()).toMatchObject({ state: "RUNNING", pendingInputs: 1 });
          await until(r, (s) => s.turnsCompleted === 2 && s.state === "AWAITING_INPUT", 25_000);
          expect(r.turns.map((t) => t.settledBy)).toEqual(["local_command", "turn_duration"]);
          expect(r.turns[0]?.answer).toBe("Compacted (ctrl+o to see full summary)");
          expect(r.turns[1]?.answer).toBe(`ANSWER fake-answer ${sha8("Reply with exactly KIWI.")}`);
          expect(r.s.snapshot().anomalies.filter((a) => a.startsWith("send_not_accepted"))).toEqual(
            []
          );
          r.s.cancel();
          await finish(r);
        },
        T
      );
    });

    describe.concurrent("command turns with a file", () => {
      test(
        "R3-M3: a command whose expansion never Reads the file → complete null + read_coverage_unverified, not prompt_not_read",
        async () => {
          const r = await start("answer", { initialPrompt: "/pear\nsecond line\nthird line" });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.turns[0]?.delivery).toMatchObject({ mode: "command", complete: null });
          expect(snap.anomalies).toContain("read_coverage_unverified");
        },
        T
      );
    });

    describe.concurrent("panel commands", () => {
      test(
        "/cost opens a panel that writes no record: Esc at once, no turn, the next prompt is not held",
        async () => {
          const r = await start("answer", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
          });
          await r.s.ready;
          const at = Date.now();
          expect(r.s.send("/cost").ok).toBe(true);
          expect(r.s.send("Reply with exactly KIWI.").ok).toBe(true);
          const s = await until(r, (x) => x.turnsCompleted === 1 && x.state === "AWAITING_INPUT");
          // Held behind the panel means the 30 s admission bound (≈ 30 s); 20 s leaves room
          // for full-suite load, which measured 13.3 s for a prompt that was not held.
          expect(Date.now() - at).toBeLessThan(20_000);
          expect(s.anomalies).toContain("panel_dismissed");
          expect(s.anomalies).toContain("panel_command");
          expect(s.anomalies).not.toContain("send_not_accepted");
          expect(r.turns.map((t) => t.answer)).toEqual([
            `ANSWER fake-answer ${sha8("Reply with exactly KIWI.")}`,
          ]);
          r.s.cancel();
          await finish(r);
        },
        T
      );
    });

    describe.concurrent("blocked, interrupts and permission", () => {
      test(
        "ask_user (team): FAILED blocked with the question text, in one net transition",
        async () => {
          const r = await start("ask_user");
          const snap = await finish(r);
          expect(snap.state).toBe("FAILED");
          expect(snap.reason).toBe("blocked");
          expect(snap.detail).toBe("Which fruit do you prefer?");
          expect(r.transitions).toEqual([
            ["STARTING", "RUNNING"],
            ["RUNNING", "FAILED"],
          ]);
        },
        T
      );

      test(
        "ask_user_send (session): AWAITING_INPUT; a send presses Esc → path I settles; the text is turn 2",
        async () => {
          const r = await start("ask_user_send", {
            shape: "interactive",
            onBlocked: () => "wait",
            decide: () => "continue",
          });
          const blocked = await until(
            r,
            (s) => s.state === "AWAITING_INPUT" && s.activity === "AskUserQuestion"
          );
          expect(blocked.phase).toBe("QUESTION");
          expect(r.s.send("Pear, please")).toEqual({ ok: true, queued: 1 });
          await until(r, (s) => s.turnsCompleted === 2);
          expect(r.turns[0]?.stopReason).toBe("interrupted");
          expect(r.turns[0]?.settledBy).toBe("interrupt");
          expect(r.turns[1]?.answer).toBe(`ANSWER fake-ask_user_send ${sha8("Pear, please")}`);
          await close(r);
        },
        T
      );

      test(
        "interrupt_td: the interrupt with a turn_duration settles once",
        async () => {
          const r = await start("interrupt_td", {
            shape: "interactive",
            onBlocked: () => "wait",
            decide: () => "continue",
          });
          await until(r, (s) => s.phase === "QUESTION");
          r.s.send("next");
          await until(r, (s) => s.turnsCompleted === 2);
          expect(r.turns).toHaveLength(2);
          await close(r);
        },
        T
      );

      test(
        "permission: AWAITING_PERMISSION with the tool as activity; cancel ends it",
        async () => {
          const r = await start("permission", {
            shape: "interactive",
            onBlocked: () => "wait",
            decide: () => "continue",
          });
          const s = await until(r, (x) => x.state === "AWAITING_PERMISSION");
          expect(s.activity).toBe("Write");
          expect(r.blocks[0]?.kind).toBe("permission");
          r.s.cancel();
          expect((await finish(r)).state).toBe("CANCELLED");
        },
        T
      );

      test(
        "tool_slow_numbered: numbered prose over a running Bash is NOT a dialog (R3-H1)",
        async () => {
          const r = await start("tool_slow_numbered", { env: { FAKE_GAP_MS_TOOL: "2500" } });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.blocks).toHaveLength(0);
        },
        T
      );
    });

    describe.concurrent("exit paths", () => {
      test(
        "exit_mid_turn → FAILED child_exited with the code",
        async () => {
          const snap = await finish(await start("exit_mid_turn"));
          expect(snap.reason).toBe("child_exited");
          expect(snap.exitCode).toBe(3);
          expect(snap.detail).toContain("code 3");
        },
        T
      );

      test(
        "exit_after_settle / exit_before_td: the verdict comes from the turn, not child_exited",
        async () => {
          const a = await start("exit_after_settle");
          expect((await finish(a)).state).toBe("COMPLETED");
          const b = await start("exit_before_td");
          expect((await finish(b)).state).toBe("COMPLETED");
          expect(b.turns[0]?.settledBy).toBe("exit");
        },
        T
      );

      test(
        "interactive_exit_after_settle: turn_continue then exit_clean → COMPLETED",
        async () => {
          const r = await start("interactive_exit_after_settle", {
            shape: "interactive",
            decide: () => "continue",
          });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(snap.turnsCompleted).toBe(1);
        },
        T
      );

      test(
        "turn2_exit0: turn 2 accepted, exit 0 before answering → FAILED child_exited (C3)",
        async () => {
          const r = await start("turn2_exit0", { shape: "interactive", decide: () => "continue" });
          await until(r, (s) => s.turnsCompleted === 1 && s.state === "AWAITING_INPUT");
          r.s.send("turn two");
          const snap = await finish(r);
          expect(snap.reason).toBe("child_exited");
        },
        T
      );

      test(
        "/exit after a settled turn: the command's own records are no re-wake → COMPLETED via exit_clean",
        async () => {
          const r = await start("answer", { shape: "interactive", decide: () => "continue" });
          await until(r, (s) => s.state === "AWAITING_INPUT" && s.turnsCompleted === 1);
          r.s.send("/exit");
          const snap = await finish(r, 8000);
          expect(snap.state).toBe("COMPLETED");
          expect(snap.reason).toBeNull();
          expect(snap.turnsCompleted).toBe(1);
          // no AWAITING_INPUT → RUNNING after the settle: /exit is not the model waking up
          expect(r.transitions).toEqual([
            ["STARTING", "RUNNING"],
            ["RUNNING", "AWAITING_INPUT"],
            ["AWAITING_INPUT", "COMPLETED"],
          ]);
        },
        T
      );

      test(
        "idle_exit: a promptless session's /exit → COMPLETED via exit_clean",
        async () => {
          const r = await start("answer", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
          });
          await r.s.ready;
          expect(r.s.snapshot().state).toBe("AWAITING_INPUT");
          r.s.send("/exit");
          expect((await finish(r)).state).toBe("COMPLETED");
        },
        T
      );

      test(
        "an unknown --agent → FAILED agent_rejected with the child's own line",
        async () => {
          const r = await start("answer", { callerFlags: ["--agent", "zzz-not-real"] });
          const snap = await finish(r);
          expect(snap.reason).toBe("agent_rejected");
          expect(snap.detail).toContain("--agent 'zzz-not-real' not found.");
        },
        T
      );
    });

    describe.concurrent("boot and admission bounds", () => {
      test(
        "named dialog → first_run_dialog; unnamed choice → boot_blocked (text in detail)",
        async () => {
          const a = await start("dialog_trust");
          const as = await finish(a);
          expect(as.reason).toBe("first_run_dialog");
          expect(as.detail).toContain("Is this a project you created or one you trust");
          const b = await start("dialog_unknown");
          expect((await finish(b)).reason).toBe("boot_blocked");
        },
        T
      );

      test(
        "slow_boot with a 1 s boot bound → boot_timeout",
        async () => {
          const snap = await finish(await start("slow_boot", { bootTimeoutMs: 1000 }));
          expect(snap.reason).toBe("boot_timeout");
        },
        T
      );

      test(
        "ignore_input: the created prompt never accepted → FAILED prompt_not_accepted",
        async () => {
          const snap = await finish(
            await start("ignore_input", { admitTimeoutMs: 2500, timings: { resendAfterMs: 1000 } })
          );
          expect(snap.reason).toBe("prompt_not_accepted");
        },
        T
      );

      test(
        "promptless_first_send_ignored: unconfirmed fails the later admission loudly at its bound, then accepts the next prompt",
        async () => {
          // The production 30 s bound is proven in pane-gated-delivery (DA-1); this test is about
          // what happens when a later admission's bound expires, at a bound with room for one send.
          const r = await start("promptless_first_send_ignored", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
            timings: { admitTimeoutMs: LATER_ADMIT_BOUND_MS },
          });
          await r.s.ready;
          const sends = traceInput(r);
          const at = Date.now();
          r.s.send("first, ignored");
          await until(
            r,
            (s) => s.anomalies.includes("send_not_accepted") && s.state === "AWAITING_INPUT",
            LATER_ADMIT_BOUND_MS + 5_000
          );
          expect(Date.now() - at).toBeGreaterThanOrEqual(LATER_ADMIT_BOUND_MS - 1_000);
          expect(r.s.diagnostics().lastSend?.reason).toBe("unconfirmed");
          expect(r.s.snapshot().anomalies).not.toContain("degraded_mode");
          expect(sends.filter(({ message }) => typeof message.text === "string")).toHaveLength(1);
          expect(r.turns).toHaveLength(0);
          r.s.send("second, answered");
          await until(r, (s) => s.turnsCompleted === 1);
          await close(r);
          expect(r.transitions.slice(0, 3)).toEqual([
            ["STARTING", "AWAITING_INPUT"],
            ["AWAITING_INPUT", "RUNNING"],
            ["RUNNING", "AWAITING_INPUT"],
          ]);
          expect(r.transitions.some(([, to]) => to === "STARTING" || to === "FAILED")).toBe(false);
          expect(r.submits.map(({ text }) => text)).toEqual(["second, answered"]);
        },
        T * 2
      );

      test(
        "timeoutMs → TIMEOUT (the caller's own deadline)",
        async () => {
          const r = await start("contract-fake-model", {
            initialPrompt: "@@HANG@@",
            timeoutMs: 3500,
          });
          expect((await finish(r)).state).toBe("TIMEOUT");
        },
        T
      );
    });

    describe.concurrent("degraded mode", () => {
      test(
        "slow_prompt_hook: degraded entry, then the late witness reverts to the transcript",
        async () => {
          const r = await start("slow_prompt_hook", {
            env: { FAKE_GAP_MS_PROMPT_HOOK: "5000" },
            timings: { degradedEntryMs: 1500, resendAfterMs: 1500 },
          });
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(snap.anomalies).toContain("degraded_mode");
          expect(snap.anomalies).toContain("degraded_reverted");
          expect(r.turns[0]?.captureSource).toBe("transcript");
        },
        T
      );

      test(
        "no_transcript / missing_no_warning: settles from the screen, captureSource screen",
        async () => {
          for (const sc of ["no_transcript", "missing_no_warning"]) {
            const r = await start(sc, {
              timings: { degradedEntryMs: 800, screenSettleQuietMs: 300 },
            });
            const snap = await finish(r);
            expect(snap.state).toBe("COMPLETED");
            expect(r.turns[0]?.captureSource).toBe("screen");
            expect(r.turns[0]?.answer).toContain("ANSWER");
            expect(snap.turnSource).toBe("screen");
          }
        },
        T * 2
      );

      test(
        "screen_api_error: a degraded turn with an error row → FAILED api_error",
        async () => {
          const r = await start("screen_api_error", {
            timings: { degradedEntryMs: 800, screenSettleQuietMs: 300 },
          });
          const snap = await finish(r);
          expect(snap.reason).toBe("api_error");
        },
        T
      );
    });

    describe.concurrent("screen, capture, transport", () => {
      test(
        "capture: seq 0 means no frame; since_seq unchanged; spans on request; final after terminal",
        async () => {
          const r = await start("answer");
          await r.s.ready;
          const c1 = r.s.capture(undefined, { spans: true });
          expect("lines" in c1 && c1.lines.length === 50 && c1.cols === 160).toBe(true);
          expect("spans" in c1 && Array.isArray(c1.spans)).toBe(true);
          const same = r.s.capture((c1 as { seq: number }).seq);
          expect(same).toMatchObject({ unchanged: true });
          await r.s.terminal;
          const fin = r.s.capture();
          expect(fin.final).toBe(true);
          await finish(r);
        },
        T
      );

      test(
        "status_tick: a ticking status row under the box does not hold the settle; seq advances",
        async () => {
          const r = await start("status_tick", {
            shape: "interactive",
            decide: () => "continue",
            initialPrompt: undefined,
          });
          await r.s.ready;
          const s0 = r.s.capture().seq;
          await Bun.sleep(2200);
          expect(r.s.capture().seq).toBeGreaterThan(s0);
          r.s.send("go");
          await until(r, (s) => s.turnsCompleted === 1);
          await close(r);
        },
        T
      );

      test(
        "idle_suggestion: faint ghost text reads as an empty box",
        async () => {
          expect((await finish(await start("idle_suggestion"))).state).toBe("COMPLETED");
        },
        T
      );

      test(
        "subscriber drop: our socket closes while magmux lives → reconnect, no state change, seq continues",
        async () => {
          const r = await start("tool_slow", { env: { FAKE_GAP_MS_TOOL: "4000" } });
          await until(r, (s) => s.activity === "Bash");
          const seq = r.s.capture().seq;
          (r.s as unknown as { client: { close(): void } }).client.close();
          await until(r, (s) => s.anomalies.includes("socket_reconnected") && s.connected);
          expect(r.s.snapshot().state).toBe("RUNNING");
          const snap = await finish(r);
          expect(snap.state).toBe("COMPLETED");
          expect(r.s.capture().seq).toBeGreaterThanOrEqual(seq);
        },
        T
      );

      test(
        "sends while RUNNING queue; the settle-then-admit step reports no AWAITING_INPUT (net onTransition)",
        async () => {
          const r = await start("tool_slow", {
            shape: "interactive",
            decide: () => "continue",
            env: { FAKE_GAP_MS_TOOL: "1500" },
          });
          await until(r, (s) => s.activity === "Bash");
          expect(r.s.send("queued one")).toEqual({ ok: true, queued: 1 });
          expect(r.s.snapshot().pendingInputs).toBe(1);
          await until(r, (s) => s.turnsCompleted === 2, 20_000);
          const toAwaiting = r.transitions.filter(([, to]) => to === "AWAITING_INPUT");
          expect(toAwaiting).toHaveLength(1); // only after turn 2
          await close(r);
        },
        T
      );

      test(
        "a send whose reply is lost after magmux typed it is not typed twice (§2.9 step 4)",
        async () => {
          const r = await start("answer", {
            shape: "interactive",
            initialPrompt: undefined,
            decide: () => "continue",
          });
          await r.s.ready;
          const sends = traceInput(r);
          type Req = (m: Record<string, unknown>, ms?: number) => Promise<unknown>;
          const client = (r.s as unknown as { client: { request: Req } }).client;
          const real = client.request.bind(client);
          let lost = 0;
          client.request = async (m, ms) => {
            const reply = await real(m, ms);
            if (m.type === "send" && typeof m.text === "string" && lost++ === 0)
              return {
                ok: false,
                code: "client_lost",
                error: "connection closed before the reply",
              };
            return reply;
          };
          r.s.send("/model haiku");
          await until(r, (s) => s.turnsCompleted === 1 && s.state === "AWAITING_INPUT");
          expect(r.turns[0]?.answer).toBe("Set model to `haiku`"); // once, not "haiku/model haiku"
          expect(r.s.snapshot().anomalies).toContain("send_reply_lost");
          r.s.cancel();
          await finish(r);
          expect(sends.filter(({ message }) => message.text === "/model haiku")).toHaveLength(2);
          expect(
            sends.filter(
              ({ message }) => Array.isArray(message.keys) && message.keys.includes("ctrl-u")
            )
          ).toHaveLength(1);
          expect(r.submits.map(({ text }) => text)).toEqual(["/model haiku"]);
        },
        T
      );

      test(
        "send validation: /clear and /resume are unsupported; a terminal session refuses",
        async () => {
          const r = await start("answer");
          expect(r.s.send("/clear")).toEqual({ ok: false, reason: "unsupported_command" });
          await r.s.terminal;
          expect(r.s.send("x")).toEqual({ ok: false, reason: "terminal" });
          await finish(r);
        },
        T
      );

      test(
        "env_probe: the pane's env and cwd — no terminal identity, no profile sourced, markers set",
        async () => {
          const probe = join("/tmp", `pane-probe-${process.pid}-${Date.now()}.json`);
          const canary = join("/tmp", `pane-canary-${process.pid}-${Date.now()}`);
          const r0 = makePaneTestEnv();
          r0.cleanup();
          const r = await start("env_probe", {
            env: {
              FAKE_PROBE_FILE: probe,
              TMUX: "/tmp/tmux,1,0",
              TERM_PROGRAM: "iTerm.app",
              CLAUDE_CODE_SESSION_ID: "host",
            },
          });
          mkdirSync(r.t.home, { recursive: true });
          writeFileSync(
            join(r.t.home, ".zprofile"),
            `touch ${canary}\nexport CLAUDE_CONFIG_DIR=/nope\ncd /\n`
          );
          await finish(r);
          const p = JSON.parse(readFileSync(probe, "utf8")) as {
            env: Record<string, string>;
            cwd: string;
          };
          expect(p.env.TMUX).toBeUndefined();
          expect(p.env.TERM_PROGRAM).toBeUndefined();
          expect(p.env.CLAUDE_CODE_SESSION_ID).toBeUndefined();
          expect(p.env.CLAUDISH_PANE_CHILD).toBe("1");
          expect(p.env.CLAUDISH_PANE_ENV).toBeDefined();
          expect(JSON.parse(p.env.CLAUDISH_PANE_ENV as string).SHELL).toBe("/bin/zsh");
          expect(p.env.SHELL.endsWith("/sh-shim")).toBe(true);
          expect(p.env.CLAUDE_CONFIG_DIR).toBe(r.t.configDir);
          expect(p.cwd.endsWith("/cwd")).toBe(true);
          expect(existsSync(canary)).toBe(false);
        },
        T
      );

      test(
        "five sessions at once: unique ids, all reaped",
        async () => {
          const runs = await Promise.all(["a", "b", "c", "d", "e"].map(() => start("answer")));
          expect(new Set(runs.map((r) => r.s.paneId)).size).toBe(5);
          const snaps = await Promise.all(runs.map((r) => finish(r)));
          expect(snaps.every((s) => s.state === "COMPLETED")).toBe(true);
        },
        T
      );
    });
  }
);