Skip to content

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

67.3 KB
Raw Blame
/**
 * The settle hold, `SETTLING` and the turn chain (hook-system architecture §7.3, §7.4,
 * §11.5 H-1 … H-34), against REAL magmux and the fake interactive child in scripted
 * mode (`fake-scripted`, `FAKE_SCRIPT`, `FAKE_KEYLOG`).
 *
 * The binding is a test double whose `settle()` returns a promise the test resolves,
 * except where a row says "real binding" (H-21, H-21b, H-24, the cap and the
 * sessionStart rows), which run `createSessionHookBinding` over a real engine. The
 * owner is the real MCP `SessionManager` (observed through get_output,
 * get_diagnostics and events.jsonl, whose `state` records give the row events) or the real team orchestrator
 * (response-<slot>.md and the slot's status row). Every test ends with the
 * no-orphan check.
 */

import { afterAll, describe, expect, test } from "bun:test";
import { randomUUID } from "node:crypto";
import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { HookEngine } from "../hooks/engine.js";
import type { JournalEntry } from "../hooks/journal.js";
import type { HookDefinition } from "../hooks/public.js";
import { HookRegistry, type UserHookInput } from "../hooks/registry.js";
import {
  type HoldResult,
  type HoldTurnInfo,
  type SessionHookBinding,
  createSessionHookBinding,
} from "../hooks/session/binding.js";
import { SessionManager, sessionEventFor } from "../mcp-session/session-manager.js";
import type { SessionManagerOptions } from "../mcp-session/types.js";
import {
  type TeamHandle,
  type TeamRunOptions,
  cancelTeamRun,
  getStatus,
  setupSession,
  startModels,
} from "../team-orchestrator.js";
import type { CaptureResult, SlotState } from "./contract.js";
import { type PaneSession, type PaneSessionOptions, startPaneSession } from "./pane-session.js";
import {
  MAGMUX,
  NO_MAGMUX_MESSAGE,
  type PaneTestEnv,
  killLeftovers,
  makePaneTestEnv,
  newSessionUuid,
  waitNoOrphans,
} from "./test-helpers/hermetic-env.js";
import type { PaneSnapshot, SettledTurn } from "./types.js";

const T = 60_000;

/* ───────────────────────────── the test double binding ───────────────────────────── */

interface SettleCall {
  turn: HoldTurnInfo;
  signal: AbortSignal;
  resolve(r: HoldResult): void;
  reject(e: unknown): void;
}

function controlled(o: { idle?: boolean; bound?: number } = {}) {
  const calls: SettleCall[] = [];
  const dropped: Array<{ text: string; reason: string }> = [];
  const abandoned: Array<{ text: string; reason: string }> = [];
  const binding: SessionHookBinding = {
    hasIdleWork: () => o.idle ?? true,
    settle: (turn, signal) =>
      new Promise<HoldResult>((resolve, reject) => calls.push({ turn, signal, resolve, reject })),
    holdBoundMs: () => o.bound ?? 30_000,
    fireStart() {},
    fireBlocked() {},
    fireEnd() {},
    noteDropped: (item, reason) => void dropped.push({ text: item.text, reason }),
    abandon: (r, reason) => {
      for (const i of r.injections) abandoned.push({ text: i.text, reason });
    },
  };
  return { binding, calls, dropped, abandoned };
}

const inject = (text: string): HoldResult => ({
  injections: [{ text, hookIds: ["hook:t/x"], source: "sessionIdle" }],
});
const nothing: HoldResult = { injections: [] };

/* ───────────────────────────── engines for the real binding ───────────────────────────── */

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: "mcp",
    journalSink: (e) => journal.push(e),
    warn: () => {},
    drainTelemetryOutbox: false,
  });
  return { engine, journal };
}

const after = <T>(ms: number, v: T) => new Promise<T>((r) => setTimeout(() => r(v), ms));

/**
 * An injected turn's admission bound in the never-accepted rows: enough for ONE gated send
 * of a short line (its budget, ~13 s with a 1 s readiness wait), so the line is typed and
 * magmux answers before the bound drops it.
 */
const HOOK_ADMIT_BOUND_MS = 16_000;

/* ───────────────────────────── helpers ───────────────────────────── */

interface TurnScript {
  say?: string;
  partial?: string;
  ask?: string;
  noWitness?: boolean;
  exitOnSubmit?: number;
  noRead?: boolean;
  apiError?: string;
  delayMs?: number;
  rewake?: {
    delayMs: number;
    say: string;
    workingMs?: number;
    quietMs?: number;
    gateFile?: string;
    clearWithRecords?: boolean;
  };
  exitAfter?: number;
  exitDelayMs?: number;
}

const openEnvs = new Set<PaneTestEnv>();
afterAll(() => {
  for (const t of openEnvs) {
    killLeftovers({ sockRoot: t.sockRoot });
    t.cleanup();
  }
});

function env(script: TurnScript[], extra: Record<string, string> = {}): PaneTestEnv {
  const t = makePaneTestEnv({
    FAKE_SCRIPT: JSON.stringify(script),
    CONTRACT_FAKE_MAX_MS: "60000",
    ...extra,
  });
  t.env.FAKE_KEYLOG = join(t.tmp, "keylog.txt");
  openEnvs.add(t);
  return t;
}

function keylog(t: PaneTestEnv): string[] {
  const p = t.env.FAKE_KEYLOG as string;
  return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean) : [];
}

/** Occurrences of a whole line in the output. */
function lineCount(output: string, line: string): number {
  return output.split("\n").filter((l) => l === line).length;
}

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 TERMINAL: SlotState[] = ["COMPLETED", "FAILED", "CANCELLED", "TIMEOUT", "EMPTY"];

interface Chan {
  t: PaneTestEnv;
  manager: SessionManager;
  id: string;
  /** the row event of every state the session entered, from events.jsonl `state` records */
  rowEvents(): string[];
  info(): ReturnType<SessionManager["getSession"]>;
  output(): string;
  anomalies(): readonly string[];
  terminal(ms?: number): Promise<ReturnType<SessionManager["getSession"]>>;
}

async function channel(o: {
  script: TurnScript[];
  /** null = an interactive (promptless) session; the test sends turn 1 */
  prompt?: string | null;
  binding?: SessionHookBinding | SessionManagerOptions["hookBinding"];
  engine?: HookEngine;
  timeoutSeconds?: number;
  timings?: PaneSessionOptions["timings"];
  magmuxBinary?: string;
  extraEnv?: Record<string, string>;
}): Promise<Chan> {
  const t = env(o.script, o.extraEnv);
  const b = o.binding;
  const manager = new SessionManager({
    maxSessions: 20,
    sessionsDir: join(t.tmp, "sessions"),
    hostPid: 1,
    parentEnv: t.env,
    paneTimings: { replStableMs: 200, corroborationMs: 200, ...o.timings },
    hookEngine: async () => o.engine ?? null,
    ...(b ? { hookBinding: typeof b === "function" ? b : () => b } : {}),
    ...(o.magmuxBinary ? { magmuxBinary: o.magmuxBinary } : {}),
  });
  const prompt = o.prompt === undefined ? "Reply with the first answer." : o.prompt;
  const id = await manager.createSession({
    model: "fake-scripted",
    cwd: t.cwd,
    ...(prompt ? { prompt } : {}),
    ...(o.timeoutSeconds ? { timeoutSeconds: o.timeoutSeconds } : {}),
  });
  return {
    t,
    manager,
    id,
    rowEvents: () =>
      eventsOf({ manager, id } as Chan)
        .filter((e) => e.type === "state")
        .map((e) => sessionEventFor({ state: e.to as SlotState, activity: null }).event),
    info: () => manager.getSession(id),
    output: () => manager.getOutput(id).output,
    anomalies: () => manager.getDiagnostics(id).anomalies,
    async terminal(ms = 30_000) {
      await until(() => TERMINAL.includes(manager.getSession(id).state), "a terminal state", ms);
      return manager.getSession(id);
    },
  };
}

/** Cancel whatever is live, wait for the reap, and prove nothing is left. */
async function done(c: Chan): Promise<void> {
  await c.manager.shutdownAll();
  const left = await waitNoOrphans({ sockRoot: c.t.sockRoot }, 10_000);
  killLeftovers({ sockRoot: c.t.sockRoot });
  openEnvs.delete(c.t);
  c.t.cleanup();
  expect(left).toEqual({ processes: [], files: [] });
}

function eventsOf(c: Chan): Array<Record<string, unknown>> {
  const p = join(c.manager.getDiagnostics(c.id).sessionDir, "events.jsonl");
  return readFileSync(p, "utf8")
    .split("\n")
    .filter(Boolean)
    .map((l) => JSON.parse(l));
}

/** The pane's magmux pid, from its record. */
function magmuxPidOf(c: Chan): number {
  const pane = c.info().pane as string;
  const rec = JSON.parse(readFileSync(join(c.t.sockRoot, "panes", `${pane}.json`), "utf8"));
  return rec.magmuxPid as number;
}

function pidAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
}

/* ───────────────────────────── team ───────────────────────────── */

interface Team {
  t: PaneTestEnv;
  handle: TeamHandle;
  slot: string;
  response(): string;
  state(): SlotState | undefined;
}

async function team(o: {
  script: TurnScript[];
  binding: SessionHookBinding;
  input?: string;
  extra?: TeamRunOptions;
  timings?: PaneSessionOptions["timings"];
}): Promise<Team> {
  const t = env(o.script);
  const path = join(t.tmp, "team");
  setupSession(path, ["fake-scripted"], o.input ?? "Reply with the first answer.");
  const handle = await startModels(path, {
    parentEnv: t.env,
    spawnPlanner: async () => ({ pinned: new Map<string, string>() }),
    paneTimings: { replStableMs: 200, corroborationMs: 200, ...o.timings },
    hookEngine: async () => null,
    hookBinding: () => o.binding,
    ...o.extra,
  });
  const slot = handle.slots["fake-scripted"] as string;
  return {
    t,
    handle,
    slot,
    response: () => {
      const p = join(path, `response-${slot}.md`);
      return existsSync(p) ? readFileSync(p, "utf8") : "";
    },
    state: () => getStatus(path).models[slot]?.state as SlotState | undefined,
  };
}

async function teamDone(x: Team): Promise<void> {
  await cancelTeamRun(x.handle.sessionPath, undefined, x.handle.runId).catch(() => undefined);
  await x.handle.done;
  const left = await waitNoOrphans({ sockRoot: x.t.sockRoot }, 10_000);
  killLeftovers({ sockRoot: x.t.sockRoot });
  openEnvs.delete(x.t);
  x.t.cleanup();
  expect(left).toEqual({ processes: [], files: [] });
}

/* ───────────────────────────── tests ───────────────────────────── */

describe.skipIf(!MAGMUX)(`the settle hold (§11.5) ${MAGMUX ? "" : NO_MAGMUX_MESSAGE}`, () => {
  describe.concurrent("the latch and the terminal paths of a hold (channel, one-shot)", () => {
    test(
      "H-1 latch: settle() once over ≥ 4 ticks; A1 already in get_output; RUNNING, activity hook, phase SETTLING",
      async () => {
        const ctl = controlled();
        const c = await channel({ script: [{ say: "ANS-ONE" }], binding: ctl.binding });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          await Bun.sleep(1_200); // ≥ 4 ticker ticks of 250 ms
          expect(ctl.calls.length).toBe(1);
          expect(ctl.calls[0]?.turn).toMatchObject({
            index: 1,
            answer: "ANS-ONE",
            hookCaused: false,
          });
          const info = c.info();
          expect(info.turnsCompleted).toBe(1);
          expect(info.state).toBe("RUNNING");
          expect(info.activity).toBe("hook");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          const diag = c.manager.getDiagnostics(c.id);
          expect(diag.phase).toBe("SETTLING");
          expect(diag.anomalies.some((a) => a.startsWith("illegal_transition"))).toBe(false);
          expect(c.rowEvents()).not.toContain("waiting_for_input");
          // the row event for RUNNING with activity "hook" is "running", never a tool named "hook"
          expect(sessionEventFor(info).event).toBe("running");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-2 timeout during the hold: TIMEOUT, A1 once; a late injection changes nothing",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-NEVER" }],
          binding: ctl.binding,
          timeoutSeconds: 5,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          const end = await c.terminal(15_000);
          expect(end.state).toBe("TIMEOUT");
          expect(ctl.calls[0]?.signal.aborted).toBe(true);
          expect(ctl.calls[0]?.signal.reason).toBe("terminal");
          ctl.calls[0]?.resolve(inject("HOOK-LATE"));
          await Bun.sleep(600);
          expect(c.info().state).toBe("TIMEOUT");
          expect(keylog(c.t)).not.toContain("HOOK-LATE");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-3 cancel during the hold: CANCELLED, A1 once; a late resolution is ignored",
      async () => {
        const ctl = controlled();
        const c = await channel({ script: [{ say: "ANS-ONE" }], binding: ctl.binding });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          c.manager.cancelSession(c.id);
          expect(c.info().state).toBe("CANCELLED");
          ctl.calls[0]?.resolve(inject("HOOK-LATE"));
          await Bun.sleep(500);
          expect(c.info().state).toBe("CANCELLED");
          expect(keylog(c.t)).not.toContain("HOOK-LATE");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-4 the child exits 0 during the hold (one-shot): COMPLETED on A1 with the exit note, never child_exited",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE", exitAfter: 0, exitDelayMs: 2_000 }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.reason).toBeNull();
          expect(end.detail ?? "").toContain("pane child exited 0");
          expect(ctl.calls[0]?.signal.aborted).toBe(true);
          expect(ctl.calls[0]?.signal.reason).toBe("exit");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-6 a fatal magmux stderr line during the hold: FAILED pane_lost; A1 once (published at record)",
      async () => {
        const ctl = controlled();
        const probe = makePaneTestEnv();
        const wrapper = join(probe.tmp, "magmux-wrapper.sh");
        const trigger = join(probe.tmp, "fatal-now");
        writeFileSync(
          wrapper,
          `#!/bin/bash
REAL=${JSON.stringify(MAGMUX)}
if [ "$1" = "--version" ]; then exec "$REAL" --version; fi
"$REAL" "$@" &
child=$!
trap 'kill -TERM $child 2>/dev/null; wait $child; exit 143' TERM
while kill -0 $child 2>/dev/null; do
  if [ -f "$H6_TRIGGER" ]; then rm -f "$H6_TRIGGER"; echo "magmux: socket lost (test)" >&2; fi
  sleep 0.05
done
wait $child
`
        );
        chmodSync(wrapper, 0o755);
        const c = await channel({
          script: [{ say: "ANS-ONE" }],
          binding: ctl.binding,
          magmuxBinary: wrapper,
          extraEnv: { H6_TRIGGER: trigger },
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          writeFileSync(trigger, "1");
          const end = await c.terminal();
          expect(end.state).toBe("FAILED");
          expect(end.reason).toBe("pane_lost");
          expect(end.detail ?? "").toContain("magmux: socket lost");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
          probe.cleanup();
        }
      },
      T
    );

    test(
      "H-7 timeout while a chain turn runs: TIMEOUT; get_output holds A1 then A2-part, each once",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { partial: "ANS-TWO-PART" }],
          binding: ctl.binding,
          timeoutSeconds: 6,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          const end = await c.terminal(15_000);
          expect(end.state).toBe("TIMEOUT");
          const out = c.output();
          expect(lineCount(out, "ANS-ONE")).toBe(1);
          expect(lineCount(out, "ANS-TWO-PART")).toBe(1);
          expect(out.indexOf("ANS-ONE")).toBeLessThan(out.indexOf("ANS-TWO-PART"));
          expect(keylog(c.t)).toContain("HOOK-PING");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-8 timeout in the second hold: TIMEOUT; A1 and A2 each once, in order",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }],
          binding: ctl.binding,
          timeoutSeconds: 6,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          await until(() => ctl.calls.length === 2, "settle() 2");
          const end = await c.terminal(15_000);
          expect(end.state).toBe("TIMEOUT");
          const out = c.output();
          expect(lineCount(out, "ANS-ONE")).toBe(1);
          expect(lineCount(out, "ANS-TWO")).toBe(1);
          expect(out.indexOf("ANS-ONE")).toBeLessThan(out.indexOf("ANS-TWO"));
          expect(ctl.calls[1]?.turn).toMatchObject({ index: 2, hookCaused: true });
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("team slots: chains, verdicts, terminal paths", () => {
    test(
      "H-9 team cancelled while chain turn 3 runs: response is A1\\n\\nA2\\n\\nA3-part, outputSize its byte length",
      async () => {
        const ctl = controlled();
        const x = await team({
          script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }, { partial: "ANS-3-PART" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-ONE"));
          await until(() => ctl.calls.length === 2, "settle() 2");
          ctl.calls[1]?.resolve(inject("HOOK-TWO"));
          const transcript = getStatus(x.handle.sessionPath).models[x.slot]
            ?.transcriptPath as string;
          await until(
            () => existsSync(transcript) && readFileSync(transcript, "utf8").includes("ANS-3-PART"),
            "the partial answer of turn 3"
          );
          await Bun.sleep(600); // let the follower read it
          await cancelTeamRun(x.handle.sessionPath, undefined, x.handle.runId);
          await until(() => x.state() === "CANCELLED", "CANCELLED");
          const want = "ANS-ONE\n\nANS-TWO\n\nANS-3-PART";
          expect(x.response()).toBe(want);
          expect(getStatus(x.handle.sessionPath).models[x.slot]?.outputSize).toBe(
            Buffer.byteLength(want, "utf8")
          );
        } finally {
          await teamDone(x);
        }
      },
      T
    );

    test(
      "H-10 team cancelled in the second hold: response is A1\\n\\nA2",
      async () => {
        const ctl = controlled();
        const x = await team({
          script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-ONE"));
          await until(() => ctl.calls.length === 2, "settle() 2");
          // the chain so far is already on disk at record, before any verdict
          expect(x.response()).toBe("ANS-ONE\n\nANS-TWO");
          await cancelTeamRun(x.handle.sessionPath, undefined, x.handle.runId);
          await until(() => x.state() === "CANCELLED", "CANCELLED");
          expect(x.response()).toBe("ANS-ONE\n\nANS-TWO");
        } finally {
          await teamDone(x);
        }
      },
      T
    );

    for (const [pattern, state] of [
      ["^VOTE", "COMPLETED"],
      ["^NOPE", "EMPTY"],
    ] as const) {
      test(
        `H-11 require_pattern ${pattern} on a chain: one verdict, response A1\\n\\nA2, ${state}`,
        async () => {
          const ctl = controlled();
          const x = await team({
            script: [{ say: "thinking about it" }, { say: "VOTE: yes" }],
            binding: ctl.binding,
            extra: { requirePattern: pattern },
          });
          try {
            await until(() => ctl.calls.length === 1, "settle() 1");
            ctl.calls[0]?.resolve(inject("HOOK-PING"));
            await until(() => ctl.calls.length === 2, "settle() 2");
            ctl.calls[1]?.resolve(nothing);
            const status = await x.handle.done;
            expect(x.response()).toBe("thinking about it\n\nVOTE: yes");
            expect(status.models[x.slot]?.state).toBe(state);
            if (state === "EMPTY")
              expect(status.models[x.slot]?.error?.reason).toBe("shape_mismatch");
          } finally {
            await teamDone(x);
          }
        },
        T
      );
    }

    test(
      "H-12 team blocked mid-chain: FAILED blocked; response is A1\\n\\nB2",
      async () => {
        const ctl = controlled();
        const x = await team({
          script: [{ say: "ANS-ONE" }, { ask: "ANS-B2" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          const status = await x.handle.done;
          expect(status.models[x.slot]?.state).toBe("FAILED");
          expect(status.models[x.slot]?.error?.reason).toBe("blocked");
          expect(x.response()).toBe("ANS-ONE\n\nANS-B2");
        } finally {
          await teamDone(x);
        }
      },
      T
    );

    test(
      "H-14 team: an injected turn never accepted → slot COMPLETED, response A1, nothing left RUNNING",
      async () => {
        const ctl = controlled();
        const x = await team({
          script: [{ say: "ANS-ONE" }, { noWitness: true }],
          binding: ctl.binding,
          // room for one gated send; magmux answers `unconfirmed`, the bound drops the item
          timings: { admitTimeoutMs: HOOK_ADMIT_BOUND_MS },
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          const status = await x.handle.done;
          expect(status.models[x.slot]?.state).toBe("COMPLETED");
          expect(x.response()).toBe("ANS-ONE");
          expect(ctl.dropped).toEqual([{ text: "HOOK-PING", reason: "send_not_accepted" }]);
          for (const m of Object.values(getStatus(x.handle.sessionPath).models))
            expect(["RUNNING", "AWAITING_INPUT"]).not.toContain(m.state);
          expect(keylog(x.t)).toContain("HOOK-PING");
        } finally {
          await teamDone(x);
        }
      },
      T
    );

    test(
      "H-32 team variant: the child exits 0 during an injected admission → slot COMPLETED, response A1",
      async () => {
        const ctl = controlled();
        const x = await team({
          script: [{ say: "ANS-ONE" }, { exitOnSubmit: 0 }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          const status = await x.handle.done;
          expect(status.models[x.slot]?.state).toBe("COMPLETED");
          expect(x.response()).toBe("ANS-ONE");
        } finally {
          await teamDone(x);
        }
      },
      T
    );
  });

  describe.concurrent("injected turns never accepted, and caller input during a hold", () => {
    test(
      "H-13 one-shot: no witness → hook_injection_dropped:send_not_accepted, COMPLETED on A1, never AWAITING_INPUT",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { noWitness: true }],
          binding: ctl.binding,
          // room for one gated send; magmux answers `unconfirmed`, the bound drops the item
          timings: { admitTimeoutMs: HOOK_ADMIT_BOUND_MS },
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(c.anomalies()).toContain("hook_injection_dropped:send_not_accepted");
          expect(c.rowEvents()).not.toContain("waiting_for_input");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          expect(ctl.dropped).toEqual([{ text: "HOOK-PING", reason: "send_not_accepted" }]);
          // typed and submitted, never accepted: not dropped before a send was made
          expect(keylog(c.t)).toContain("HOOK-PING");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-15 interactive: no witness → AWAITING_INPUT (today's admit_abandoned), the anomaly, A1 once",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { noWitness: true }],
          binding: ctl.binding,
          prompt: null,
          // room for one gated send; magmux answers `unconfirmed`, the bound drops the item
          timings: { admitTimeoutMs: HOOK_ADMIT_BOUND_MS },
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(() => ctl.calls.length === 1, "settle()");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          await until(
            () => c.anomalies().includes("hook_injection_dropped:send_not_accepted"),
            "the anomaly"
          );
          await until(() => c.info().state === "AWAITING_INPUT", "AWAITING_INPUT");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          expect(keylog(c.t)).toContain("HOOK-PING");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-16 send_input during a hold: the hold ends in that step (caller), CALLER runs, a late HOOK never",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-CALLER" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          const r = c.manager.sendInput(c.id, "CALLER");
          // admitted in this very step, so nothing is left queued (as for any send whose own
          // step settles a turn, session-manager.test G-row); see the P6 deviation note
          expect(r).toEqual({ success: true, queued: 0 });
          expect(ctl.calls[0]?.signal.aborted).toBe(true);
          expect(ctl.calls[0]?.signal.reason).toBe("caller");
          expect(c.manager.getDiagnostics(c.id).phase).toBe("ADMITTING");
          ctl.calls[0]?.resolve(inject("HOOK"));
          await until(() => c.info().turnsCompleted === 2, "turn 2");
          await until(() => ctl.calls.length === 2, "the second hold");
          ctl.calls[1]?.resolve(nothing);
          await until(() => c.info().state === "AWAITING_INPUT", "AWAITING_INPUT");
          expect(keylog(c.t)).toContain("CALLER");
          expect(keylog(c.t)).not.toContain("HOOK");
          expect(c.info().shape).toBe("interactive");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          expect(lineCount(c.output(), "ANS-CALLER")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-17 a hold that never resolves (bound 30 s) does not delay the caller: CALLER admitted at once, no watchdog",
      async () => {
        const ctl = controlled({ bound: 30_000 });
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-CALLER" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          const t0 = Date.now();
          c.manager.sendInput(c.id, "CALLER");
          await until(() => keylog(c.t).includes("CALLER"), "CALLER typed", 2_000);
          expect(Date.now() - t0).toBeLessThan(1_500);
          expect(c.anomalies()).not.toContain("hook_hold_watchdog");
          expect(TERMINAL).not.toContain(c.info().state);
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("the chain head's prompt-read result", () => {
    const filePrompt = "Line one of the task.\nLine two of the task.";

    test(
      "H-18 head delivered as a file and not read: FAILED prompt_not_read; get_output holds A1 and A2",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ noRead: true, say: "ANS-ONE" }, { say: "ANS-TWO" }],
          binding: ctl.binding,
          prompt: filePrompt,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          await until(() => ctl.calls.length === 2, "settle() 2");
          ctl.calls[1]?.resolve(nothing);
          const end = await c.terminal();
          expect(end.state).toBe("FAILED");
          expect(end.reason).toBe("prompt_not_read");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          expect(lineCount(c.output(), "ANS-TWO")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-19 head read in full: COMPLETED",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }],
          binding: ctl.binding,
          prompt: filePrompt,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          await until(() => ctl.calls.length === 2, "settle() 2");
          ctl.calls[1]?.resolve(nothing);
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          // no wait opened between chain turns
          expect(c.rowEvents()).not.toContain("waiting_for_input");
          const waits = join(c.manager.getDiagnostics(c.id).sessionDir, "waits.jsonl");
          expect(existsSync(waits) ? readFileSync(waits, "utf8") : "").toBe("");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-20 a hook turn delivered as a file and not read: COMPLETED; anomaly hook_injection_not_read",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { noRead: true, say: "ANS-TWO" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("A hook turn\nthat goes as a file."));
          await until(() => ctl.calls.length === 2, "settle() 2");
          ctl.calls[1]?.resolve(nothing);
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(c.anomalies()).toContain("hook_injection_not_read");
          expect(c.anomalies()).not.toContain("prompt_not_read");
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("sessionStart and the hold bound (real binding)", () => {
    test(
      "H-21 a sessionStart injection still running at the first settle holds it: turn 2 runs LATE; one verdict",
      async () => {
        const { engine } = engineOf({
          id: "late",
          on: { sessionStart: () => after(2_000, [{ type: "injectUserTurn", text: "LATE" }]) },
        });
        const c = await channel({ script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }], engine });
        try {
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.turnsCompleted).toBe(2);
          expect(keylog(c.t)).toContain("LATE");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          expect(lineCount(c.output(), "ANS-TWO")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-21 control: the hook returns after its timeout → COMPLETED after turn 1, journal timeout, no turn 2",
      async () => {
        const { engine, journal } = engineOf({
          id: "late",
          timeoutMs: 800,
          on: { sessionStart: () => after(2_000, [{ type: "injectUserTurn", text: "LATE" }]) },
        });
        const c = await channel({ script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }], engine });
        try {
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.turnsCompleted).toBe(1);
          expect(keylog(c.t)).not.toContain("LATE");
          expect(journal.some((j) => j.hookId === "hook:t/late" && j.decision === "timeout")).toBe(
            true
          );
        } finally {
          await done(c);
        }
      },
      T
    );

    for (const [delay, late] of [
      [2_500, true],
      [4_500, false],
    ] as const) {
      test(
        `H-21b sessionStart (timeout 4 s) returns at ${delay} ms, inbox bound 200 ms: no watchdog; ${late ? "turn 2 runs LATE" : "COMPLETED after turn 1"}`,
        async () => {
          const { engine, journal } = engineOf({
            id: "late",
            timeoutMs: 4_000,
            on: { sessionStart: () => after(delay, [{ type: "injectUserTurn", text: "LATE" }]) },
          });
          const t0 = Date.now();
          const c = await channel({
            script: [{ say: "ANS-ONE" }, { say: "ANS-TWO" }],
            engine,
            binding: ({ session, inboxPath }) =>
              createSessionHookBinding(engine, session, inboxPath, { inboxBoundMs: 200 }),
          });
          try {
            const end = await c.terminal();
            expect(end.state).toBe("COMPLETED");
            expect(c.anomalies()).not.toContain("hook_hold_watchdog");
            if (late) {
              expect(end.turnsCompleted).toBe(2);
              expect(keylog(c.t)).toContain("LATE");
              expect(lineCount(c.output(), "ANS-TWO")).toBe(1);
            } else {
              expect(end.turnsCompleted).toBe(1);
              expect(keylog(c.t)).not.toContain("LATE");
              expect(journal.some((j) => j.decision === "timeout")).toBe(true);
              expect(Date.now() - t0).toBeGreaterThanOrEqual(3_500);
            }
            expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          } finally {
            await done(c);
          }
        },
        T
      );
    }

    test(
      "a sessionStart injection that returns before turn 1 settles is delivered after turn 1 (callerSeq survives)",
      async () => {
        const { engine } = engineOf({
          id: "start",
          on: { sessionStart: () => [{ type: "injectUserTurn", text: "EARLY" }] },
        });
        const c = await channel({
          script: [{ say: "ANS-ONE", delayMs: 600 }, { say: "ANS-TWO" }],
          engine,
        });
        try {
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.turnsCompleted).toBe(2);
          const typed = keylog(c.t);
          expect(typed.indexOf("EARLY")).toBeGreaterThan(0); // after the initial prompt
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "cap: an idle hook that always injects gets 3 hook-caused turns, then dropped capped; one verdict",
      async () => {
        let n = 0;
        const { engine } = engineOf({
          id: "more",
          on: { sessionIdle: () => [{ type: "injectUserTurn", text: `MORE-${++n}` }] },
        });
        const c = await channel({
          script: [
            { say: "ANS-1" },
            { say: "ANS-2" },
            { say: "ANS-3" },
            { say: "ANS-4" },
            { say: "ANS-5" },
          ],
          engine,
        });
        try {
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.turnsCompleted).toBe(4);
          expect(keylog(c.t).filter((l) => l.startsWith("MORE-"))).toEqual([
            "MORE-1",
            "MORE-2",
            "MORE-3",
          ]);
          expect(c.anomalies()).toContain("hook_injection_dropped:capped");
          expect(c.rowEvents()).not.toContain("waiting_for_input");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "a hook item queued during a QUESTION waits, and no Esc is ever sent for it",
      async () => {
        const { engine } = engineOf({
          id: "start",
          on: { sessionStart: () => after(800, [{ type: "injectUserTurn", text: "WAITING" }]) },
        });
        const c = await channel({ script: [{ ask: "" }], engine });
        try {
          await until(() => c.manager.getDiagnostics(c.id).phase === "QUESTION", "QUESTION");
          await until(
            () => c.manager.getDiagnostics(c.id).pendingHookInputs === 1,
            "the queued hook item"
          );
          await Bun.sleep(1_200);
          expect(c.manager.getDiagnostics(c.id).phase).toBe("QUESTION");
          expect(keylog(c.t)).not.toContain("<ESC>");
          expect(keylog(c.t)).not.toContain("WAITING");
          expect(c.manager.getDiagnostics(c.id).pendingInputs).toBe(0);
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("errors, the watchdog, re-wake", () => {
    test(
      "H-22 settle() rejects: concluded with no injection; hook_hold_error; COMPLETED; A1 once",
      async () => {
        const ctl = controlled();
        const c = await channel({ script: [{ say: "ANS-ONE" }], binding: ctl.binding });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          ctl.calls[0]?.reject(new Error("binding broke"));
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(c.anomalies()).toContain("hook_hold_error");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-23 settle() hangs, bound 300 ms: concluded at ~300 ms; hook_hold_watchdog; a later resolve changes nothing",
      async () => {
        const ctl = controlled({ bound: 300 });
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-X" }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          const t0 = Date.now();
          const end = await c.terminal();
          // The anomaly below names the watchdog as the cause; this bound only separates the
          // 300 ms watchdog (plus the turn's own finish, 1074 ms on a loaded CI runner) from a
          // hold left to the 30 s default.
          expect(Date.now() - t0).toBeLessThan(2_000);
          expect(end.state).toBe("COMPLETED");
          expect(c.anomalies()).toContain("hook_hold_watchdog");
          expect(ctl.calls[0]?.signal.reason).toBe("watchdog");
          ctl.calls[0]?.resolve(inject("HOOK-LATE"));
          await Bun.sleep(500);
          expect(keylog(c.t)).not.toContain("HOOK-LATE");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-24 re-wake during a hold (real binding): S dropped, the drained proxy P is delivered next; A1 and A1b once",
      async () => {
        let idleCalls = 0;
        let firstSignal: AbortSignal | null = null;
        const { engine } = engineOf({
          id: "idle",
          on: {
            sessionIdle: (ctx) => {
              idleCalls++;
              if (idleCalls === 1) {
                firstSignal = ctx.signal;
                return new Promise((r) =>
                  ctx.signal.addEventListener("abort", () =>
                    r([{ type: "injectUserTurn", text: "S" }])
                  )
                );
              }
              return [];
            },
          },
        });
        const c = await channel({
          script: [
            { say: "ANS-ONE", rewake: { delayMs: 1_500, say: "ANS-ONE-B" } },
            { say: "ANS-P" },
          ],
          engine,
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          const inboxPath = join(c.manager.getDiagnostics(c.id).sessionDir, "hook-inbox.jsonl");
          writeFileSync(
            inboxPath,
            [
              { v: 1, kind: "stop", req: "r1" },
              { v: 1, kind: "inject", req: "r1", hookId: "hook:c/p", text: "INJECTED-P", at: "x" },
              { v: 1, kind: "end", req: "r1" },
            ]
              .map((l) => `${JSON.stringify(l)}\n`)
              .join("")
          );
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(
            () => keylog(c.t).includes("INJECTED-P"),
            "P delivered as the next turn",
            25_000
          );
          expect((firstSignal as AbortSignal | null)?.reason).toBe("rewake");
          await until(
            () => c.info().turnsCompleted === 2 && c.info().state === "AWAITING_INPUT",
            "turn 2"
          );
          expect(keylog(c.t)).not.toContain("S");
          const out = c.output();
          expect(lineCount(out, "ANS-ONE")).toBe(1);
          expect(lineCount(out, "ANS-ONE-B")).toBe(1);
          expect(lineCount(out, "ANS-P")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("the exit paths of a hold (M-1)", () => {
    for (const code of [0, 1]) {
      test(
        `H-5 interactive, the child exits ${code} during the hold: ${code === 0 ? "COMPLETED through exit_clean" : "FAILED child_exited"}; A1 once`,
        async () => {
          const ctl = controlled();
          const c = await channel({
            script: [{ say: "ANS-ONE", exitAfter: code, exitDelayMs: 2_000 }],
            binding: ctl.binding,
            prompt: null,
          });
          try {
            await until(() => c.info().state === "AWAITING_INPUT", "boot");
            c.manager.sendInput(c.id, "Reply with the first answer.");
            await until(() => ctl.calls.length === 1, "settle()");
            const end = await c.terminal();
            if (code === 0) {
              expect(end.state).toBe("COMPLETED");
            } else {
              expect(end.state).toBe("FAILED");
              expect(end.reason).toBe("child_exited");
            }
            expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          } finally {
            await done(c);
          }
        },
        T
      );
    }

    test(
      "H-29 magmux killed during the hold (one-shot): COMPLETED on A1, detail 'magmux exited', signal reason exit",
      async () => {
        const ctl = controlled();
        const c = await channel({ script: [{ say: "ANS-ONE" }], binding: ctl.binding });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          process.kill(magmuxPidOf(c), "SIGKILL");
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.detail ?? "").toContain("magmux exited");
          expect(ctl.calls[0]?.signal.reason).toBe("exit");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-30 magmux killed during the hold (interactive): FAILED pane_lost with today's 'magmux exited' detail; A1 once",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }],
          binding: ctl.binding,
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(() => ctl.calls.length === 1, "settle()");
          process.kill(magmuxPidOf(c), "SIGKILL");
          const end = await c.terminal();
          expect(end.state).toBe("FAILED");
          expect(end.reason).toBe("pane_lost");
          expect(end.detail ?? "").toContain("magmux exited");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-31 the hold ends inside the exit-capture window: dropped pane_exited, nothing typed, COMPLETED with the exit note",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE", exitAfter: 0, exitDelayMs: 2_000 }],
          binding: ctl.binding,
          timings: { exitCaptureDelayMs: 500 },
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          const pid = c.info().panePid as number;
          await until(() => !pidAlive(pid), "the child's exit", 10_000);
          await Bun.sleep(100);
          ctl.calls[0]?.resolve(inject("HOOK-X"));
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.detail ?? "").toContain("pane child exited 0");
          expect(c.anomalies()).toContain("hook_injection_dropped:pane_exited");
          expect(keylog(c.t)).not.toContain("HOOK-X");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-32 one-shot: the child exits 0 during an injected admission → send_not_accepted; COMPLETED on A1 with the exit note",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { exitOnSubmit: 0 }],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "settle()");
          ctl.calls[0]?.resolve(inject("HOOK-PING"));
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          expect(end.detail ?? "").toContain("pane child exited 0");
          expect(c.anomalies()).toContain("hook_injection_dropped:send_not_accepted");
          expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
        } finally {
          await done(c);
        }
      },
      T
    );

    for (const code of [0, 1]) {
      test(
        `H-33 interactive: the child exits ${code} during an injected admission → the anomaly; ${code === 0 ? "COMPLETED (exit_clean)" : "FAILED child_exited"}`,
        async () => {
          const ctl = controlled();
          const c = await channel({
            script: [{ say: "ANS-ONE" }, { exitOnSubmit: code }],
            binding: ctl.binding,
            prompt: null,
          });
          try {
            await until(() => c.info().state === "AWAITING_INPUT", "boot");
            c.manager.sendInput(c.id, "Reply with the first answer.");
            await until(() => ctl.calls.length === 1, "settle()");
            ctl.calls[0]?.resolve(inject("HOOK-PING"));
            const end = await c.terminal();
            expect(c.anomalies()).toContain("hook_injection_dropped:send_not_accepted");
            if (code === 0) expect(end.state).toBe("COMPLETED");
            else {
              expect(end.state).toBe("FAILED");
              expect(end.reason).toBe("child_exited");
            }
            expect(lineCount(c.output(), "ANS-ONE")).toBe(1);
          } finally {
            await done(c);
          }
        },
        T
      );
    }

    test(
      "H-34 interactive: an unread hook-turn file is hook_injection_not_read, never prompt_not_read",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { noRead: true, say: "ANS-TWO" }],
          binding: ctl.binding,
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(() => ctl.calls.length === 1, "settle() 1");
          ctl.calls[0]?.resolve(inject("A hook turn\nthat goes as a file."));
          await until(() => ctl.calls.length === 2, "settle() 2");
          ctl.calls[1]?.resolve(nothing);
          await until(
            () => c.info().state === "AWAITING_INPUT" && c.info().turnsCompleted === 2,
            "idle"
          );
          await Bun.sleep(400);
          expect(c.anomalies()).toContain("hook_injection_not_read");
          const keys = eventsOf(c)
            .filter((e) => e.type === "anomaly")
            .map((e) => e.key);
          expect(keys).not.toContain("prompt_not_read");
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "H-34 control: a caller send_input delivered as a file and not read → prompt_not_read as today",
      async () => {
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { noRead: true, say: "ANS-TWO" }],
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(
            () => c.info().turnsCompleted === 1 && c.info().state === "AWAITING_INPUT",
            "turn 1"
          );
          c.manager.sendInput(c.id, "A caller turn\nthat goes as a file.");
          await until(
            () => c.info().turnsCompleted === 2 && c.info().state === "AWAITING_INPUT",
            "turn 2"
          );
          await Bun.sleep(400);
          const keys = eventsOf(c)
            .filter((e) => e.type === "anomaly")
            .map((e) => e.key);
          expect(keys).toContain("prompt_not_read");
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  /* ───────────────────────── PaneSession directly (snapshot, no-hold, no binding) ───────────────────────── */

  describe.concurrent(
    "PaneSession: the snapshot during a hold, the no-hold paths, no binding",
    () => {
      interface Direct {
        s: PaneSession;
        t: PaneTestEnv;
        uuid: string;
        transitions: Array<[SlotState, SlotState]>;
        recorded: SettledTurn[];
        decided: SettledTurn[];
      }

      async function direct(o: {
        script: TurnScript[];
        hooks?: SessionHookBinding;
        exitCaptureDelayMs?: number;
      }): Promise<Direct> {
        const t = env(o.script);
        const uuid = newSessionUuid();
        const transitions: Array<[SlotState, SlotState]> = [];
        const recorded: SettledTurn[] = [];
        const decided: SettledTurn[] = [];
        const s = await startPaneSession({
          kind: "t",
          label: "01",
          callerFlags: [],
          spawnModel: "fake-scripted",
          cwd: t.cwd,
          sessionUuid: uuid,
          transcriptPath: t.transcriptPathFor(uuid),
          slotEnv: {},
          shape: "one-shot",
          initialPrompt: "Reply with the first answer.",
          readAvailable: true,
          parentEnv: t.env,
          sockRoot: t.sockRoot,
          decide: (turn) => {
            decided.push(turn);
            return { state: "COMPLETED" };
          },
          onBlocked: () => ({ state: "FAILED", reason: "blocked" }),
          onTransition: (x) => void transitions.push([x.from, x.to]),
          onTurnRecorded: (turn) => void recorded.push(turn),
          timings: {
            replStableMs: 200,
            corroborationMs: 200,
            ...(o.exitCaptureDelayMs ? { exitCaptureDelayMs: o.exitCaptureDelayMs } : {}),
          },
          ...(o.hooks ? { hooks: o.hooks } : {}),
        });
        return { s, t, uuid, transitions, recorded, decided };
      }

      async function directDone(d: Direct): Promise<PaneSnapshot> {
        d.s.cancel();
        await d.s.reaped();
        const left = await waitNoOrphans({ sockRoot: d.t.sockRoot, ids: [d.uuid] });
        killLeftovers({ sockRoot: d.t.sockRoot, ids: [d.uuid] });
        openEnvs.delete(d.t);
        d.t.cleanup();
        expect(left).toEqual({ processes: [], files: [] });
        return d.s.snapshot();
      }

      test(
        "H-25 snapshot during a hold: state RUNNING, activity hook, phase SETTLING, turnEndRecordMissing false",
        async () => {
          const ctl = controlled();
          const d = await direct({ script: [{ say: "ANS-ONE" }], hooks: ctl.binding });
          try {
            await until(() => ctl.calls.length === 1, "settle()");
            const snap = d.s.snapshot();
            expect(snap.state).toBe("RUNNING");
            expect(snap.activity).toBe("hook");
            expect(snap.phase).toBe("SETTLING");
            expect(snap.turnEndRecordMissing).toBe(false);
            expect(snap.pendingHookInputs).toBe(0);
            // published at record, before any transition; not yet decided
            expect(d.recorded.map((r) => r.answer)).toEqual(["ANS-ONE"]);
            expect(d.decided).toEqual([]);
            expect(d.s.chainText()).toBe("ANS-ONE");
          } finally {
            await directDone(d);
          }
        },
        T
      );

      test(
        "H-26 hasIdleWork false: SETTLING never entered, settle() never called, the verdict in the settling step",
        async () => {
          const ctl = controlled({ idle: false });
          const d = await direct({ script: [{ say: "ANS-ONE" }], hooks: ctl.binding });
          try {
            await d.s.terminal;
            expect(ctl.calls).toEqual([]);
            expect(d.transitions).toEqual([
              ["STARTING", "RUNNING"],
              ["RUNNING", "COMPLETED"],
            ]);
            expect(d.recorded).toHaveLength(1);
            expect(d.decided).toHaveLength(1);
            expect(d.s.snapshot().anomalies.some((a) => a.startsWith("illegal_transition"))).toBe(
              false
            );
          } finally {
            await directDone(d);
          }
        },
        T
      );

      test(
        "H-27 end record and exit in the same tick: no hold, settle() never called, COMPLETED with the exit note",
        async () => {
          const ctl = controlled();
          const d = await direct({
            script: [{ say: "ANS-ONE", exitAfter: 0, exitDelayMs: 0 }],
            hooks: ctl.binding,
          });
          try {
            const snap = await d.s.terminal;
            expect(ctl.calls).toEqual([]);
            expect(snap.state).toBe("COMPLETED");
            expect(snap.detail ?? "").toContain("pane child exited 0");
            expect(d.decided.map((t) => t.answer)).toEqual(["ANS-ONE"]);
          } finally {
            await directDone(d);
          }
        },
        T
      );

      test(
        "H-27b the end record settles inside the exit-capture window: the exit note keeps its code",
        async () => {
          // The interleaving H-27 hits under load, made deterministic: the exit event is
          // processed (the pane is known dead) and the session is still capturing the final
          // screen when a tick settles the turn on its end record. The note must carry the
          // code the exit event reported, never a bare "pane child exited".
          const ctl = controlled();
          const d = await direct({
            script: [{ delayMs: 1000, say: "ANS-ONE" }],
            hooks: ctl.binding,
            exitCaptureDelayMs: 4000,
          });
          try {
            await until(
              () => d.transitions.some(([, to]) => to === "RUNNING"),
              "the turn is RUNNING"
            );
            const exit = (
              d.s as unknown as { onPaneExit(e: { exitCode: number; lastLine: string }): void }
            ).onPaneExit.bind(d.s);
            exit({ exitCode: 0, lastLine: "" });
            const snap = await d.s.terminal;
            expect(ctl.calls).toEqual([]);
            expect(snap.state).toBe("COMPLETED");
            expect(snap.detail ?? "").toContain("pane child exited 0");
            expect(d.decided.map((t) => t.answer)).toEqual(["ANS-ONE"]);
          } finally {
            await directDone(d);
          }
        },
        T
      );

      test(
        "H-28 binding absent: today's events — no record callback, no SETTLING, chain fields at their no-hook values",
        async () => {
          const d = await direct({ script: [{ say: "ANS-ONE" }] });
          try {
            const snap = await d.s.terminal;
            expect(snap.state).toBe("COMPLETED");
            expect(d.recorded).toEqual([]);
            expect(d.transitions).toEqual([
              ["STARTING", "RUNNING"],
              ["RUNNING", "COMPLETED"],
            ]);
            const turn = d.decided[0] as SettledTurn;
            expect(turn.chainAnswers).toEqual([]);
            expect(turn.chainDelivery).toEqual(turn.delivery);
            expect(turn.hookTurns).toBe(0);
            expect(turn.hookCaused).toBe(false);
            expect(snap.pendingHookInputs).toBe(0);
          } finally {
            await directDone(d);
          }
        },
        T
      );
    }
  );

  describe.concurrent("the hold's result is applied only on current evidence", () => {
    const screenShows = (c: Chan, text: string) =>
      (c.manager.captureSession(c.id) as CaptureResult).lines.some((l) => l.includes(text));
    /** The fake starts its re-wake when this file exists: after the test saw the hold. */
    const gateFile = () => join(tmpdir(), `claudish-rewake-gate-${randomUUID()}`);

    test(
      "a re-wake whose working row shows before its records: the injection is never typed; its result is abandoned rewake",
      async () => {
        const ctl = controlled();
        const gate = gateFile();
        const c = await channel({
          script: [
            {
              say: "ANS-ONE",
              rewake: { gateFile: gate, delayMs: 100, workingMs: 2_500, say: "ANS-ONE-B" },
            },
            { say: "ANS-NEVER" },
          ],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "the hold");
          writeFileSync(gate, "");
          // The screen shows the re-woken turn working; the transcript has nothing of it yet.
          await until(() => screenShows(c, "Simmering"), "the re-wake's working row");
          ctl.calls[0]?.resolve(inject("HOOK-LATE"));
          await until(
            () => ctl.calls.length === 2 || keylog(c.t).includes("HOOK-LATE"),
            "the re-settle, or the injection typed over the running turn"
          );
          expect(keylog(c.t)).not.toContain("HOOK-LATE");
          expect(ctl.abandoned).toEqual([{ text: "HOOK-LATE", reason: "rewake" }]);
          expect(ctl.calls[1]?.turn.index).toBe(1);
          expect(ctl.calls[1]?.turn.answer).toContain("ANS-ONE-B");
          ctl.calls[1]?.resolve(nothing);
          const end = await c.terminal();
          expect(end.state).toBe("COMPLETED");
          const out = c.output();
          expect(lineCount(out, "ANS-ONE")).toBe(1);
          expect(lineCount(out, "ANS-ONE-B")).toBe(1);
        } finally {
          rmSync(gate, { force: true });
          await done(c);
        }
      },
      T
    );

    test(
      "a re-wake already in the transcript, with no frame since: the result arrives, the injection is never typed",
      async () => {
        const ctl = controlled();
        const gate = gateFile();
        const c = await channel({
          script: [
            {
              say: "ANS-ONE",
              rewake: { gateFile: gate, delayMs: 100, quietMs: 3_000, say: "ANS-ONE-B" },
            },
            { say: "ANS-NEVER" },
          ],
          binding: ctl.binding,
        });
        try {
          await until(() => ctl.calls.length === 1, "the hold");
          writeFileSync(gate, "");
          const transcript = c.t.transcriptPathFor(c.info().claudeSessionId as string);
          // Resolve the instant the re-wake's records are on disk: the pane's last poll
          // (frame-debounced, or the 1 s backstop) is older than them.
          const end = Date.now() + 20_000;
          while (!readFileSync(transcript, "utf8").includes("ANS-ONE-B")) {
            if (Date.now() > end) throw new Error("timed out waiting for the re-wake's records");
            await Bun.sleep(2);
          }
          ctl.calls[0]?.resolve(inject("HOOK-LATE"));
          await until(
            () => ctl.calls.length === 2 || keylog(c.t).includes("HOOK-LATE"),
            "the re-settle, or the injection typed over the running turn"
          );
          expect(keylog(c.t)).not.toContain("HOOK-LATE");
          // Either the result came back (abandoned rewake), or, rarely, the pane's own
          // backstop poll saw the records first and ended the hold before it arrived.
          if ((ctl.calls[0]?.signal.reason as string | undefined) !== "rewake")
            expect(ctl.abandoned).toEqual([{ text: "HOOK-LATE", reason: "rewake" }]);
          ctl.calls[1]?.resolve(nothing);
          expect((await c.terminal()).state).toBe("COMPLETED");
          expect(lineCount(c.output(), "ANS-ONE-B")).toBe(1);
        } finally {
          rmSync(gate, { force: true });
          await done(c);
        }
      },
      T
    );

    test(
      "a result that waited for a working row: a re-wake written as the row clears ends the hold; the injection is never typed",
      async () => {
        const ctl = controlled();
        const gate = gateFile();
        const c = await channel({
          script: [
            {
              say: "ANS-ONE",
              rewake: {
                gateFile: gate,
                delayMs: 100,
                workingMs: 1_500,
                clearWithRecords: true,
                quietMs: 3_000,
                say: "ANS-ONE-B",
              },
            },
            { say: "ANS-NEVER" },
          ],
          binding: ctl.binding,
          // A frame polls only 3 s after the last poll, so the frame that clears the row,
          // 1.5 s after the result's own read, comes with a view that predates the records.
          timings: { pollDebounceMs: 3_000, pollBackstopMs: 6_000 },
        });
        try {
          await until(() => ctl.calls.length === 1, "the hold");
          writeFileSync(gate, "");
          // The result arrives while the screen shows work, so it waits for the screen.
          await until(() => screenShows(c, "Simmering"), "the working row");
          ctl.calls[0]?.resolve(inject("HOOK-LATE"));
          // The row then clears in the same instant the re-wake's records land: only a
          // read made at admission sees them.
          await until(
            () => ctl.calls.length === 2 || keylog(c.t).includes("HOOK-LATE"),
            "the re-settle, or the injection typed over the running turn"
          );
          expect(keylog(c.t)).not.toContain("HOOK-LATE");
          expect(ctl.abandoned).toEqual([{ text: "HOOK-LATE", reason: "rewake" }]);
          ctl.calls[1]?.resolve(nothing);
          expect((await c.terminal()).state).toBe("COMPLETED");
          expect(lineCount(c.output(), "ANS-ONE-B")).toBe(1);
        } finally {
          rmSync(gate, { force: true });
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("hook text never reaches the command path", () => {
    test(
      "an injection that starts with a slash is dropped delivery_unavailable and never typed",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ say: "ANS-ONE" }, { say: "ANS-NEVER" }],
          binding: ctl.binding,
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(() => ctl.calls.length === 1, "the hold");
          // the double skips the action rules a real binding applies
          ctl.calls[0]?.resolve(inject("/model opus"));
          await until(
            () => c.info().state === "AWAITING_INPUT" && c.info().turnsCompleted === 1,
            "idle after the dropped injection"
          );
          await Bun.sleep(300);
          expect(keylog(c.t)).toEqual(["Reply with the first answer."]);
          expect(ctl.dropped).toEqual([{ text: "/model opus", reason: "delivery_unavailable" }]);
        } finally {
          await done(c);
        }
      },
      T
    );
  });

  describe.concurrent("an interactive turn a hook follows gets its own verdict", () => {
    test(
      "turn 1 ends in an API error: FAILED api_error before any injection; the injection is dropped session_ended",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ apiError: "API Error: 500 upstream failed" }, { say: "ANS-NEVER" }],
          binding: ctl.binding,
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "Reply with the first answer.");
          await until(() => ctl.calls.length === 1, "the hold");
          ctl.calls[0]?.resolve(inject("HOOK-AFTER-ERROR"));
          await until(
            () => TERMINAL.includes(c.info().state) || keylog(c.t).includes("HOOK-AFTER-ERROR"),
            "the verdict, or the injection typed"
          );
          expect(keylog(c.t)).not.toContain("HOOK-AFTER-ERROR");
          const end = await c.terminal();
          expect(end.state).toBe("FAILED");
          expect(end.reason).toBe("api_error");
          expect(ctl.dropped).toEqual([{ text: "HOOK-AFTER-ERROR", reason: "session_ended" }]);
        } finally {
          await done(c);
        }
      },
      T
    );

    test(
      "turn 1's task file was not read: prompt_not_read is recorded, then the injection is the next turn",
      async () => {
        const ctl = controlled();
        const c = await channel({
          script: [{ noRead: true, say: "ANS-ONE" }, { say: "ANS-TWO" }],
          binding: ctl.binding,
          prompt: null,
        });
        try {
          await until(() => c.info().state === "AWAITING_INPUT", "boot");
          c.manager.sendInput(c.id, "A caller turn\nthat goes as a file.");
          await until(() => ctl.calls.length === 1, "the hold");
          ctl.calls[0]?.resolve(inject("HOOK-NEXT"));
          await until(() => ctl.calls.length === 2, "the injected turn's hold");
          ctl.calls[1]?.resolve(nothing);
          await until(
            () => c.info().state === "AWAITING_INPUT" && c.info().turnsCompleted === 2,
            "idle"
          );
          expect(keylog(c.t)).toContain("HOOK-NEXT");
          const notRead = eventsOf(c).filter(
            (e) => e.type === "anomaly" && e.key === "prompt_not_read"
          );
          expect(notRead.map((e) => e.turn)).toEqual([1]);
        } finally {
          await done(c);
        }
      },
      T
    );
  });
});