Skip to content

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

146 KB
Raw Blame
/**
 * `PaneSession` — one interactive Claude Code, launched through claudish, in its own
 * headless magmux pane, driven over the socket (architecture §2.9–§2.10).
 *
 * The transcript decides turn state (D3): acceptance, settle, answer and accounting.
 * magmux supplies liveness (`exit`, pids), the screen (`watch` frames) and input
 * (`send`). The lifecycle is the phase table of `slot-state.ts`; this class is the only
 * thing that fires its events. Policy stays with the owner (D8): `decide(turn)` and
 * `onBlocked(block)` are the owner's, never ours.
 *
 * Every event handler runs inside `step()`, which reports the NET wire-state change of
 * one event-processing step to `onTransition` (so RUNNING → IDLE → ADMITTING in one step
 * reports nothing) and coalesces `onChange` to at most 4 per second.
 *
 * No claudish timer ends a turn after its prompt was accepted (D10). The only bounds are
 * boot (90 s) and admission of the CREATED prompt (30 s), before any work exists, and a
 * MCP session's own `timeoutMs`.
 *
 * Session hooks (architecture §7.3). With a `hooks` binding, a settled turn is RECORDED
 * first (its answer published through `onTurnRecorded`, before any transition) and
 * CONCLUDED later: between the two the pane sits in `SETTLING` (wire RUNNING) while
 * `binding.settle()` runs. The phase is the latch: the ticker never re-settles a held
 * turn, and every way out of the hold is a table edge that aborts it with a reason. An
 * injection the hold returns becomes the next turn of the session's TURN CHAIN; the
 * verdict is taken once, at the end, on the session's current shape. Without a binding
 * none of this runs: `finishTurn` is today's code path exactly.
 */

import type { ChildProcess } from "node:child_process";
import { readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { getConfigFileOverride } from "../config-override.js";
import {
  type HookQueueItem,
  type InjectionQueueState,
  type QueueItem,
  afterAdmission,
  callerCount,
  emptyQueueState,
  hookCount,
  next as nextQueueDecision,
} from "../hooks/injection/queue.js";
import type {
  HoldAbortReason,
  HoldInjection,
  HoldResult,
  SessionHookBinding,
} from "../hooks/session/binding.js";
import { claudeConfigDir } from "../mcp-session/parent-session.js";
import { waitForExit } from "../process-tree.js";
import { redactSecrets } from "../redact.js";
import { locateBox, locatedBoxText } from "./box-locate.js";
import {
  type CaptureResult,
  type CaptureUnchanged,
  ContractErrorException,
  type FailureReason,
  type SlotState,
} from "./contract.js";
import { checkGateBinding } from "./gate-binding.js";
import {
  BOOT_DIALOG_KINDS,
  type GateDialogKind,
  type GateInput,
  SEND_READY_WAIT_DEFAULT_MS,
  type SendOutcome,
  type SendOutcomeKind,
  assertNever,
  classifySendReply,
  parseGateInput,
  sendBudgetMs,
} from "./input-gate.js";
import { MagmuxClient, type MagmuxConnectError, type MagmuxReply } from "./magmux-client.js";
import {
  type ClaudishLaunch,
  FATAL_MAGMUX_STDERR,
  MIN_MAGMUX_VERSION,
  SUBCOMMAND_WORDS,
  assertMagmuxAvailable,
  buildClaudishPaneArgv,
  buildPaneEnv,
  createLaunchDirs,
  ensureSockRoot,
  launcherScript,
  mintPaneId,
  resolveClaudishLaunch,
  sockRootFor,
  spawnPaneMagmux,
  spawnPaneWatcher,
  versionAtLeast,
  writeLauncherFiles,
} from "./pane-launch.js";
import {
  type RegisteredPane,
  ensureSwept,
  installPaneShutdownHooks,
  ownerStartOfSelf,
  paneShutdownHooksInstalled,
  refreshGroupOf,
  registerPane,
  removePaneFiles,
  reservePanes,
  takePaneReservation,
  unregisterPane,
  updateRecord,
  writeRecord,
} from "./pane-registry.js";
import {
  DEFAULT_PANE_COLS,
  DEFAULT_PANE_ROWS,
  type PaneSize,
  RESIZE_QUIET_MS,
  clampPaneSize,
  samePaneSize,
} from "./pane-size.js";
import {
  type GroupSnapshot,
  type PaneIdentity,
  groupCheck,
  isLaunchDirPath,
  liveEscaped,
  readProcessTableAsync,
  recordPathOf,
  sockPathOf,
  verifiedGroupSnapshot,
} from "./process-identity.js";
import { type Delivery, deliveryRefusal, planDelivery, writeTurnFile } from "./prompt-delivery.js";
import {
  agentRejectedLine,
  choiceDialog,
  dialogText,
  flatText,
  hasChoiceDialog,
  inputBox,
  isWorking,
  menuAbove,
  nameBootScreen,
  screenAnswer,
  screenErrorRows,
  screenText,
  stopHookRunning,
  transcriptSavingOff,
  workingAboveBox,
} from "./screen-classifier.js";
import {
  type MagmuxCapture,
  type MagmuxFrame,
  type ScreenState,
  applyFrame,
  emptyScreen,
} from "./screen-model.js";
import { KNOWN_STATUSES, type RegistryRecord, SessionRegistry } from "./session-registry.js";
import {
  CORROBORATION_MS,
  type CorroborationFacts,
  SECONDARY_QUIET_MS,
  type SettleDecision,
  agentCountMismatch,
  decideSettle,
} from "./settle-rule.js";
import {
  type Phase,
  type PhaseEvent,
  isTerminalPhase,
  nextPhase,
  wireState,
} from "./slot-state.js";
import { TranscriptFollower, type TranscriptView, type TurnView } from "./transcript-follower.js";
import type { FinalVerdict, PaneSnapshot, SettledTurn } from "./types.js";

export type { FinalVerdict, PaneSnapshot, SettledTurn } from "./types.js";

export const BOOT_TIMEOUT_MS = 90_000;
export const ADMIT_TIMEOUT_MS = 30_000;
/**
 * A turn the input gate accepted with no transcript witness this long after the acceptance
 * settles from the screen (degraded mode). Acceptance itself is never inferred from the
 * screen (architecture-v2 §5.7).
 */
export const DEGRADED_ENTRY_MS = 10_000;
/** Degraded settle: no change above the box for 2 × this. */
export const SCREEN_SETTLE_QUIET_MS = 3_000;
/** A panel command's screen must have been up this long after delivery before Esc. */
const PANEL_SETTLE_MS = 500;
/**
 * @deprecated Nothing reads it: boot readiness is magmux's `input.ready` (architecture-v2
 * §6.2), which waits for the box and a raw terminal both still for 1 s AND for Claude
 * Code's boot stdin reset (or 3.5 s after the terminal first went raw) — the hazard this
 * 3 s wait existed for. Kept only so the integration test that pins it still loads; delete
 * it with that test.
 */
export const REPL_STABLE_MS = 3_000;
/**
 * A gated send's client request timeout is magmux's own upper bound on it
 * (`sendBudgetMs`, protocol.SendBudget) plus this. Every admission attempt is sized so
 * that timeout ends by the admission deadline (architecture-v2 R1.4).
 */
const SEND_CLIENT_SLACK_MS = 2_000;
/** No attempt is started with less readiness wait than this (R1.4). */
const MIN_READY_TIMEOUT_MS = 1_000;
/** A `busy` refusal (Enter not pressed): the next attempt after this. */
const BUSY_RETRY_MS = 250;
/** After a `text_mismatch`: magmux's verify settle, so a late draw has landed (sendbudget.go). */
const MISMATCH_SETTLE_MS = 1_000;
/** After a ctrl-u from the admission loop: wait at most this for a fresh `ready` reading. */
const CLEAR_WAIT_MS = 1_000;
/** A dialog or choice screen static this long blocks boot. */
const BOOT_STATIC_MS = 5_000;
const TICK_MS = 250;
/** research-magmux §6 recommends 2–4; 4 halves boot/witness latency at no idle cost. */
const WATCH_FPS = 4;
const POLL_BACKSTOP_MS = 1_000;
/** R3-M4: a `finishing` turn with a static screen for this many secondary windows. */
const TURN_END_MISSING_FACTOR = 3;
/** A resize reply, and the screen showing the new size after it. */
const RESIZE_REPLY_MS = 10_000;
const RESIZE_SCREEN_MS = 1_000;
/**
 * magmux's input gate is read by polling `list` (it publishes no readiness event and
 * refreshes `input` at 4 Hz): one request in flight at a time, this often, while connected.
 */
const GATE_POLL_MS = 250;
const GATE_REPLY_MS = 1_000;
/** A gate reading older than this, or any reading while disconnected, is unknown. */
const GATE_STALE_MS = 1_000;
/**
 * The most gate corroboration may delay a transcript-closed turn (architecture-v2 §7.1,
 * Jack's decision J2): after this much chat quiet it settles with `settle_gate_unconfirmed`.
 */
export const GATE_GRACE_MS = SECONDARY_QUIET_MS;
/**
 * `list` showing pane 0 dead this long with no `exit` event: take the exit path anyway.
 * The event stays the primary path (it carries `lastLine`); this is its backstop.
 */
const GATE_DEAD_BACKSTOP_MS = 1_000;
/**
 * The longest a liveness exit (ESRCH while disconnected) waits for magmux to name the code.
 * magmux keeps a dead pane's code after the socket drops, and whatever dropped the socket can
 * hold the path away for a moment, so the query redials until this bound rather than asking
 * once. Two seconds covers a socket that comes back within about a second of the exit being
 * seen (the liveness check itself runs once a second); it is also all a magmux that is gone,
 * wedged or slow can add to the finish.
 */
const EXIT_CODE_QUERY_MS = 2_000;
/** The redial period inside EXIT_CODE_QUERY_MS, and the `list` re-ask period. */
const EXIT_CODE_RETRY_MS = 50;
/** Gate reasons that carry no dialog kind: a static screen under one is named from its words. */
const GATE_KINDLESS_REASONS: ReadonlySet<string> = new Set([
  "starting",
  "terminal_not_ready",
  "no_input_box",
]);
/** Dialogs a turn can open; a boot dialog kind is never one of them. */
const RUNTIME_DIALOG_KINDS: ReadonlySet<GateDialogKind> = new Set<GateDialogKind>([
  "permission",
  "question",
  "plan",
  "select",
]);
/** The session registry is re-read at most this often (telemetry only). */
const REGISTRY_READ_MS = 250;
/** A registry/screen disagreement must hold this long before it is counted. */
const REGISTRY_DISAGREE_MS = 2_000;
/**
 * `registry_idle_gate_starting` must hold this long: while it waits for Claude Code's boot
 * reset the gate says `starting` for up to its 3.5 s floor plus 1 s of stillness, a window
 * in which the registry can already read idle. Longer than that, it is the canary.
 */
const REGISTRY_GATE_BOOT_DISAGREE_MS = 5_000;
/** No live registry record this long after boot was ready: `registry_record_missing`. */
const REGISTRY_MISSING_MS = 5_000;
const MAX_ANOMALY_KEYS = 64;
/** Settled answers kept for `turnAnswer` (owners read the current or the last one). */
const KEPT_ANSWERS = 4;
/** `hooks.injection.maxConsecutive` when the binding does not say (§4.7 rule 5). */
const DEFAULT_MAX_CONSECUTIVE = 3;

export interface PaneBlock {
  kind: "question" | "permission";
  tool: string;
  text: string;
}

export interface PaneSessionOptions {
  kind: "t" | "s";
  label: string;
  /** already checked by checkChildFlags */
  callerFlags: string[];
  spawnModel: string;
  cwd: string;
  sessionUuid: string;
  /** transcriptPathFor(realpath cwd, sessionUuid, projectsDir(parentEnv)) — the caller derives it */
  transcriptPath: string;
  slotEnv: Record<string, string>;
  shape: "one-shot" | "interactive";
  /** enqueued before boot; delivered on boot_ready */
  initialPrompt?: string;
  /** the pane's size at launch, clamped here; DEFAULT_PANE_COLS × DEFAULT_PANE_ROWS when absent */
  initialSize?: PaneSize;
  /** false when callerFlags remove Read (§2.3 rule 4) */
  readAvailable: boolean;
  decide: (turn: SettledTurn) => FinalVerdict | "continue";
  onBlocked: (b: PaneBlock) => FinalVerdict | "wait";
  bootTimeoutMs?: number;
  /** initialDelivery only */
  admitTimeoutMs?: number;
  /** whole-session deadline → TIMEOUT (MCP sessions only; team never passes it) */
  timeoutMs?: number;
  /** the session's hook binding (§7.3); absent → today's code path exactly */
  hooks?: SessionHookBinding;
  /**
   * Synchronous, in the step that records a settled turn, before any transition of that
   * step (binding present only): the answer reaches the owner before anything can end
   * the session.
   */
  onTurnRecorded?: (turn: SettledTurn) => void;
  /** coalesced ≤ 4/s */
  onChange?: (snap: PaneSnapshot, prev: SlotState) => void;
  /** every wire-state change, synchronously, never coalesced, NET of one event-processing step */
  onTransition?: (t: { from: SlotState; to: SlotState; at: string; snap: PaneSnapshot }) => void;
  magmuxBinary?: string;
  sockRoot?: string;
  claudishSpawn?: ClaudishLaunch;
  parentEnv?: Record<string, string | undefined>;
  /** @internal test-only timing seams (X-M7); production never passes them */
  timings?: {
    secondaryQuietMs?: number;
    screenSettleQuietMs?: number;
    degradedEntryMs?: number;
    /**
     * @deprecated ignored: there is no resend timer; magmux's input gate resends Enter
     * itself (architecture-v2 §5.1). Kept so the tests that still pass it load.
     */
    resendAfterMs?: number;
    corroborationMs?: number;
    /** GATE_GRACE_MS */
    gateGraceMs?: number;
    bootStaticMs?: number;
    /** @deprecated ignored: boot readiness is magmux's `input.ready` (see `REPL_STABLE_MS`) */
    replStableMs?: number;
    /** H-31: hold the exit-path screen capture this long, as a slow magmux reply does */
    exitCaptureDelayMs?: number;
    /** a LATER admission's bound, through owners that do not pass `admitTimeoutMs` (H-13 … H-15) */
    admitTimeoutMs?: number;
    /** a frame polls the transcript only this long after the last poll (default 250) */
    pollDebounceMs?: number;
    /** with no frame, the transcript is polled this often (default 1 000) */
    pollBackstopMs?: number;
  };
}

/**
 * What `resize` answers: the size SET, whether the pane's size moved, and the screen's
 * seq after it. `pending` = the socket is reconnecting; the size is applied on the redial.
 */
export interface PaneResizeOutcome {
  cols: number;
  rows: number;
  changed: boolean;
  seq: number;
  pending?: true;
}

export type SendResult =
  | { ok: true; queued: number }
  | { ok: false; reason: "terminal" | "delivery_unavailable" | "unsupported_command" };

/** What `get_diagnostics` reads from a live pane beyond the snapshot (§4.2). */
export interface PaneDiagnostics {
  /** the head of magmux's own stderr (≤ 8 KB) */
  magmuxStderr: string;
  /** the child's session-registry record as last read (telemetry); null when none matched */
  registry: { status: string | null; waitingFor: string | null; version: string | null } | null;
  /** assistant text before a file-delivered turn's task file was read (X-H4) */
  preambleBytes: number;
  /** read coverage of the current turn's task file; null for a typed turn or no turn */
  readCoverage: {
    linesTotal: number;
    linesReturned: number;
    complete: boolean;
    reads: number;
  } | null;
  /**
   * magmux's input gate as last read (`list` → pane 0 `input`); `ageMs` since it was read.
   * null: never read on this connection, or disconnected. Additive (architecture-v2 §9).
   */
  gate: { ready: boolean; reason: string | null; detail: string | null; ageMs: number } | null;
  /** The last gated send's outcome, in the input gate's own words; null before any send. */
  lastSend: PaneLastSend | null;
}

/** `get_diagnostics`' view of the last gated send (architecture-v2 §9, R1.2). */
export interface PaneLastSend {
  kind: SendOutcomeKind;
  /** a `busy` / `not_accepted` reason, or a client / magmux code */
  reason?: string;
  accept?: string;
  evidence?: string;
  retypeCause?: string;
  /** gated sends of the admission (or control line) it belongs to */
  attempts: number;
}

export interface PaneSession {
  readonly paneId: string;
  readonly sockPath: string;
  /** resolves when the wire state leaves STARTING: RUNNING, AWAITING_INPUT (promptless), or terminal */
  readonly ready: Promise<void>;
  readonly terminal: Promise<PaneSnapshot>;
  snapshot(): PaneSnapshot;
  capture(sinceSeq?: number, opts?: { spans?: boolean }): CaptureResult | CaptureUnchanged;
  send(text: string): SendResult;
  /**
   * Set the terminal size (clamped). Allowed in every live state; a terminal session
   * answers its last size with `changed:false`. Throws `ContractErrorException` with
   * `resize_unsupported` (magmux lacks the op) or `delivery_unavailable`.
   */
  resize(cols: number, rows: number): Promise<PaneResizeOutcome>;
  turnAnswer(index: number): string;
  /** The recorded chain answers plus the running chain turn's partial, joined like chainAnswerOf. */
  chainText(): string;
  /** main-chain assistant message ids the transcript has shown, first-seen order, each once */
  assistantMessageIds(): readonly string[];
  diagnostics(): PaneDiagnostics;
  cancel(): { changed: boolean; state: SlotState };
  expire(): { changed: boolean; state: SlotState };
  reaped(): Promise<void>;
}

/**
 * Which gated send of an admission comes next (architecture-v2 §5.4): `submit` types the
 * line and presses Enter in one send; a slash command is `type` (no Enter), a menu check,
 * then `enter` (`{keys:["enter"]}`, itself a gated SUBMIT).
 */
type SubmitStep = "submit" | "type" | "enter";

/**
 * Why no further send of an admission is made: Enter may have been pressed and nothing
 * proves it, so only claudish's own transcript witness can accept now (§5.6, R1.3).
 */
type SubmittedUnproven =
  | "unconfirmed"
  | "reply_lost"
  | "still_in_box_twice"
  | "maybe_submitted_by_other";

interface Admission {
  index: number;
  /** a hook item's admission takes the hook routes when it is never accepted (§7.3 step 7) */
  item: QueueItem;
  text: string;
  plan: Delivery;
  /** the one line every gated send of this admission types */
  line: string;
  initial: boolean;
  startedAt: number;
  /** startedAt + (initial ? admitTimeoutMs : ADMIT_TIMEOUT_MS); no attempt outlives it */
  deadline: number;
  step: SubmitStep;
  /** a gated send of this admission awaits its reply */
  inFlight: boolean;
  /** gated sends made */
  attempts: number;
  submittedUnproven: SubmittedUnproven | null;
  /** the one ctrl-u + resend after `still_in_box` was used */
  stuckRetried: boolean;
  /** a command that opened a panel or picker (§5.4 `panelStep`) */
  panel: null | {
    showingSince: number | null;
    escaped: boolean;
    /** Enter reached the pane (`unconfirmed`), or not (`busy dialog:select`) */
    entered: boolean;
  };
  /** no further attempt: a stop row of §5.2 already decided, or the pane is gone */
  stopped: boolean;
  /** the box may hold this admission's own text (a lost TYPE reply, a withheld Enter) */
  clearFirst: boolean;
  /**
   * When the reply that set `clearFirst` arrived. Only a gate reading received after it (by
   * one publication interval) may clear the flag: an older one can say `ready` while that
   * delivery's text is still being drawn (Revision 3 item 2, DB-2).
   */
  clearAfter: number;
  /** a TYPE whose reply was lost: its delivery may still be typing until `until` (R1.5.3) */
  lostType: { client: MagmuxClient; until: number } | null;
  /** the latest reply, for `prompt_not_accepted`'s detail */
  last: SendOutcome | null;
  /** anomaly keys counted once per admission */
  noted: Set<string>;
}

/** A `resize` call waiting for the drain worker's send that carries its size (or a later one). */
interface ResizeWaiter {
  resolve: (r: PaneResizeOutcome) => void;
  reject: (e: unknown) => void;
}

/** A settled turn before the chain fields are added (§4.10). */
type TurnCore = Omit<SettledTurn, "chainAnswers" | "chainDelivery" | "hookTurns" | "hookCaused">;

interface ScreenTurn {
  echo: string;
  acceptedAt: number;
  errorLogSize: number;
}

const EVENT_REASON: Partial<Record<PhaseEvent, FailureReason>> = {
  boot_dialog: "first_run_dialog",
  boot_blocked: "boot_blocked",
  admit_deadline: "prompt_not_accepted",
  pane_lost: "pane_lost",
  cancel: "cancelled",
  timeout: "timeout",
};

const VERDICT_EVENT: Record<FinalVerdict["state"], PhaseEvent> = {
  COMPLETED: "verdict_completed",
  EMPTY: "verdict_empty",
  FAILED: "verdict_failed",
};

function iso(ms: number): string {
  return new Date(ms).toISOString();
}

function alive(p: ChildProcess | null): boolean {
  return !!p && p.exitCode === null && p.signalCode === null;
}

function screenTailOf(s: ScreenState, n = 12): string {
  const lines = s.lines.filter((l) => l.trim());
  return lines.slice(-n).join("\n");
}

export class PaneSessionImpl implements PaneSession, RegisteredPane {
  readonly paneId: string;
  readonly sockPath: string;
  readonly root: string;
  readonly identity: PaneIdentity;
  readonly ready: Promise<void>;
  readonly terminal: Promise<PaneSnapshot>;
  group: GroupSnapshot | null = null;
  reapFailed = false;

  private readonly o: PaneSessionOptions;
  private readonly turnDir: string;
  private readonly ctlDir: string;
  private readonly follower: TranscriptFollower;
  private readonly startedAtMs = Date.now();
  private readonly secondaryQuietMs: number;
  private readonly corroborationMs: number;

  private resolveReady!: () => void;
  private resolveTerminal!: (s: PaneSnapshot) => void;
  private readySettled = false;

  private phase: Phase = "BOOTING";
  private initialDelivery = false;
  private initialPending: boolean;
  private shape: "one-shot" | "interactive";
  /** caller and hook items (§7.2); the policy is the pure `hooks/injection/queue.ts` */
  private q: InjectionQueueState;
  private screen: ScreenState;
  private final = false;
  private turnIndex = 0;
  private admission: Admission | null = null;
  private screenTurn: ScreenTurn | null = null;
  private turnSource: "transcript" | "screen" = "transcript";
  private turnsCompleted = 0;
  private rewakeOfSettled = false;
  private settledChatOffset: number | null = null;
  private lastChatOffset: number | null = null;
  private lastChatSeenAt = 0;
  private currentDelivery: Delivery | null = null;
  private answers = new Map<number, string>();
  private lastCaptureSource: SettledTurn["captureSource"] | null = null;
  private exitRequested = false;
  private escapeArmed = false;
  private escapeSentAt: number | null = null;
  private blockedToolId: string | null = null;
  private reason: FailureReason | null = null;
  private detail: string | null = null;
  private activity: string | null = null;
  private exitCode: number | null = null;
  private endedAtMs: number | null = null;
  private claudeCodeVersion: string | null = null;
  private anomalies = new Map<string, number>();
  private turnEndMissing = false;
  /** the live agent_count_mismatch pair as `counted/reported`; null while counts agree */
  private agentMismatch: string | null = null;
  private readonly registry: SessionRegistry;
  private registryRec: RegistryRecord | null = null;
  private registryEverSeen = false;
  private lastRegistryReadAt = 0;
  private bootReadyAtMs: number | null = null;
  /** registry/screen disagreements now holding, with when each began; counted once at onset */
  private disagreeSince = new Map<string, number>();
  private disagreeCounted = new Set<string>();
  private exitScrollback = "";
  private exitLastLine = "";

  /** the size the viewer asked for last (clamped); the drain worker always sends THIS one */
  private desiredSize: PaneSize;
  /** the pane's size as magmux last confirmed it; null = unknown (a lost or timed-out reply) */
  private appliedSize: PaneSize | null;
  /** `capabilities.verbs` contains "resize", as of the latest attach */
  private supportsResize = false;
  private resizeWaiters: ResizeWaiter[] = [];
  private resizeDraining = false;
  /** the size of the worker's last send on this connection; null = none since the attach */
  private lastSentSize: PaneSize | null = null;
  /**
   * The resize quiet window [from, until): opened at a send, only ever extended (a lost
   * reply may follow an applied resize, so nothing retracts it); 0 = never opened.
   */
  private resizeQuietFrom = 0;
  private resizeQuietUntil = 0;
  /** the last screen change that is activity, i.e. not a resize redraw (M4) */
  private activityChangedAt = 0;

  /** the last `list` → pane 0 `input` reading; read through `gateNow()`, never directly */
  private gate: GateInput | null = null;
  /** this connection passed the binding check: its gate readings may be trusted */
  private gateTrusted = false;
  private gateInFlight = false;
  private gateTimer: ReturnType<typeof setInterval> | null = null;
  /** when `list` first showed pane 0 dead with no `exit` event yet; 0 = not dead */
  private gateDeadSince = 0;
  /** the last gated send's outcome (`get_diagnostics`) */
  private lastSend: PaneLastSend | null = null;
  /**
   * When the current turn was accepted, by the gate's evidence or the witness: the
   * degraded-entry clock (§5.7) and the `witness_missing` clock (§5.8). null: not accepted.
   */
  private turnAcceptedAt: number | null = null;
  private turnErrorLogSize = 0;
  private witnessMissingCounted = false;
  /** a later send abandoned unwitnessed: a witness arriving in IDLE re-wakes this turn (§5.3) */
  private abandonedIndex: number | null = null;

  /* session hooks (§7.3); untouched without a binding */
  private readonly hooks: SessionHookBinding | null;
  /** the turn chain: every recorded answer since the last caller admission */
  private chain: Array<{ index: number; answer: string }> = [];
  private chainHead: SettledTurn["delivery"] | null = null;
  private hookTurns = 0;
  /** the current turn was admitted from a hook item */
  private turnHookCaused = false;
  /** recorded, not yet concluded */
  private heldTurn: SettledTurn | null = null;
  private holdGen = 0;
  private holdController: AbortController | null = null;
  private holdWatchdog: ReturnType<typeof setTimeout> | null = null;
  /**
   * The hold's result, waiting in SETTLING until the screen shows the session idle
   *. Applied, or handed back to the binding by `endHold`; never both.
   */
  private heldResult: { result: HoldResult; since: number } | null = null;
  /** `callerAdmitted` when sessionStart fired: its injections survive the initial prompt */
  private startCallerSeq = 0;

  private magmux: ChildProcess | null = null;
  private watcher: ChildProcess | null = null;
  private client: MagmuxClient | null = null;
  private panePidValue: number | null = null;
  private stderrHead = "";
  private paneClosed = false;
  private paneExited = false;
  /** A liveness exit is asking magmux for the code; the exit path waits for the answer. */
  private exitCodeQuery = false;
  private reaping = false;
  private fastReap = false;
  private reapPromise: Promise<void> | null = null;
  private reconnecting = false;

  private depth = 0;
  private stepFrom: SlotState | null = null;
  private lastPollAt = 0;
  private framePending = false;
  private lastLivenessAt = 0;
  private ticker: ReturnType<typeof setInterval> | null = null;
  private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
  private changeTimer: ReturnType<typeof setTimeout> | null = null;
  private lastChangeAt = 0;
  private lastChangeState: SlotState = "STARTING";

  constructor(
    o: PaneSessionOptions,
    ids: { paneId: string; sockPath: string; root: string; ctlDir: string; turnDir: string }
  ) {
    this.o = o;
    this.paneId = ids.paneId;
    this.sockPath = ids.sockPath;
    this.root = ids.root;
    this.ctlDir = ids.ctlDir;
    this.turnDir = ids.turnDir;
    this.identity = { paneId: ids.paneId, sessionUuid: o.sessionUuid, ctlDir: ids.ctlDir };
    this.shape = o.shape;
    const size = launchSize(o);
    this.desiredSize = size;
    // magmux sizes the pane from COLUMNS/LINES at launch, so the launch size is applied
    this.appliedSize = { ...size };
    this.screen = emptyScreen(size.cols, size.rows);
    this.initialPending = !!o.initialPrompt;
    this.hooks = o.hooks ?? null;
    this.q = emptyQueueState(this.hooks?.maxConsecutive ?? DEFAULT_MAX_CONSECUTIVE);
    if (o.initialPrompt) this.q.items.push({ kind: "caller", text: o.initialPrompt });
    this.hooks?.attach?.({
      queueInjections: (items) => this.step(() => this.queueHookInjections(items)),
    });
    this.secondaryQuietMs = o.timings?.secondaryQuietMs ?? SECONDARY_QUIET_MS;
    this.corroborationMs = o.timings?.corroborationMs ?? CORROBORATION_MS;
    this.follower = new TranscriptFollower(
      o.transcriptPath,
      join(o.transcriptPath.replace(/\.jsonl$/, ""), "subagents")
    );
    // the same environment the transcript path is derived from
    this.registry = new SessionRegistry({
      configDir: claudeConfigDir(o.parentEnv ?? process.env),
      sessionUuid: o.sessionUuid,
    });
    this.ready = new Promise((r) => {
      this.resolveReady = r;
    });
    this.terminal = new Promise((r) => {
      this.resolveTerminal = r;
    });
  }

  /* ───────────────────────────── start ───────────────────────────── */

  /** Spawn order (X-L4): record → watcher → magmux → magmux.pid/record → dial → watch. */
  async start(input: {
    magmuxBinary: string;
    env: Record<string, string>;
    cwd: string;
  }): Promise<void> {
    const recordPath = recordPathOf(this.root, this.paneId);
    try {
      this.watcher = spawnPaneWatcher({
        paneId: this.paneId,
        sessionUuid: this.o.sessionUuid,
        ctlDir: this.ctlDir,
        sockPath: this.sockPath,
        recordPath,
        turnDir: this.turnDir,
        sockRoot: this.root,
      });
    } catch (e) {
      // a registered session must still reach a terminal state, or it stays counted
      // (livePaneCount) with its record and dirs on disk until the owner exits
      return this.spawnFailed(e);
    }
    updateRecord(this.root, this.paneId, { watcherPid: this.watcher.pid ?? null });
    let proc: ChildProcess | null = null;
    try {
      proc = spawnPaneMagmux({
        binary: input.magmuxBinary,
        paneId: this.paneId,
        sockRoot: this.root,
        ctlDir: this.ctlDir,
        cwd: input.cwd,
        env: input.env,
        sessionUuid: this.o.sessionUuid,
        transcriptPath: this.o.transcriptPath,
      });
    } catch (e) {
      return this.spawnFailed(e);
    }
    if (!proc.pid) return this.spawnFailed(new Error("magmux did not start"));
    this.magmux = proc;
    try {
      writeFileSync(join(this.ctlDir, "magmux.pid"), `${proc.pid}\n`, { mode: 0o600 });
    } catch {
      // the record carries it too
    }
    updateRecord(this.root, this.paneId, { magmuxPid: proc.pid });
    proc.stderr?.setEncoding("utf8");
    proc.stderr?.on("data", (d: string) => this.onStderr(d));
    proc.on("exit", (code, sig) => this.onMagmuxExit(code, sig));
    this.ticker = setInterval(() => this.step(() => this.evaluate()), TICK_MS);
    this.gateTimer = setInterval(() => this.pollGate(), GATE_POLL_MS);
    if (this.o.timeoutMs !== undefined)
      this.timeoutTimer = setTimeout(
        () => this.step(() => this.fire("timeout")),
        Math.max(0, this.o.timeoutMs)
      );
    await this.connectFirst();
  }

  /**
   * R3-M1: magmux could not be spawned. The terminal transition's reap does the "spawn
   * failed" reap: no magmux and no group to signal, so it removes the record and the dirs
   * and ends the watcher with `done`.
   */
  private spawnFailed(e: unknown): void {
    const msg = e instanceof Error ? e.message : String(e);
    this.step(() => this.fire("pane_lost", { detail: `magmux spawn failed: ${msg}` }));
  }

  private async connectFirst(): Promise<void> {
    let client: MagmuxClient;
    try {
      client = await MagmuxClient.connect(this.sockPath, {
        timeoutMs: 5000,
        alive: () => alive(this.magmux),
      });
    } catch (e) {
      const err = e as MagmuxConnectError;
      this.step(() =>
        this.fire("pane_lost", {
          detail: `cannot connect to ${this.sockPath}: ${err.message}${this.stderrHead ? `; magmux: ${this.stderrHead.trim()}` : ""}`,
        })
      );
      return;
    }
    await this.attach(client, false);
  }

  /** Subscribe a fresh connection: capabilities, list (dead pane?), watch. */
  private async attach(client: MagmuxClient, reconnect: boolean): Promise<void> {
    if (isTerminalPhase(this.phase) && this.reaping) {
      client.close();
      return;
    }
    client.on("snapshot", (e) => this.onSnapshot(e));
    client.on("frame", (f: MagmuxFrame) => this.onFrame(f));
    client.on("exit", (e) => void this.onPaneExit(e));
    client.on("pane_closed", (e) => {
      if (e?.pane === 0) this.paneClosed = true;
    });
    client.on("disconnected", () => this.onDisconnected(client));
    const caps = await client.request<{ version?: string; protocol?: number; verbs?: unknown }>({
      type: "capabilities",
    });
    // The resize flag is set BEFORE this.client: a resize arriving in between sees a
    // disconnected session (stored, pending), never a connected one without the op.
    this.supportsResize =
      caps.ok && Array.isArray(caps.result.verbs) && caps.result.verbs.includes("resize");
    // dropped while asking: `disconnected` has already started the redial
    if (client.isClosed) return;
    this.client = client;
    // no gate reading is trusted on this connection until its binding check passes
    this.gateTrusted = false;
    this.gate = null;
    const magmuxVersion = caps.ok ? String(caps.result.version ?? "") : "";
    if (caps.ok) {
      const v = magmuxVersion;
      if (caps.result.protocol !== 1 || !versionAtLeast(v, MIN_MAGMUX_VERSION)) {
        this.step(() =>
          this.fire("pane_lost", {
            detail: `magmux_unavailable: magmux ${v || "?"} protocol ${caps.result.protocol ?? "?"}; panes need >= ${MIN_MAGMUX_VERSION}, protocol 1`,
          })
        );
        return;
      }
    }
    // a size set while disconnected, or one whose reply was lost, is applied now
    this.lastSentSize = null;
    if (this.supportsResize && !samePaneSize(this.appliedSize, this.desiredSize)) this.kickResize();
    await client.request({ type: "watch", pane: 0, mode: "frames", fps: WATCH_FPS });
    // An `exit` pushed before this connection subscribed (a child that dies in its first
    // milliseconds, or one that exited in a reconnect gap) is only visible in `list`.
    const list = await client.request<{ panes?: Array<Record<string, unknown>> }>({ type: "list" });
    const p0 = list.ok ? list.result.panes?.find((p) => p.pane === 0) : undefined;
    if (typeof p0?.pid === "number" && !this.panePidValue) this.setPanePid(p0.pid);
    if (p0?.dead === true && !this.paneExited) {
      if (!reconnect) await this.nextFrame(500); // let the keyframe land: the final screen decides agent_rejected
      void this.onPaneExit({ exitCode: p0.exitCode ?? null, lastLine: "" });
      return;
    }
    if (!this.verifyGateBinding(client, list, magmuxVersion) || !list.ok) return;
    this.gateTrusted = true;
    this.onGateList(client, list.result);
  }

  /**
   * The binding check (architecture-v2 R1.0), on every attach: magmux's input gate is
   * trusted only for a pane it bound BY NAME to this session's id and transcript. Anything
   * else fails the pane; claudish never falls back to magmux's transcript discovery.
   * True only when the gate of this connection may be read.
   */
  private verifyGateBinding(
    client: MagmuxClient,
    list: MagmuxReply<{ panes?: Array<Record<string, unknown>> }>,
    magmuxVersion: string
  ): boolean {
    // dropped while asking: the redial attaches again and re-checks
    if (client.isClosed || isTerminalPhase(this.phase)) return false;
    if (!list.ok) {
      this.step(() =>
        this.fire("pane_lost", {
          detail: `input_gate_unbound: magmux ${magmuxVersion || "?"} list failed (${list.code}: ${list.error}), so the binding of pane 0 is unknown`,
        })
      );
      return false;
    }
    // no pane 0: it is gone, and the exit path owns that
    if (!list.result.panes?.some((p) => p.pane === 0)) return false;
    const check = checkGateBinding(list.result, {
      sessionUuid: this.o.sessionUuid,
      transcriptPath: this.o.transcriptPath,
      magmuxVersion,
    });
    if (!check.ok) {
      this.step(() => this.fire("pane_lost", { detail: check.detail }));
      return false;
    }
    return true;
  }

  /* ───────────────────────────── the input gate ───────────────────────────── */

  /**
   * One `list` on the current connection, unless one is in flight (architecture-v2 §6.1).
   * Only after this connection's binding check passed: a reading from an unbound pane could
   * describe another session's dialog.
   */
  private pollGate(): void {
    const c = this.client;
    if (!c || !this.gateTrusted || this.gateInFlight) return;
    if (this.reaping || isTerminalPhase(this.phase)) return;
    this.gateInFlight = true;
    void c
      .request<{ panes?: Array<Record<string, unknown>> }>({ type: "list" }, GATE_REPLY_MS)
      .then((r) => {
        this.gateInFlight = false;
        if (r.ok) this.onGateList(c, r.result);
      });
  }

  /**
   * A `list` reply: pane 0's `input` is the gate reading; its `pid`/`dead` back up the
   * `exit` event. A reading that changed `ready` or `reason` is evaluated at once rather
   * than at the next tick.
   */
  private onGateList(c: MagmuxClient, result: { panes?: Array<Record<string, unknown>> }): void {
    if (c !== this.client || !this.gateTrusted || isTerminalPhase(this.phase)) return;
    const now = Date.now();
    const p0 = result.panes?.find((p) => p.pane === 0);
    if (typeof p0?.pid === "number" && !this.panePidValue) this.setPanePid(p0.pid);
    if (p0?.dead === true && !this.paneExited) {
      if (this.gateDeadSince === 0) this.gateDeadSince = now;
      else if (now - this.gateDeadSince >= GATE_DEAD_BACKSTOP_MS) {
        this.anomaly("exit_event_missing");
        void this.onPaneExit({ exitCode: p0.exitCode ?? null, lastLine: "" });
        return;
      }
    } else this.gateDeadSince = 0;
    const prev = this.gate;
    this.gate = parseGateInput(result, now);
    const g = this.gate;
    if (prev?.ready !== g?.ready || prev?.reason !== g?.reason) this.step(() => this.evaluate());
  }

  /** The gate's latest reading, or null when unknown: disconnected, unbound, or stale. */
  private gateNow(): GateInput | null {
    const g = this.gate;
    if (!g || !this.client || !this.gateTrusted) return null;
    return Date.now() - g.receivedAt <= GATE_STALE_MS ? g : null;
  }

  /* ───────────────────────────── magmux events ───────────────────────────── */

  private onStderr(d: string): void {
    if (this.stderrHead.length < 8192) this.stderrHead += d.slice(0, 8192 - this.stderrHead.length);
    const fatal = d.split("\n").find((l) => FATAL_MAGMUX_STDERR.test(l));
    if (fatal) this.step(() => this.fire("pane_lost", { detail: fatal.trim() }));
  }

  private onSnapshot(e: { panes?: Array<{ pane?: number; pid?: number }> }): void {
    const p0 = e?.panes?.find((p) => p.pane === 0);
    if (p0?.pid && !this.panePidValue) this.setPanePid(p0.pid);
  }

  private setPanePid(pid: number): void {
    this.panePidValue = pid;
    updateRecord(this.root, this.paneId, { panePid: pid });
    // never a synchronous ps on the event loop: a stalled loop gets our socket dropped as a slow consumer
    void readProcessTableAsync().then((t) => {
      if (t) refreshGroupOf(this, t);
    });
  }

  private onFrame(f: MagmuxFrame): void {
    if (f.pane !== undefined && f.pane !== 0) return;
    const seq = this.screen.seq;
    this.screen = applyFrame(this.screen, f);
    if (this.screen.seq !== seq && !this.inResizeQuiet(this.screen.changedAt))
      this.activityChangedAt = this.screen.changedAt;
    this.framePending = true;
    if (!this.claudeCodeVersion) {
      const m = this.screen.lines.join("\n").match(/Claude Code v(\d+\.\d+\.\d+)/);
      if (m) this.claudeCodeVersion = m[1] ?? null;
    }
    this.step(() => this.evaluate());
  }

  private onDisconnected(client: MagmuxClient): void {
    if (this.client === client) {
      this.client = null;
      // a reading from before the drop says nothing about now
      this.gate = null;
      this.gateTrusted = false;
    }
    if (this.reaping || !alive(this.magmux)) return;
    if (isTerminalPhase(this.phase)) return;
    void this.reconnect();
  }

  /** magmux is alive (it keeps panes when a client leaves): redial with backoff while it lives. */
  private async reconnect(): Promise<void> {
    if (this.reconnecting) return;
    this.reconnecting = true;
    let delay = 50;
    let enoent = 0;
    try {
      while (alive(this.magmux) && !this.reaping && !isTerminalPhase(this.phase)) {
        try {
          const c = await MagmuxClient.dial(this.sockPath);
          this.anomaly("socket_reconnected");
          await this.attach(c, true);
          return;
        } catch (e) {
          enoent = (e as MagmuxConnectError).errno === "ENOENT" ? enoent + 1 : 0;
          if (enoent >= 20) {
            this.anomaly("socket_lost");
            return;
          }
        }
        await Bun.sleep(delay);
        delay = Math.min(1000, delay * 2);
      }
    } finally {
      this.reconnecting = false;
    }
  }

  private onMagmuxExit(code: number | null, sig: NodeJS.Signals | null): void {
    if (this.reaping || isTerminalPhase(this.phase)) return;
    this.step(() => {
      this.pollFollower(true);
      const detail = `magmux exited (${sig ?? `code ${code}`}) without reporting the pane's exit${this.stderrHead ? `; stderr: ${this.stderrHead.trim().slice(0, 500)}` : ""}`;
      // §7.3 step 6 (M-1a): a held turn is concluded on its settled chain. A one-shot
      // gets its verdict; an interactive session goes to IDLE and then, as from IDLE today,
      // reports the lost pane.
      if (this.phase === "SETTLING") {
        this.endHold("exit");
        this.conclude(`magmux exited (${sig ?? `code ${code}`})`);
        if (!isTerminalPhase(this.phase)) this.fire("pane_lost", { detail });
        return;
      }
      if (this.phase === "RUNNING" && this.exitSettle()) {
        this.applyExitPath(null);
        return;
      }
      this.fire("pane_lost", { detail });
    });
  }

  /** The pane child exited (magmux `exit` event, or a dead pane found on reconnect). */
  private async onPaneExit(e: { exitCode?: unknown; lastLine?: unknown }): Promise<void> {
    if (this.paneExited || isTerminalPhase(this.phase)) return;
    const code = typeof e?.exitCode === "number" ? e.exitCode : null;
    const lastLine = typeof e?.lastLine === "string" ? e.lastLine : "";
    // The code is stored with the exit itself, not after the capture below: a tick that
    // settles the turn inside that window concludes with this code (H-27).
    this.paneExited = true;
    this.exitCode = code;
    this.exitLastLine = lastLine;
    // The final screen, with scrollback, so a long agent list cannot hide the refusal (L8).
    const slow = this.o.timings?.exitCaptureDelayMs;
    if (slow) await Bun.sleep(slow);
    if (this.client) {
      const cap = await this.client.request<MagmuxCapture>(
        { type: "capture", pane: 0, offset: 200 },
        1000
      );
      if (
        cap.ok &&
        agentRejectedLine(cap.result.text ?? "") &&
        !agentRejectedLine(screenText(this.screen))
      )
        this.exitScrollback = cap.result.text ?? "";
    }
    this.step(() => this.applyExitPath(code));
  }

  /* ───────────────────────────── the step ───────────────────────────── */

  private wire(): SlotState {
    return wireState(this.phase, this.initialDelivery);
  }

  /** Run one event-processing step; report the NET wire change once. */
  private step(fn: () => void): void {
    if (this.depth === 0) this.stepFrom = this.wire();
    this.depth++;
    try {
      fn();
    } finally {
      this.depth--;
    }
    if (this.depth > 0) return;
    const from = this.stepFrom as SlotState;
    const to = this.wire();
    if (from !== to) {
      try {
        this.o.onTransition?.({ from, to, at: iso(Date.now()), snap: this.snapshot() });
      } catch {
        // an owner's callback must not break the session
      }
    }
    if (to !== "STARTING" && !this.readySettled) {
      this.readySettled = true;
      this.resolveReady();
    }
    this.scheduleChange();
  }

  private scheduleChange(): void {
    if (!this.o.onChange || this.changeTimer) return;
    const wait = Math.max(0, this.lastChangeAt + 250 - Date.now());
    this.changeTimer = setTimeout(() => {
      this.changeTimer = null;
      this.lastChangeAt = Date.now();
      const prev = this.lastChangeState;
      const snap = this.snapshot();
      this.lastChangeState = snap.state;
      try {
        this.o.onChange?.(snap, prev);
      } catch {
        // ignore
      }
    }, wait);
  }

  private fire(ev: PhaseEvent, info: { reason?: FailureReason; detail?: string } = {}): boolean {
    const next = nextPhase(this.phase, ev);
    if (!next) {
      this.anomaly(`illegal_transition:${this.phase}:${ev}`);
      return false;
    }
    this.phase = next;
    const reason = info.reason ?? EVENT_REASON[ev];
    // `detail` often carries the final screen rows: redacted HERE, once, so no owner can
    // persist or forward a credential the child printed (meta.json, output.log, frames)
    const detail = info.detail === undefined ? undefined : redactSecrets(info.detail);
    if (isTerminalPhase(next)) {
      this.reason = next === "COMPLETED" ? null : (reason ?? this.reason);
      if (detail !== undefined) this.detail = detail;
      this.onTerminal();
    } else if (detail !== undefined) this.detail = detail;
    return true;
  }

  private anomaly(key: string): void {
    const n = this.anomalies.get(key);
    if (n !== undefined) this.anomalies.set(key, n + 1);
    else if (this.anomalies.size < MAX_ANOMALY_KEYS) this.anomalies.set(key, 1);
  }

  /* ───────────────────────────── evaluation ───────────────────────────── */

  /**
   * Poll on a frame (debounced 250 ms) and on a 1 s backstop (FR4). The returned view
   * can be that old: a step about to type into the pane reads with `force`.
   */
  private pollFollower(force = false): TranscriptView {
    const now = Date.now();
    const since = now - this.lastPollAt;
    const debounce = this.t("pollDebounceMs", TICK_MS);
    if (
      force ||
      (this.framePending && since >= debounce) ||
      since >= this.t("pollBackstopMs", POLL_BACKSTOP_MS)
    ) {
      this.follower.poll();
      this.lastPollAt = now;
      this.framePending = false;
    }
    const view = this.follower.view();
    const off = view.current?.lastChatOffset ?? null;
    if (off !== this.lastChatOffset) {
      this.lastChatOffset = off;
      this.lastChatSeenAt = now;
    }
    return view;
  }

  private evaluate(): void {
    if (isTerminalPhase(this.phase)) return;
    if (transcriptSavingOff(this.screen)) this.follower.markSavingOff();
    const view = this.pollFollower();
    this.checkLiveness();
    const phase = this.phase;
    switch (phase) {
      case "BOOTING":
        this.evalBoot();
        break;
      case "ADMITTING":
        this.evalAdmission(view);
        break;
      case "RUNNING":
      case "QUESTION":
      case "PERMISSION":
        this.evalRunning(view);
        break;
      case "SETTLING":
        this.evalSettling(view);
        break;
      case "IDLE":
        this.evalIdle(view);
        break;
      case "COMPLETED":
      case "FAILED":
      case "CANCELLED":
      case "TIMEOUT":
      case "EMPTY":
        break;
      default:
        assertNever(phase);
    }
    this.checkRegistry();
    this.pump();
  }

  /**
   * Telemetry only (pane-session.md, "The session registry"; architecture-v2 §6.4): compare
   * Claude Code's own session record with magmux's input gate (and, for working, the
   * screen), and the gate with the screen readers it is replacing; count each disagreement
   * once at its onset. No decision reads the registry; these counts decide, later, whether
   * the screen cross-checks can go.
   */
  private checkRegistry(): void {
    const now = Date.now();
    if (now - this.lastRegistryReadAt < REGISTRY_READ_MS) return;
    this.lastRegistryReadAt = now;
    const rec = this.registry.read();
    this.registryRec = rec;
    if (rec) this.registryEverSeen = true;
    if (
      !this.registryEverSeen &&
      this.bootReadyAtMs !== null &&
      now - this.bootReadyAtMs >= REGISTRY_MISSING_MS
    ) {
      this.disagree("registry_record_missing", true, now, 0);
    }
    const status = rec?.status ?? null;
    if (status !== null && !KNOWN_STATUSES.has(status))
      this.disagree(`registry_status_unknown:${status.slice(0, 32)}`, true, now, 0);
    if (!this.client) return; // a stale screen proves nothing
    const idle = status === "idle";
    this.disagree(
      "registry_idle_screen_working",
      this.phase === "RUNNING" && idle && isWorking(this.screen),
      now
    );
    // an unknown gate reading is not a disagreement, and does not end one either
    const g = this.gateNow();
    if (!g) return;
    // the `--agent` border signature, and the canary for magmux missing the box at a new width
    this.disagree(
      "registry_idle_gate_starting",
      this.phase === "BOOTING" && idle && (g.reason === "starting" || g.reason === "no_input_box"),
      now,
      REGISTRY_GATE_BOOT_DISAGREE_MS
    );
    this.disagree("registry_waiting_gate_no_dialog", status === "waiting" && g.ready, now);
    this.disagree(
      "gate_dialog_registry_not_waiting",
      g.dialog !== null && RUNTIME_DIALOG_KINDS.has(g.dialog) && (idle || status === "busy"),
      now
    );
    this.disagree("gate_ready_box_not_located", g.ready && locateBox(this.screen) === null, now);
    // canary for magmux's dialog markers drifting from claudish's closed list
    this.disagree(
      "gate_dialog_screen_unrecognised",
      (g.dialog === "permission" || g.dialog === "plan" || g.dialog === "question") &&
        choiceDialog(this.screen) === null,
      now
    );
  }

  private disagree(key: string, holds: boolean, now: number, forMs = REGISTRY_DISAGREE_MS): void {
    if (!holds) {
      this.disagreeSince.delete(key);
      this.disagreeCounted.delete(key);
      return;
    }
    const since = this.disagreeSince.get(key) ?? now;
    this.disagreeSince.set(key, since);
    if (now - since >= forMs && !this.disagreeCounted.has(key)) {
      this.disagreeCounted.add(key);
      this.anomaly(key);
    }
  }

  /**
   * While disconnected, the pane's liveness is `kill(panePid, 0)` every second (X-M12).
   *
   * ESRCH means magmux has already reaped the child, so magmux knows its exit code even though
   * our socket is gone. Before finishing, a bounded query asks it (`exitCodeFromMagmux`); the
   * code is then stored together with `paneExited`, as `onPaneExit` does (H-27). Unreachable or
   * silent, the exit goes on without a code, exactly as before.
   */
  private checkLiveness(): void {
    if (this.client || !this.panePidValue || this.paneExited || this.exitCodeQuery) return;
    const now = Date.now();
    if (now - this.lastLivenessAt < 1000) return;
    this.lastLivenessAt = now;
    try {
      process.kill(this.panePidValue, 0);
    } catch (e) {
      if ((e as NodeJS.ErrnoException).code === "ESRCH") {
        this.exitCodeQuery = true;
        void this.exitCodeFromMagmux().then((code) => {
          this.exitCodeQuery = false;
          // a redial that attached meanwhile saw the dead pane and took the exit path with its code
          if (this.paneExited || isTerminalPhase(this.phase)) return;
          this.paneExited = true;
          this.exitCode = code;
          this.step(() => this.applyExitPath(code));
        });
      }
    }
  }

  /**
   * Pane 0's exit code from magmux over a fresh connection, or null when magmux cannot be
   * reached, does not answer, or does not report the pane dead with a numeric code within
   * EXIT_CODE_QUERY_MS. Its own dial loop, not the redial loop: that one backs off to a second
   * between attempts, and its attach does far more than this needs. Never throws.
   */
  private async exitCodeFromMagmux(): Promise<number | null> {
    const deadline = Date.now() + EXIT_CODE_QUERY_MS;
    const left = () => deadline - Date.now();
    const client = await this.dialWithin(left);
    if (!client) return null;
    try {
      // magmux marks the pane dead once it has reaped the child; ESRCH says it has, but the
      // mark may trail the reap by a moment, so ask again until the bound.
      while (left() > 0) {
        const r = await client.request<{ panes?: Array<Record<string, unknown>> }>(
          { type: "list" },
          Math.max(1, left())
        );
        if (!r.ok) return null;
        const p0 = r.result.panes?.find((p) => p.pane === 0);
        if (!p0) return null;
        if (p0.dead === true) return typeof p0.exitCode === "number" ? p0.exitCode : null;
        await Bun.sleep(Math.min(EXIT_CODE_RETRY_MS, Math.max(0, left())));
      }
      return null;
    } finally {
      client.close();
    }
  }

  /** A fresh magmux connection, redialled every EXIT_CODE_RETRY_MS while `left()` is positive. */
  private async dialWithin(left: () => number): Promise<MagmuxClient | null> {
    while (left() > 0 && !this.reaping && !isTerminalPhase(this.phase)) {
      try {
        // a connect that never completes must not outlive the bound either
        const dial = MagmuxClient.dial(this.sockPath);
        const client = await Promise.race([dial, Bun.sleep(Math.max(0, left())).then(() => null)]);
        if (!client) void dial.then((late) => late.close()).catch(() => {});
        return client;
      } catch {
        await Bun.sleep(Math.min(EXIT_CODE_RETRY_MS, Math.max(0, left())));
      }
    }
    return null;
  }

  private t(key: keyof NonNullable<PaneSessionOptions["timings"]>, dflt: number): number {
    return this.o.timings?.[key] ?? dflt;
  }

  /** The owner's admission bound, else the test seam, else `ADMIT_TIMEOUT_MS`. */
  private admitTimeoutMs(): number {
    return this.o.admitTimeoutMs ?? this.o.timings?.admitTimeoutMs ?? ADMIT_TIMEOUT_MS;
  }

  /**
   * An admission's bound. `admitTimeoutMs` bounds only the CREATED prompt's admission, as its
   * option says; the test-only `timings.admitTimeoutMs` bounds only a LATER one (an injected
   * turn, H-13 … H-15), for owners that do not pass `admitTimeoutMs`. A bound must leave room
   * for one gated send (`readyTimeoutFor`), else no attempt is made at all.
   */
  private admitBoundMs(initial: boolean): number {
    if (initial) return this.o.admitTimeoutMs ?? ADMIT_TIMEOUT_MS;
    return this.o.timings?.admitTimeoutMs ?? ADMIT_TIMEOUT_MS;
  }

  /**
   * Boot (architecture-v2 §6.2): ready is magmux's `input.ready`, which already requires the
   * box and a raw terminal both still for 1 s and Claude Code's boot stdin reset seen (or
   * 3.5 s since the terminal went raw). What blocks boot is the gate's dialog kind, named
   * from the screen's words only where the gate has no kind for it. Nothing is ever
   * accepted: no key is sent while booting.
   */
  private evalBoot(): void {
    const now = Date.now();
    const g = this.gateNow();
    if (g?.ready) {
      this.bootReady();
      return;
    }
    const staticFor = this.screen.seq === 0 ? 0 : now - this.screen.changedAt;
    const settled = staticFor >= this.t("bootStaticMs", BOOT_STATIC_MS);
    const block = g && settled ? this.bootBlock(g) : null;
    if (block) {
      this.fire(block.ev, { detail: block.detail });
      return;
    }
    if (now - this.startedAtMs >= (this.o.bootTimeoutMs ?? BOOT_TIMEOUT_MS)) {
      const blocked =
        this.screen.seq > 0 &&
        settled &&
        (g?.reason?.startsWith("dialog:") === true ||
          nameBootScreen(this.screen).kind !== "booting");
      const gate = g
        ? `gate: ${g.reason ?? "ready"}${g.detail ? ` (${g.detail})` : ""}`
        : "gate: unknown";
      this.fire("boot_deadline", {
        reason: blocked ? "boot_blocked" : "boot_timeout",
        detail: `${screenTailOf(this.screen)}\n${gate}`,
      });
    }
  }

  /**
   * A static boot screen the gate does not call ready: a boot dialog kind fails
   * `first_run_dialog` with the dialog's words; otherwise the screen names it — a named
   * first-run marker is `first_run_dialog` (magmux files a reworded boot dialog under
   * `select`); vim mode, `select` or another dialog kind is `boot_blocked`; a reason with no
   * kind (`starting`, `no_input_box`, …) blocks only on choice markers (`Press Enter to
   * continue`, the unnamed MCP-server prompt), which magmux has no kind for.
   * null: nothing names a blocking screen, so boot keeps waiting for its deadline.
   */
  private bootBlock(g: GateInput): { ev: "boot_dialog" | "boot_blocked"; detail: string } | null {
    if (g.dialog && BOOT_DIALOG_KINDS.has(g.dialog))
      return { ev: "boot_dialog", detail: dialogText(this.screen) };
    const named = nameBootScreen(this.screen);
    // the gate is not ready and the screen is static: a named first-run dialog is that dialog
    if (named.kind === "dialog") return { ev: "boot_dialog", detail: named.text };
    if (g.reason === "vim_mode")
      return { ev: "boot_blocked", detail: "vim editing mode is on (-- INSERT -- under the box)" };
    if (g.reason?.startsWith("dialog:"))
      return { ev: "boot_blocked", detail: screenText(this.screen) };
    if (named.kind === "choice" && g.reason !== null && GATE_KINDLESS_REASONS.has(g.reason))
      return { ev: "boot_blocked", detail: named.text };
    return null;
  }

  private bootReady(): void {
    this.bootReadyAtMs = Date.now();
    const head = this.q.items.find((i) => i.kind === "caller");
    if (!head || isControl(head.text)) {
      this.fire("boot_ready_idle");
      this.fireSessionStart();
      return;
    }
    const initial = this.initialPending;
    this.initialPending = false;
    this.initialDelivery = initial;
    this.q.items = this.q.items.filter((i) => i !== head);
    this.fire("boot_ready_admit");
    this.startAdmission(head, initial);
    this.fireSessionStart();
  }

  /** §7.3: right after the initial prompt's admission started (or boot found no prompt). */
  private fireSessionStart(): void {
    if (!this.hooks) return;
    this.startCallerSeq = this.q.callerAdmitted;
    try {
      this.hooks.fireStart();
    } catch {
      // a binding's failure must not break the session
    }
  }

  /** IDLE (or boot-ready) with a queued item: admit synchronously, then deliver. */
  private pump(): void {
    if (isTerminalPhase(this.phase) || this.admission) return;
    if (this.q.items.length === 0) return;
    const d = nextQueueDecision(this.q, Date.now(), this.phase, this.canDeliver);
    if (this.phase === "IDLE") {
      // a hook item is typed only on current evidence; it stays queued until then
      if (d.deliver?.kind === "hook" && !this.idleForHookItem()) return;
      this.q.items = d.remaining;
      this.dropHookItems(d.drop);
      const item = d.deliver;
      if (!item) return;
      if (item.kind === "caller" && isControl(item.text)) {
        this.exitRequested = true;
        void this.submitControl(item.text.trim());
        return;
      }
      this.fire("admit");
      this.startAdmission(item, false);
      return;
    }
    // A queue holding only hook items never presses Esc (§7.2).
    if (
      (this.phase === "QUESTION" || this.phase === "PERMISSION") &&
      d.pressEscape &&
      this.escapeArmed &&
      this.escapeSentAt === null
    ) {
      // Esc declines the dialog AND interrupts the turn; it settles through path I (D17).
      this.escapeArmed = false;
      this.escapeSentAt = Date.now();
      void this.key("escape");
    }
  }

  /**
   * What the interactive driver's gate reads, read NOW. The transcript first: a
   * re-wake written since the last tick moves the session to RUNNING (`evalIdle`). Then
   * the screen: the box drawn and empty, no menu, no dialog, no working row.
   */
  private idleForHookItem(): boolean {
    this.evalIdle(this.pollFollower(true));
    return this.phase === "IDLE" && this.screenIdle();
  }

  /**
   * The box is drawn and empty with no menu, no dialog and no working row. The box is the
   * one located by the cursor (any terminal width), else the rule-drawn one; a dialog is the
   * input gate's (`dialog:<kind>`), else the screen's. The gated send that follows still
   * waits for the gate's own readiness.
   */
  private screenIdle(): boolean {
    if (!this.client) return false;
    if (this.gateNow()?.dialog) return false;
    const s = this.screen;
    const located = locateBox(s);
    const drawn = located ? null : inputBox(s);
    const top = located?.top ?? drawn?.top;
    if (top === undefined) return false;
    const text = located ? locatedBoxText(s, located) : (drawn?.text ?? "");
    if (text !== "" || menuAbove(s.lines, top).menuOpen) return false;
    return !hasChoiceDialog(s) && !isWorking(s);
  }

  /**
   * The merged hook text can be delivered: a plain line, or a file the child can Read.
   * Never a slash command: hook text goes as typed text or a file, not through
   * the command or control path a caller's `/model` or `/exit` takes.
   */
  private readonly canDeliver = (text: string): boolean =>
    !text.trimStart().startsWith("/") && deliveryRefusal(text, this.o.readAvailable) === null;

  private startAdmission(item: QueueItem, initial: boolean): void {
    const text = item.text;
    // §7.2 L1: both counters change here, when the item leaves the queue
    Object.assign(this.q, afterAdmission(this.q, item));
    if (item.kind === "caller") {
      this.chain = [];
      this.chainHead = null;
      this.hookTurns = 0;
      this.turnHookCaused = false;
    } else {
      this.hookTurns++;
      this.turnHookCaused = true;
      this.hooks?.noteDelivered?.(item);
      this.anomaly("hook_injection_delivered");
    }
    this.follower.poll();
    this.lastPollAt = Date.now();
    const offset = this.follower.size(); // mark BEFORE deliver: the single turn boundary
    const index = ++this.turnIndex;
    const plan = planDelivery(text, this.turnDir, index, this.o.readAvailable);
    this.currentDelivery = plan;
    this.turnSource = "transcript";
    this.screenTurn = null;
    this.rewakeOfSettled = false;
    this.settledChatOffset = null;
    this.turnAcceptedAt = null;
    this.witnessMissingCounted = false;
    this.abandonedIndex = null;
    if (plan.mode === "refused" || plan.mode === "control") {
      this.anomaly(`delivery_refused:${plan.mode === "refused" ? plan.reason : "control"}`);
      this.admission = null;
      if (item.kind === "hook") {
        this.hookAdmissionFailed(item);
        return;
      }
      this.fire(initial ? "admit_deadline" : "admit_abandoned", {
        detail: plan.mode === "refused" ? plan.reason : undefined,
      });
      return;
    }
    try {
      writeTurnFile(plan);
    } catch (e) {
      this.anomaly(`turn_file_failed:${e instanceof Error ? e.message : String(e)}`);
    }
    const delivery =
      (plan.mode === "file" || plan.mode === "command") &&
      plan.file &&
      plan.fileContent !== undefined
        ? { file: plan.file, text: plan.fileContent }
        : null;
    this.follower.openTurn({ index, offset, witness: plan.witness, delivery });
    const adm = newAdmission({
      index,
      item,
      text,
      plan,
      initial,
      bound: this.admitBoundMs(initial),
    });
    this.admission = adm;
    void this.runAdmission(adm);
  }

  /** This admission is still the live one: nothing accepted, expired or ended it meanwhile. */
  private admitting(adm: Admission): boolean {
    return this.admission === adm && this.phase === "ADMITTING";
  }

  /**
   * The admission loop (architecture-v2 §5.3, R1.4): at most one gated send in flight, each
   * sized so that its client timeout ends by the admission deadline, and every reply handled
   * by the exhaustive switch of `onSendOutcome`. magmux's gate presses Enter only on a box
   * holding exactly the line; claudish never reads the box to decide a retype, never resends
   * a SUBMIT whose reply was lost or that may have been submitted, and never accepts on the
   * screen. Claudish's own transcript witness accepts in `evalAdmission` whatever the loop is
   * doing ("the witness always wins"); the loop sees that at its next check and stops.
   *
   * The loop ends with no decision when Enter may have been pressed unproven
   * (`submittedUnproven`), when a stop row decided (`stopped`), or when no attempt fits
   * before the deadline; `evalAdmission` then expires the admission at its deadline.
   */
  private async runAdmission(adm: Admission): Promise<void> {
    try {
      while (this.admitting(adm) && adm.submittedUnproven === null && !adm.stopped) {
        if (Date.now() >= adm.deadline) return;
        if (adm.panel) {
          // a command opened a picker or panel: `panelStep` dismisses it, or hands it back
          await this.pause(adm, TICK_MS);
          continue;
        }
        if (!this.client || !this.gateTrusted) {
          await this.awaitTrustedClient(adm);
          continue;
        }
        // a stop row, an ended admission or a wait re-checks from the top of the loop
        if ((await this.beforeSend(adm)) !== "send") continue;
        if (!this.admitting(adm) || !(await this.attemptOnce(adm))) return;
      }
    } finally {
      adm.inFlight = false;
    }
  }

  /** Nothing is written while disconnected: the redial's attach re-checks the binding first. */
  private awaitTrustedClient(adm: Admission): Promise<void> {
    return this.waitFor(
      () => !this.admitting(adm) || (!!this.client && this.gateTrusted),
      Math.max(0, adm.deadline - Date.now())
    );
  }

  /**
   * One gated send of the admission's current step, and its outcome handled. False when no
   * attempt fits before the deadline, or the admission ended while the send was out.
   */
  private async attemptOnce(adm: Admission): Promise<boolean> {
    const c = this.client;
    if (!c) return true; // the loop waits for the redial
    const step = adm.step;
    const shape = sendShape(step, adm.line);
    const rt = readyTimeoutFor(step, adm.line, adm.deadline - Date.now());
    if (rt === null) return false;
    const timeout = sendBudgetMs({ ...shape.budget, readyTimeoutMs: rt }) + SEND_CLIENT_SLACK_MS;
    const sentAt = Date.now();
    adm.inFlight = true;
    adm.attempts++;
    let reply: MagmuxReply;
    try {
      reply = await c.request({ ...shape.msg, readyTimeoutMs: rt }, timeout);
    } finally {
      adm.inFlight = false;
    }
    const out = classifySendReply(reply);
    adm.last = out;
    this.noteLastSend(out, adm.attempts);
    // the witness accepted it, or the session ended, while the send was out
    if (!this.admitting(adm)) return false;
    await this.onSendOutcome(adm, out, step, { client: c, until: sentAt + timeout });
    return true;
  }

  /**
   * One gated reply → what the admission does next (architecture-v2 §5.2, R1.1-R1.5). The
   * switch is exhaustive over the closed `SendOutcome`; `input-gate.ts` only translates.
   */
  private async onSendOutcome(
    adm: Admission,
    out: SendOutcome,
    step: SubmitStep,
    sent: { client: MagmuxClient; until: number }
  ): Promise<void> {
    switch (out.kind) {
      case "accepted":
        this.onGateAccepted(adm, out);
        return;
      case "in_box":
        if (step !== "type") {
          // a send that carried an Enter answered as a TYPE: whether Enter was pressed is unknown
          this.anomaly("send_unexpected:in_box");
          this.stopAdmission(adm, "magmux answered in_box to a send that carried an Enter");
          return;
        }
        if (out.retyped) this.anomaly(`gate_retyped:${out.retypeCause ?? "unknown"}`);
        await this.menuCheck(adm);
        adm.step = "enter";
        return;
      case "busy":
        await this.onBusy(adm, out, step);
        return;
      case "not_accepted":
        await this.onNotAccepted(adm, out, step);
        return;
      case "bad_request":
        // nothing was written: a claudish bug (planDelivery emits printable text only)
        this.anomaly("send_bad_request");
        this.stopAdmission(adm, `send_bad_request: ${out.error}`);
        return;
      case "reply_lost":
        this.anomaly("send_reply_lost");
        if (step === "type") {
          // R1.5.3: a TYPE presses no Enter, so its text is cleared and typed again, once the
          // delivery behind the lost reply can no longer be typing
          adm.lostType = sent;
          markClearFirst(adm);
          return;
        }
        // magmux carries the delivery on, Enter included: never resent; the witness decides
        adm.submittedUnproven = "reply_lost";
        return;
      case "unsent":
        // never written: the next attempt waits for the redial
        await this.pause(adm, BUSY_RETRY_MS);
        return;
      case "pane_gone":
        // the exit path decides (`onPaneExit`); no further attempt
        adm.stopped = true;
        return;
      case "unexpected":
        this.anomaly(`send_unexpected:${out.code}`);
        this.stopAdmission(adm, `send_unexpected: ${out.code}${out.error ? `: ${out.error}` : ""}`);
        return;
      default:
        assertNever(out);
    }
  }

  /**
   * `ok`: history evidence (this pane's own screen) accepts at once; transcript evidence
   * only together with claudish's own witness (§5.6: until the named binding is trusted for
   * it, a transcript the gate read is not attributable on its own), else it is `unconfirmed`.
   */
  private onGateAccepted(adm: Admission, out: Extract<SendOutcome, { kind: "accepted" }>): void {
    if (out.accept === "resent_enter") this.anomaly("gate_resent_enter");
    if (out.accept === "submitted_by_other") this.anomaly("gate_submitted_by_other");
    if (out.retyped) this.anomaly(`gate_retyped:${out.retypeCause ?? "unknown"}`);
    if (out.dismissed.length > 0) this.anomaly("gate_dismissed_unexpected");
    if (out.evidence === "transcript") {
      this.anomaly("gate_transcript_evidence");
      if (!this.witnessNow()) {
        this.anomaly("gate_transcript_evidence_unwitnessed");
        adm.submittedUnproven = "unconfirmed";
        return;
      }
    }
    this.acceptAdmission(adm);
  }

  /** `busy`: Enter was NOT pressed. */
  private async onBusy(
    adm: Admission,
    out: Extract<SendOutcome, { kind: "busy" }>,
    step: SubmitStep
  ): Promise<void> {
    const reason = out.reason || "unknown";
    if (this.stopOnGateBlock(adm, reason, out.dialog)) return;
    if (out.dialog === "select" && step === "enter") {
      // the command's own Enter met a picker or panel: dismiss it (§5.4 `panelStep`)
      this.noteOnce(adm, "gate_dialog_at_admission:select");
      adm.panel = { showingSince: null, escaped: false, entered: false };
      return;
    }
    if (out.dialog) {
      // a re-woken turn owns the dialog; evalIdle/evalRunning see it
      this.noteOnce(adm, `gate_dialog_at_admission:${out.dialog}`);
    } else if (out.typed) {
      // the box may hold all or part of the text: the next send's precondition clears it
      this.anomaly("gate_typed_withheld");
      markClearFirst(adm);
    } else if (reason === "box_not_empty") {
      this.anomaly("gate_box_not_empty");
      markClearFirst(adm);
    } else {
      // starting, terminal_not_ready, no_input_box, typing_in_progress, queue_full, in_flight, …
      this.noteOnce(adm, `gate_busy:${reason}`);
    }
    await this.pause(adm, BUSY_RETRY_MS);
  }

  /**
   * The §5.2 stop rows a gate reason decides on its own, from a reply or from the published
   * view: a boot dialog kind (`first_run_dialog`) and vim mode. True when it stopped.
   */
  private stopOnGateBlock(adm: Admission, reason: string, dialog: GateDialogKind | null): boolean {
    if (dialog && BOOT_DIALOG_KINDS.has(dialog)) {
      // a question for the human: never a key, never accepted
      this.anomaly(`gate_boot_dialog:${dialog}`);
      this.stopAdmission(adm, dialogText(this.screen) || `busy ${reason}`, "first_run_dialog");
      return true;
    }
    if (reason === "vim_mode") {
      this.anomaly("gate_vim_mode");
      this.stopAdmission(adm, "busy vim_mode: vim editing mode is on (-- INSERT -- under the box)");
      return true;
    }
    return false;
  }

  /**
   * Revision 3 item 1: magmux answers `busy vim_mode` and `busy dialog:<kind>` only after the
   * send's WHOLE `readyTimeoutMs`, so before a send that types, the fresh published view is
   * read first, as R1.5.2 does for `box_not_empty`. Vim mode or a boot dialog stops the
   * admission with no send; a turn's own dialog (permission, question, plan) starts no send
   * until it leaves, within the deadline. A stale or missing reading decides nothing: the
   * send goes, and the gate decides.
   * `"send"`: go ahead; `"stopped"`: a stop row decided; `"waited"`: re-check from the top.
   */
  private async precheckGate(adm: Admission): Promise<"send" | "stopped" | "waited"> {
    const g = this.gateNow();
    if (!g || g.ready) return "send";
    if (this.stopOnGateBlock(adm, g.reason ?? "unknown", g.dialog)) return "stopped";
    const kind = g.dialog;
    if (kind !== "permission" && kind !== "question" && kind !== "plan") return "send";
    this.noteOnce(adm, `gate_dialog_at_admission:${kind}`);
    await this.waitFor(
      () => !this.admitting(adm) || this.gateNow()?.dialog !== kind,
      Math.max(0, adm.deadline - Date.now())
    );
    return "waited";
  }

  /**
   * The preconditions of a send that types: leftover text cleared, then the pre-check. A
   * command's Enter types nothing and has none.
   */
  private async beforeSend(adm: Admission): Promise<"send" | "stopped" | "waited"> {
    if (adm.step === "enter") return "send";
    // R1.5.2 / R1.5.3: clear leftover text BEFORE a send that types
    await this.clearLeftover(adm);
    if (!this.admitting(adm)) return "stopped";
    return this.precheckGate(adm);
  }

  /** `not_accepted`: Enter withheld (`text_mismatch`, `empty_box`) or pressed (the other two). */
  private async onNotAccepted(
    adm: Admission,
    out: Extract<SendOutcome, { kind: "not_accepted" }>,
    step: SubmitStep
  ): Promise<void> {
    switch (out.reason) {
      case "text_mismatch":
        if (out.maybeSubmitted) {
          // R1.3: the text may already have been submitted by another writer: no ctrl-u and no
          // further send; only claudish's own witness can accept now
          this.anomaly("gate_maybe_submitted_by_other");
          adm.submittedUnproven = "maybe_submitted_by_other";
          return;
        }
        this.anomaly("gate_text_mismatch");
        markClearFirst(adm);
        if (adm.plan.mode === "command") adm.step = "type";
        // magmux's verify settle: a late draw lands before the box is read again
        await this.pause(adm, MISMATCH_SETTLE_MS);
        return;
      case "empty_box":
        if (step === "enter") {
          // R1.1: the typed command left the box without claudish's Enter, so it may have
          // run; retyping it is the D-B duplicate in another form
          this.anomaly("gate_command_left_box");
          adm.submittedUnproven = "maybe_submitted_by_other";
          return;
        }
        this.anomaly("gate_empty_box");
        await this.pause(adm, BUSY_RETRY_MS);
        return;
      case "still_in_box":
        // Enter was pressed and ignored, the text proven present
        if (this.witnessNow()) {
          this.acceptAdmission(adm);
          return;
        }
        this.anomaly("gate_still_in_box");
        if (adm.stuckRetried) {
          adm.submittedUnproven = "still_in_box_twice";
          return;
        }
        adm.stuckRetried = true;
        await this.clearBox(adm);
        if (adm.plan.mode === "command") adm.step = "type";
        return;
      case "unconfirmed":
        // Enter was pressed with no attributable evidence: never retyped
        this.anomaly("gate_unconfirmed");
        adm.submittedUnproven = "unconfirmed";
        if (step === "enter") adm.panel = { showingSince: null, escaped: false, entered: true };
        return;
      default:
        assertNever(out.reason);
    }
  }

  /** Accept from the async loop, inside one event-processing step. */
  private acceptAdmission(adm: Admission): void {
    this.step(() => {
      if (this.admitting(adm)) this.accept();
    });
  }

  /**
   * A §5.2 stop row: no further attempt. The created prompt fails now with `detail` (its
   * first line is `reason_detail`); a later send returns the session to IDLE.
   */
  private stopAdmission(adm: Admission, detail: string, reason?: FailureReason): void {
    adm.stopped = true;
    this.step(() => {
      if (!this.admitting(adm)) return;
      this.admission = null;
      if (adm.initial) {
        this.fire("admit_deadline", { reason, detail: `${detail}\n${screenTailOf(this.screen)}` });
        return;
      }
      if (adm.item.kind === "hook") {
        this.hookAdmissionFailed(adm.item);
        return;
      }
      this.anomaly("send_not_accepted");
      this.abandonedIndex = adm.index;
      this.fire("admit_abandoned");
    });
  }

  /** The current turn's witness, after a fresh read of the transcript. */
  private witnessNow(): boolean {
    return this.witnessed(this.pollFollower(true).current);
  }

  private noteOnce(adm: Admission, key: string): void {
    if (adm.noted.has(key)) return;
    adm.noted.add(key);
    this.anomaly(key);
  }

  /** Wait `ms`, or less if the admission ends meanwhile. */
  private pause(adm: Admission, ms: number): Promise<void> {
    return this.waitFor(() => !this.admitting(adm), ms);
  }

  /** A gate reading received after `after` says the box is ready (and therefore empty). */
  private freshReady(after: number): boolean {
    const g = this.gateNow();
    return !!g && g.receivedAt > after && g.ready;
  }

  /** KEYS ctrl-u, then wait at most `CLEAR_WAIT_MS` for a fresh `ready` reading. */
  private async clearBox(adm: Admission): Promise<void> {
    const at = Date.now();
    await this.key("ctrl-u");
    await this.waitFor(() => !this.admitting(adm) || this.freshReady(at), CLEAR_WAIT_MS);
  }

  /**
   * The precondition of every gated send that types (R1.5.2): a gated send into a non-empty
   * box types nothing and waits its whole `readyTimeoutMs`, so leftover text is cleared
   * first, from the published view. `box_not_empty` is the gate's LAST readiness rule, so it
   * already proves no dialog and a settled terminal: this ctrl-u cannot land on a dialog.
   * Text this admission may itself have left (`clearFirst`) is judged only on a reading
   * received after the reply that set the flag (Revision 3 item 2): an older one can say
   * `ready` while that delivery's text is still being drawn (DB-2). Such a reading that is
   * `ready` clears the flag; one naming a dialog or vim mode keeps it, and the pre-check
   * decides; any other clears the box. With no newer reading within `CLEAR_WAIT_MS`, the
   * ctrl-u goes anyway: a ctrl-u on an empty box is harmless, a send into a full one costs
   * its whole `readyTimeoutMs`.
   *
   * R1.5.3: after a TYPE whose reply was lost, a ctrl-u on the SAME connection is
   * lane-ordered behind that delivery; one on a NEW connection is not and could land
   * mid-typing, so it waits until the lost TYPE's own client timeout has passed.
   */
  private async clearLeftover(adm: Admission): Promise<void> {
    const lost = adm.lostType;
    if (lost) {
      adm.lostType = null;
      if (lost.client !== this.client || lost.client.isClosed)
        await this.pause(adm, Math.max(0, lost.until - Date.now()));
      if (!this.admitting(adm)) return;
    }
    if (adm.clearFirst) await this.clearOwnLeftover(adm);
    else if (this.gateNow()?.reason === "box_not_empty") await this.clearBox(adm);
  }

  /** `clearFirst`: judged on a reading received after the reply that set it (see above). */
  private async clearOwnLeftover(adm: Admission): Promise<void> {
    // the published view trails the pane by up to one refresh: a reading received within
    // that interval of the reply may still show the box as it was before the text landed
    const after = adm.clearAfter + GATE_POLL_MS;
    const newer = (): GateInput | null => {
      const g = this.gateNow();
      return g && g.receivedAt > after ? g : null;
    };
    await this.waitFor(
      () => !this.admitting(adm) || newer() !== null,
      CLEAR_WAIT_MS + GATE_POLL_MS
    );
    if (!this.admitting(adm)) return;
    const g = newer();
    if (g?.ready) {
      adm.clearFirst = false;
      return;
    }
    // a dialog or vim mode: no key; the pre-check decides, and the flag waits for a clear box
    if (g && (g.dialog !== null || g.reason === "vim_mode")) return;
    adm.clearFirst = false;
    await this.clearBox(adm);
  }

  /**
   * After a command's TYPE (`in_box`): Enter on an open `/` menu runs the HIGHLIGHTED item,
   * not the typed one, and the gate has no menu handling, so a menu whose highlight is not
   * the typed name is closed with Escape first (§5.4). Read on the box located by the cursor;
   * a box not located is `menu_unverified`, and no Escape.
   */
  private async menuCheck(adm: Admission): Promise<void> {
    const name = adm.line.match(/^\/\S+/)?.[0] ?? "";
    // our frames trail magmux's own verify by up to one frame interval
    await this.waitFor(() => {
      if (!this.admitting(adm)) return true;
      const box = locateBox(this.screen);
      return !!box && locatedBoxText(this.screen, box).startsWith(name);
    }, 2 * TICK_MS);
    if (!this.admitting(adm)) return;
    const box = locateBox(this.screen);
    if (!box) {
      this.anomaly("menu_unverified");
      return;
    }
    const menu = menuAbove(this.screen.lines, box.top);
    if (menu.menuOpen && menu.menuItem !== name) await this.key("escape");
  }

  /** The last gated send, as `get_diagnostics` reports it. */
  private noteLastSend(out: SendOutcome, attempts: number): PaneLastSend {
    const s: PaneLastSend = { kind: out.kind, attempts };
    switch (out.kind) {
      case "accepted":
        s.accept = out.accept;
        s.evidence = out.evidence;
        if (out.retypeCause) s.retypeCause = out.retypeCause;
        break;
      case "in_box":
        s.accept = "in_box";
        if (out.retypeCause) s.retypeCause = out.retypeCause;
        break;
      case "busy":
      case "not_accepted":
        s.reason = out.reason;
        break;
      case "bad_request":
        s.reason = "bad_request";
        break;
      case "reply_lost":
      case "unsent":
      case "pane_gone":
      case "unexpected":
        s.reason = out.code;
        break;
      default:
        assertNever(out);
    }
    this.lastSend = s;
    return s;
  }

  /**
   * `/exit` / `/quit` (§5.4 `control`): one gated SUBMIT. Its reply is only recorded; the
   * pane's exit decides.
   */
  private async submitControl(line: string): Promise<void> {
    const c = this.client;
    if (!c) {
      this.anomaly("control_send:unsent");
      return;
    }
    const rt = SEND_READY_WAIT_DEFAULT_MS;
    const shape = sendShape("submit", line);
    const r = await c.request(
      { ...shape.msg, readyTimeoutMs: rt },
      sendBudgetMs({ ...shape.budget, readyTimeoutMs: rt }) + SEND_CLIENT_SLACK_MS
    );
    const out = classifySendReply(r);
    const s = this.noteLastSend(out, 1);
    if (out.kind !== "accepted")
      this.anomaly(`control_send:${out.kind}${s.reason ? `:${s.reason}` : ""}`);
  }

  /** One KEYS send (ctrl-u, Escape): no text and no final Enter, never gated. */
  private async key(k: string): Promise<boolean> {
    const c = this.client;
    if (!c) return false;
    const r = await c.request(
      { type: "send", pane: 0, keys: [k], enter: false, noGate: true },
      10_000
    );
    return r.ok;
  }

  private nextFrame(ms: number): Promise<void> {
    const seq = this.screen.seq;
    const end = Date.now() + ms;
    return new Promise((resolve) => {
      const check = () => {
        if (this.screen.seq !== seq || Date.now() >= end) resolve();
        else setTimeout(check, 25);
      };
      check();
    });
  }

  /**
   * Synchronous, on every evaluation: the witness accepts whatever the loop is doing; a
   * command's panel is stepped; the deadline expires the admission once no gated send is
   * out (every attempt is sized to end by it).
   */
  private evalAdmission(view: TranscriptView): void {
    const adm = this.admission;
    if (!adm) return;
    if (this.witnessed(view.current)) {
      this.accept();
      return;
    }
    if (adm.panel) this.panelStep(adm);
    if (!this.admitting(adm)) return;
    if (Date.now() >= adm.deadline && !adm.inFlight) this.admitExpired(adm);
  }

  /** A full-screen panel or picker: the gate sees no box (or a `select` dialog), and `Esc to cancel`. */
  private panelShowing(g: GateInput | null): boolean {
    return (
      !!g &&
      (g.reason === "no_input_box" || g.dialog === "select") &&
      /Esc to cancel/.test(flatText(this.screen.lines))
    );
  }

  /**
   * A panel command (`/cost`, `/usage`, `/config`; `/model` with no argument) writes no
   * transcript record and swallows input until Esc (phase2-captures §3, §10), so it can never
   * be witnessed. Once it has been up for `PANEL_SETTLE_MS` it gets one Escape, and when the
   * gate is ready again the admission ends without a turn (§5.4). Never an Escape while the
   * gate names a boot dialog (`panelShowing` admits only `no_input_box` and `select`).
   */
  private panelStep(adm: Admission): void {
    const p = adm.panel;
    if (!p) return;
    const g = this.gateNow();
    if (!p.escaped) {
      if (!this.panelShowing(g)) {
        p.showingSince = null;
        return;
      }
      const now = Date.now();
      p.showingSince ??= now;
      if (now - p.showingSince < PANEL_SETTLE_MS) return;
      p.escaped = true;
      this.anomaly(g?.dialog === "select" ? "picker_dismissed" : "panel_dismissed");
      void this.key("escape");
      return;
    }
    if (!g) return;
    if (g.ready) {
      this.admission = null;
      this.anomaly("panel_command");
      if (adm.initial)
        this.fire("admit_deadline", {
          detail: `${adm.text.trim()} opened a panel and wrote no transcript record`,
        });
      else if (adm.item.kind === "hook") this.hookAdmissionFailed(adm.item);
      else this.fire("admit_abandoned");
      return;
    }
    // Esc closed a menu, not a panel, and the command (whose Enter was never pressed) is
    // still in the box: the loop presses its Enter through the gate again
    if (!p.entered && g.reason === "box_not_empty") adm.panel = null;
  }

  private accept(): void {
    this.admission = null;
    this.initialDelivery = false;
    const now = Date.now();
    this.lastChatSeenAt = now;
    this.turnAcceptedAt = now;
    this.turnErrorLogSize = this.errorLogSize();
    this.fire("prompt_accepted");
  }

  private admitExpired(adm: Admission): void {
    this.admission = null;
    if (adm.initial) {
      this.fire("admit_deadline", {
        detail: `${this.notAcceptedLine(adm)}\n${screenTailOf(this.screen)}`,
      });
      return;
    }
    if (adm.item.kind === "hook") {
      this.hookAdmissionFailed(adm.item);
      return;
    }
    this.anomaly("send_not_accepted");
    // a witness that still arrives re-wakes the session as this turn (evalIdle)
    this.abandonedIndex = adm.index;
    this.fire("admit_abandoned");
  }

  /**
   * §7.3 step 7: an injected turn never accepted (refused, no witness in time, a panel,
   * a stop row, or the pane exited first). A one-shot chain ends with a verdict on what it
   * has; an interactive session waits for input as after any turn.
   */
  private hookAdmissionFailed(item: HookQueueItem): void {
    this.admission = null;
    this.anomaly("hook_injection_dropped:send_not_accepted");
    this.hooks?.noteDropped?.(item, "send_not_accepted");
    // The turn the injection followed is still held only on a one-shot chain, or on one a
    // send_input converted to interactive during this admission: it is concluded
    // now, on the current shape, so decide() runs for it either way.
    if (this.heldTurn) {
      this.fire("hook_admit_abandoned");
      this.conclude(null);
      return;
    }
    this.fire("admit_abandoned");
  }

  /**
   * The first line of `prompt_not_accepted`'s detail, i.e. `reason_detail`: the input
   * gate's own answer (the magus session reads it).
   */
  private notAcceptedLine(adm: Admission): string {
    const secs = Math.round((Date.now() - adm.startedAt) / 1000);
    switch (adm.submittedUnproven) {
      case "maybe_submitted_by_other":
        return "magmux could not tell whether the prompt was submitted (the box emptied without its Enter) and no transcript record of it appeared";
      case "unconfirmed":
        return `magmux not_accepted unconfirmed: Enter was pressed with no evidence it was submitted, and no transcript record appeared in ${secs} s`;
      case "reply_lost": {
        const code = adm.last?.kind === "reply_lost" ? adm.last.code : "client_lost";
        return `the magmux send reply was lost (${code}) and no transcript record of the prompt appeared in ${secs} s`;
      }
      case "still_in_box_twice":
        return "magmux not_accepted still_in_box: the prompt stayed in the input box after Enter, twice";
      case null:
        return `prompt not accepted in ${secs} s; ${describeLastReply(adm, this.gateNow())}`;
      default:
        return assertNever(adm.submittedUnproven);
    }
  }

  /**
   * Settle corroboration (architecture-v2 §7.1, R1.5.1): the gate's fresh reading, plus the
   * working row and the quiet ABOVE the box located by the cursor. Null while disconnected.
   * An unlocated box yields nulls, never a veto.
   */
  private corroborationFacts(): CorroborationFacts | null {
    if (!this.client) return null;
    const g = this.gateNow();
    return {
      gate: g ? { ready: g.ready, dialog: g.dialog, reason: g.reason } : null,
      working: workingAboveBox(this.screen),
      aboveBoxQuietMs: this.aboveBoxQuietMs(),
    };
  }

  /** ms since a row above the located box changed; null when this frame locates no box. */
  private aboveBoxQuietMs(): number | null {
    return locateBox(this.screen) ? Date.now() - this.screen.aboveBoxChangedAt : null;
  }

  /**
   * A turn the gate accepted that the transcript has not witnessed: with the transcript off,
   * or still absent or empty `DEGRADED_ENTRY_MS` after the acceptance, it settles from the
   * screen (§5.7, degraded mode now begins only AFTER an evidenced acceptance); with the
   * transcript `ok` and no witness `ADMIT_TIMEOUT_MS` after it, `witness_missing` is counted
   * once (§5.8) and the turn stays RUNNING: no timer ends it (D10).
   */
  private checkUnwitnessed(view: TranscriptView): void {
    const at = this.turnAcceptedAt;
    if (at === null || this.rewakeOfSettled || this.witnessed(view.current)) return;
    const since = Date.now() - at;
    const missing = view.availability === "absent" || view.availability === "empty";
    if (
      view.availability === "off" ||
      (missing && since >= this.t("degradedEntryMs", DEGRADED_ENTRY_MS))
    ) {
      const d = this.currentDelivery;
      this.turnSource = "screen";
      this.anomaly("degraded_mode");
      this.screenTurn = {
        echo: d && d.mode !== "refused" ? d.line : "",
        acceptedAt: at,
        errorLogSize: this.turnErrorLogSize,
      };
      return;
    }
    if (view.availability === "ok" && since >= ADMIT_TIMEOUT_MS && !this.witnessMissingCounted) {
      this.witnessMissingCounted = true;
      this.anomaly("witness_missing");
    }
  }

  private evalRunning(view: TranscriptView): void {
    if (this.turnSource === "transcript") this.checkUnwitnessed(view);
    if (this.turnSource === "screen") {
      this.evalScreenTurn(view);
      return;
    }
    const t = view.current;
    if (!t) return;
    if (this.phase === "QUESTION" || this.phase === "PERMISSION") {
      if (t.pendingTool && t.pendingTool.id === this.blockedToolId) {
        this.checkEscape();
        return;
      }
      this.blockedToolId = null;
      this.escapeSentAt = null;
      this.fire("unblocked");
    }
    if (this.detectBlocked(t)) return;
    const now = Date.now();
    const transcriptQuietMs = now - (view.lastAppendAt ?? this.startedAtMs);
    const decision = decideSettle({
      turn: t,
      session: view.session,
      transcriptQuietMs,
      chatQuietMs: now - this.lastChatSeenAt,
      facts: this.corroborationFacts(),
      paneExited: false,
      secondaryQuietMs: this.secondaryQuietMs,
      corroborationMs: this.corroborationMs,
      corroborationGraceMs: this.t("gateGraceMs", GATE_GRACE_MS),
    });
    if (decision.settled) {
      this.settle(t, decision, null);
      return;
    }
    this.activity = decision.activity;
    this.checkTurnEndMissing(t, transcriptQuietMs);
    this.checkAgentCountMismatch(t);
  }

  private checkEscape(): void {
    if (this.escapeSentAt === null) return;
    if (Date.now() - this.escapeSentAt < this.admitTimeoutMs()) return;
    this.anomaly("escape_not_effective");
    this.escapeSentAt = null;
  }

  /**
   * R3-M4: `finishing` with a static screen and no Stop-hook UI for N secondary windows.
   * The condition is live (it clears the moment work resumes); the anomaly counts how often
   * it began. A turn whose end record WAS written (turn_duration, or an interrupt) is not
   * missing one: "the turn ended and the gate disagrees" is `settle_gate_unconfirmed`.
   * Quiet is measured above the located box, else from the transcript (architecture-v2 §7.2).
   */
  private checkTurnEndMissing(t: TurnView, transcriptQuietMs: number): void {
    if (this.activity !== "finishing" || t.turnDurationAfterLast || t.interruptAfterLast) {
      this.turnEndMissing = false;
      return;
    }
    if (!this.client) return;
    const quiet = this.aboveBoxQuietMs() ?? transcriptQuietMs;
    const missing =
      quiet >= TURN_END_MISSING_FACTOR * this.secondaryQuietMs && !stopHookRunning(this.screen);
    if (missing && !this.turnEndMissing) this.anomaly("turn_end_record_missing");
    this.turnEndMissing = missing;
  }

  /**
   * claudish's pending background agents disagree with Claude Code's count at the turn's
   * end record. Live like turn_end_record_missing; the anomaly counts each onset of a pair.
   * It never settles or ends the turn: Claude Code's count is a witness (D23).
   */
  private checkAgentCountMismatch(t: TurnView): void {
    const m = agentCountMismatch(t);
    const key = m ? `${m.counted}/${m.reported}` : null;
    if (m && key !== this.agentMismatch)
      this.anomaly(
        `agent_count_mismatch: claudish ${m.counted} pending, Claude Code ${m.reported}`
      );
    this.agentMismatch = key;
  }

  /**
   * Blocked detection (architecture-v2 §6.3): a pending AskUserQuestion from the transcript
   * alone; any other pending tool blocks only when magmux's input gate names the dialog
   * (`dialog:permission`/`dialog:plan`, or `dialog:question`). Anything else, an unknown
   * gate included, stays RUNNING: an honest unknown, never `blocked`.
   */
  private detectBlocked(t: TurnView): boolean {
    const pending = t.pendingTool;
    if (!pending || this.phase !== "RUNNING") return false;
    let kind: PaneBlock["kind"] | null = null;
    if (pending.name === "AskUserQuestion") kind = "question";
    else {
      const dialog = this.gateNow()?.dialog ?? null;
      if (dialog === "permission" || dialog === "plan") kind = "permission";
      else if (dialog === "question") kind = "question";
    }
    if (!kind) return false;
    this.blockedToolId = pending.id;
    this.fire(kind === "question" ? "blocked_question" : "blocked_permission");
    this.activity = pending.name;
    // the screen supplies only the words; with no frame yet there are none to give
    const text = blockText(pending, this.screen.seq > 0 ? dialogText(this.screen) || null : null);
    try {
      this.hooks?.fireBlocked({ kind, text });
    } catch {
      // a binding's failure must not break the session
    }
    let v: FinalVerdict | "wait";
    try {
      v = this.o.onBlocked({ kind, tool: pending.name, text });
    } catch {
      v = "wait";
    }
    if (v !== "wait") this.applyVerdict(v);
    return true;
  }

  private evalIdle(view: TranscriptView): void {
    const t = view.current;
    // A later send abandoned unwitnessed (§5.3, R1.3) whose witness arrives now: magmux's
    // delivery DID land. It is this same turn, reported late, never lost.
    if (
      t &&
      this.abandonedIndex !== null &&
      t.index === this.abandonedIndex &&
      t.acceptedAt !== null &&
      !this.exitRequested
    ) {
      this.abandonedIndex = null;
      this.anomaly("late_witness");
      this.turnAcceptedAt = Date.now();
      this.turnErrorLogSize = this.errorLogSize();
      this.lastChatSeenAt = Date.now();
      this.fire("rewake");
      this.activity = "thinking";
      return;
    }
    // After a delivered /exit only the pane's exit can follow, never a re-wake: Claude
    // Code 2.1.282–2.1.285 write the command's own records into the settled turn.
    if (!t || this.settledChatOffset === null || this.exitRequested) return;
    // A background notification woke the model with no prompt of ours (D23): same turn.
    if (t.lastChatOffset !== null && t.lastChatOffset > this.settledChatOffset) {
      this.rewakeOfSettled = true;
      this.fire("rewake");
      this.activity = "thinking";
    }
  }

  /* ───────────────────────────── settle ───────────────────────────── */

  private settledTurnOf(t: TurnView, decision: SettleDecision & { settled: true }): TurnCore {
    const d = this.currentDelivery;
    // R3-M3: a file-carrying COMMAND turn hands its text to the command's own expansion,
    // which may never Read the pointer file (directly or through a subagent). Zero Reads is
    // then unverified coverage, not a failed read: complete null, never prompt_not_read.
    const unverified = d?.mode === "command" && !!t.delivery && t.readCoverage.reads === 0;
    if (unverified) this.anomaly("read_coverage_unverified");
    return {
      index: t.index,
      // a local command's answer is its own stdout: it has no assistant message (path L)
      answer:
        decision.by === "local_command"
          ? (t.localCommandOutput ?? "")
          : t.assistantText.join("\n\n"),
      apiError: t.apiError,
      stopReason: decision.stopReason,
      captureSource: "transcript",
      settledBy: decision.by,
      shape: this.shape,
      delivery: {
        mode: d && d.mode !== "refused" ? d.mode : "typed",
        linesTotal: t.delivery ? t.delivery.lines : null,
        linesRead: t.delivery ? t.readCoverage.linesReturned : null,
        complete: t.delivery && !unverified ? t.readCoverage.complete : null,
        preambleBytes: t.preambleBytes,
      },
    };
  }

  private settle(
    t: TurnView,
    decision: SettleDecision & { settled: true },
    exitCode: number | null
  ): void {
    for (const a of decision.anomalies) this.anomaly(a);
    for (const cmd of t.backgroundShellsOpen) this.anomaly(`background_shell_open: ${cmd}`);
    this.finishTurn(this.settledTurnOf(t, decision), t.lastChatOffset, exitCode);
  }

  private finishTurn(core: TurnCore, chatOffset: number | null, exitCode: number | null): void {
    if (this.hooks) {
      this.recordTurn(core, chatOffset, exitCode);
      return;
    }
    const turn: SettledTurn = {
      ...core,
      chainAnswers: [],
      chainDelivery: core.delivery,
      hookTurns: 0,
      hookCaused: false,
    };
    this.turnEndMissing = false;
    this.agentMismatch = null;
    this.answers.set(turn.index, turn.answer);
    // owners ask for the current or the last settled turn: keep a few, not the session's all
    for (const k of this.answers.keys()) if (k <= turn.index - KEPT_ANSWERS) this.answers.delete(k);
    this.lastCaptureSource = turn.captureSource;
    this.activity = null;
    let verdict: FinalVerdict | "continue";
    try {
      verdict = this.o.decide(turn);
    } catch (e) {
      verdict = { state: "FAILED", reason: "child_exited", detail: `decide() threw: ${String(e)}` };
    }
    if (!this.rewakeOfSettled) {
      this.turnsCompleted++;
      this.follower.markSettled();
    }
    if (verdict === "continue") {
      if (turn.delivery.complete === false) this.anomaly("prompt_not_read");
      this.settledChatOffset = chatOffset ?? -1;
      this.fire("turn_continue");
      return;
    }
    if (exitCode !== null || this.paneExited) {
      const note = exitNoteOf(exitCode ?? this.exitCode);
      verdict = { ...verdict, detail: verdict.detail ? `${verdict.detail} · ${note}` : note };
    }
    this.applyVerdict(verdict);
  }

  private applyVerdict(v: FinalVerdict): void {
    this.fire(VERDICT_EVENT[v.state], { reason: v.reason, detail: v.detail });
  }

  /* ───────────────────────────── record, hold, conclude (§7.3) ───────────────────────────── */

  /**
   * Step 1, synchronously in the settling step: store the answer, extend the chain,
   * PUBLISH it through `onTurnRecorded` before any transition, then hold (step 3) or
   * conclude at once (step 2).
   */
  private recordTurn(core: TurnCore, chatOffset: number | null, exitCode: number | null): void {
    this.turnEndMissing = false;
    this.answers.set(core.index, core.answer);
    for (const k of this.answers.keys()) if (k <= core.index - KEPT_ANSWERS) this.answers.delete(k);
    this.lastCaptureSource = core.captureSource;
    this.activity = null;
    if (!this.rewakeOfSettled) {
      this.turnsCompleted++;
      this.follower.markSettled();
    }
    const last = this.chain[this.chain.length - 1];
    if (last && last.index === core.index) last.answer = core.answer;
    else this.chain.push({ index: core.index, answer: core.answer });
    if (!this.turnHookCaused) this.chainHead = core.delivery;
    const turn: SettledTurn = {
      ...core,
      chainAnswers: this.chain.slice(0, -1).map((c) => c.answer),
      chainDelivery: this.chainHead ?? core.delivery,
      hookTurns: this.hookTurns,
      hookCaused: this.turnHookCaused,
    };
    this.heldTurn = turn;
    try {
      this.o.onTurnRecorded?.(turn);
    } catch {
      // an owner's callback must not break the session
    }
    this.settledChatOffset = chatOffset ?? -1;
    if (turn.hookCaused && turn.delivery.complete === false)
      this.anomaly("hook_injection_not_read");
    // Step 2: no hold when nothing can come of it, and never into a dead pane.
    const exited = exitCode !== null || this.paneExited;
    let work = false;
    if (!exited) {
      try {
        work = this.hooks?.hasIdleWork(hookCount(this.q) > 0) ?? false;
      } catch {
        work = false;
      }
    }
    if (!work) {
      this.conclude(exited ? exitNoteOf(exitCode ?? this.exitCode) : null);
      return;
    }
    this.startHold(turn);
  }

  /** Step 3: SETTLING, `settle()` in flight, a watchdog at `holdBoundMs()`. */
  private startHold(turn: SettledTurn): void {
    const binding = this.hooks as SessionHookBinding;
    this.holdGen++;
    const gen = this.holdGen;
    this.fire("settle_hold");
    this.activity = "hook";
    const ctl = new AbortController();
    this.holdController = ctl;
    let bound: number;
    try {
      bound = binding.holdBoundMs();
    } catch {
      bound = 0;
    }
    let p: Promise<{ injections: HoldInjection[]; error?: string; anomalies?: string[] }>;
    try {
      p = Promise.resolve(
        binding.settle(
          {
            index: turn.index,
            answer: turn.answer,
            stopReason: turn.stopReason,
            apiError: turn.apiError !== null,
            hookCaused: turn.hookCaused,
            consecutiveHookTurns: this.q.consecutiveHookTurns,
            callerInputPending: callerCount(this.q) > 0,
            shape: this.shape,
          },
          ctl.signal
        )
      );
    } catch (e) {
      p = Promise.reject(e);
    }
    p.catch((err: unknown) => ({ injections: [], error: String(err), rejected: true }))
      .then((r) => this.step(() => this.completeHold(gen, r)))
      .catch(() => {});
    this.holdWatchdog = setTimeout(
      () => this.step(() => this.completeHold(gen, { injections: [], error: "watchdog" })),
      Math.max(0, bound)
    );
  }

  /**
   * End the hold this step leaves `SETTLING` by: no result of it is applied afterwards. A
   * settle still running learns `reason` through its signal; a result already returned
   * and waiting for the screen goes back to the binding under the same reason.
   */
  private endHold(reason: HoldAbortReason): void {
    this.holdGen++;
    if (this.holdWatchdog) clearTimeout(this.holdWatchdog);
    this.holdWatchdog = null;
    const ctl = this.holdController;
    this.holdController = null;
    if (ctl && !ctl.signal.aborted) ctl.abort(reason);
    const held = this.heldResult;
    this.heldResult = null;
    if (held) {
      try {
        this.hooks?.abandon?.(held.result, reason);
      } catch {
        // journaling never breaks the session
      }
    }
  }

  /** Step 4: the hold's result (or the watchdog's) arrives, in its own step. */
  private completeHold(gen: number, r: HoldResult & { rejected?: boolean }): void {
    if (gen !== this.holdGen || this.phase !== "SETTLING") return;
    for (const a of r.anomalies ?? []) this.anomaly(a);
    // The pane child exited while the hold ran: onPaneExit's step concludes with the real
    // exit code within its capture window. Nothing is queued or typed into a dead pane.
    if (this.paneExited) {
      for (const i of r.injections) this.dropInjection(i, "pane_exited");
      this.holdGen++;
      if (this.holdWatchdog) clearTimeout(this.holdWatchdog);
      this.holdWatchdog = null;
      return;
    }
    const failed = r.error !== undefined;
    if (!failed) this.heldResult = { result: r, since: Date.now() };
    // the last tick's poll can be up to a second old. A re-wake written since ends
    // the hold HERE, as a tick during the hold would have, and a returned result is
    // carried under `rewake` (endHold) instead of being typed over the running turn.
    if (this.rewokeDuringHold(this.pollFollower(true))) return;
    if (failed) {
      const watchdog = r.error === "watchdog" && !r.rejected;
      this.anomaly(watchdog ? "hook_hold_watchdog" : "hook_hold_error");
      this.endHold(watchdog ? "watchdog" : "error");
      // the failed settle offers nothing; hook items queued earlier may still go
      this.heldResult = { result: { injections: [] }, since: Date.now() };
    } else {
      // ended normally: clear the bound, nothing to abort
      this.holdGen++;
      if (this.holdWatchdog) clearTimeout(this.holdWatchdog);
      this.holdWatchdog = null;
      this.holdController = null;
    }
    this.applyHeldResult();
  }

  /**
   * Step 4, applied: from `completeHold`, and from each `evalSettling` tick while the
   * screen still shows work. The phase is SETTLING throughout. An injection that
   * survives the queue policy is admitted only when `screenIdle()`; until then the result
   * waits, for at most the admission bound, after which it is abandoned as the
   * watchdog's would be and the turn concludes.
   */
  private applyHeldResult(): void {
    const held = this.heldResult;
    if (!held) return;
    const r = held.result;
    // Guard: caller input normally ends the hold in send()'s own step (4a).
    if (callerCount(this.q) > 0) {
      this.heldResult = null;
      for (const i of r.injections) this.dropInjection(i, "stale");
      this.conclude(null);
      return;
    }
    const items = [...this.q.items, ...r.injections.map((i) => this.hookItemOf(i, held.since))];
    const now = Date.now();
    const d = nextQueueDecision({ ...this.q, items }, now, "IDLE", this.canDeliver);
    const inject = d.deliver?.kind === "hook" ? d.deliver : null;
    if (inject && this.heldAdmission(held.since, now) !== "admit") return;
    this.heldResult = null;
    this.q.items = d.remaining;
    this.dropHookItems(d.drop);
    if (!inject) {
      this.conclude(null);
      return;
    }
    if (this.shape === "interactive") {
      // the turn the injection follows gets its own verdict first (decide(): an
      // API error fails the session, an unread task file is prompt_not_read). `continue`
      // takes it to IDLE, from which the injection is admitted in this same step.
      this.conclude(null);
      if (this.phase !== "IDLE") {
        this.dropInjection(inject, "session_ended");
        return;
      }
    } else {
      this.fire("hold_inject");
      this.activity = null;
    }
    this.fire("admit");
    this.startAdmission(inject, false);
  }

  /**
   * Whether a held result's injection may be typed now. `wait`: the screen still shows
   * work, within the admission bound. `ended`: the hold ended here, the bound passed (the
   * watchdog's outcome) or a re-wake was found, and the result went back to the binding.
   */
  private heldAdmission(since: number, now: number): "admit" | "wait" | "ended" {
    if (!this.screenIdle()) {
      if (now - since < this.admitTimeoutMs()) return "wait";
      this.anomaly("hook_hold_watchdog");
      this.endHold("watchdog");
      this.conclude(null);
      return "ended";
    }
    // About to type: read the transcript now, as `idleForHookItem` does. The view an
    // `evalSettling` tick passed in can be a poll debounce old, and a re-wake whose
    // records landed as the screen cleared ends the hold here, its result carried.
    return this.rewokeDuringHold(this.pollFollower(true)) ? "ended" : "admit";
  }

  /**
   * Step 5: today's `finishTurn` tail, on the held turn and the session's CURRENT shape
   * (a send during the hold converted it). Legal from RUNNING (no hold) and SETTLING.
   */
  private conclude(exitNote: string | null): void {
    const held = this.heldTurn;
    if (!held) return;
    this.heldTurn = null;
    this.activity = null;
    const turn: SettledTurn = { ...held, shape: this.shape };
    let verdict: FinalVerdict | "continue";
    try {
      verdict = this.o.decide(turn);
    } catch (e) {
      verdict = { state: "FAILED", reason: "child_exited", detail: `decide() threw: ${String(e)}` };
    }
    if (verdict === "continue") {
      // an unread hook-turn file is hook_injection_not_read, never the caller's prompt_not_read
      if (!turn.hookCaused && turn.delivery.complete === false) this.anomaly("prompt_not_read");
      this.fire("turn_continue");
      return;
    }
    const note = exitNote ?? (this.paneExited ? exitNoteOf(this.exitCode) : null);
    if (note)
      verdict = { ...verdict, detail: verdict.detail ? `${verdict.detail} · ${note}` : note };
    this.applyVerdict(verdict);
  }

  private evalSettling(view: TranscriptView): void {
    if (this.paneExited) return;
    if (this.rewokeDuringHold(view)) return;
    this.applyHeldResult();
  }

  /**
   * §7.3: a re-wake during the hold abandons it; the same turn runs on and settles again.
   * True when `view` shows one (and the hold has ended).
   */
  private rewokeDuringHold(view: TranscriptView): boolean {
    const t = view.current;
    if (!t || this.settledChatOffset === null) return false;
    if (t.lastChatOffset === null || t.lastChatOffset <= this.settledChatOffset) return false;
    this.endHold("rewake");
    this.heldTurn = null;
    this.rewakeOfSettled = true;
    this.fire("hold_rewake");
    this.activity = "thinking";
    return true;
  }

  /** A sessionStart dispatch no hold took (§7.3 "other session events"). */
  private queueHookInjections(items: HoldInjection[]): void {
    if (isTerminalPhase(this.phase)) {
      for (const i of items) this.dropInjection(i, "session_ended");
      return;
    }
    const now = Date.now();
    for (const i of items) this.q.items.push(this.hookItemOf(i, now));
    this.pump();
  }

  private hookItemOf(i: HoldInjection, now: number): HookQueueItem {
    return {
      kind: "hook",
      text: i.text,
      hookIds: [...i.hookIds],
      queuedAt: now,
      // a sessionStart injection is queued as of its dispatch: it survives the initial prompt
      callerSeq: i.source === "sessionStart" ? this.startCallerSeq : this.q.callerAdmitted,
      source: i.source,
    };
  }

  private dropHookItems(drops: ReadonlyArray<{ item: HookQueueItem; reason: string }>): void {
    for (const { item, reason } of drops) this.dropInjection(item, reason);
  }

  private dropInjection(item: { text: string; hookIds: string[] }, reason: string): void {
    this.anomaly(`hook_injection_dropped:${reason}`);
    try {
      this.hooks?.noteDropped?.(item, reason);
    } catch {
      // journaling never breaks the session
    }
  }

  /* ───────────────────────────── degraded (screen) turn ───────────────────────────── */

  /** The current turn's witness is in the transcript. */
  private witnessed(t: TurnView | null): boolean {
    return !!t && t.index === this.turnIndex && t.acceptedAt !== null;
  }

  /**
   * Degraded settle (architecture-v2 §7.3): the gate ready (an empty box) and naming no
   * dialog, no working row above the located box, and an answer or error row gone quiet.
   * Quiet is above the located box, else the whole screen's (stricter: a ticking status line
   * delays it), used only with no transcript witness.
   */
  private screenSettleReady(view: TranscriptView, answer: string, apiError: unknown): boolean {
    const g = this.gateNow();
    if (!g || !g.ready || g.dialog !== null || workingAboveBox(this.screen) === true) return false;
    const quiet = this.aboveBoxQuietMs() ?? Date.now() - this.screen.changedAt;
    if (view.availability === "off" && quiet >= this.secondaryQuietMs) return true;
    return (
      (!!answer || !!apiError) && quiet >= 2 * this.t("screenSettleQuietMs", SCREEN_SETTLE_QUIET_MS)
    );
  }

  private evalScreenTurn(view: TranscriptView): void {
    if (this.witnessed(view.current)) {
      // A late witness (slow UserPromptSubmit hook): back to the transcript, at once.
      this.turnSource = "transcript";
      this.screenTurn = null;
      this.anomaly("degraded_reverted");
      this.evalRunning(view);
      return;
    }
    const st = this.screenTurn;
    if (!st || !this.client) return;
    const answer = screenAnswer(this.screen, st.echo);
    const apiError = this.screenApiError(st, answer);
    this.activity = "thinking";
    if (!this.screenSettleReady(view, answer, apiError)) return;
    // one last poll before a screen-mode settle, with the same reversion
    this.follower.poll();
    if (this.witnessed(this.follower.view().current)) return;
    this.anomaly("screen_answer_may_be_truncated");
    if (this.currentDelivery?.mode === "file") this.anomaly("read_coverage_unverified");
    const d = this.currentDelivery;
    this.finishTurn(
      {
        index: this.turnIndex,
        answer,
        apiError,
        stopReason: null,
        captureSource: "screen",
        settledBy: "screen",
        shape: this.shape,
        delivery: {
          mode: d && d.mode !== "refused" ? d.mode : "typed",
          linesTotal: null,
          linesRead: null,
          complete: null,
          preambleBytes: 0,
        },
      },
      null,
      null
    );
  }

  private errorLogPath(): string | null {
    return this.o.slotEnv.CLAUDISH_UPSTREAM_ERROR_LOG ?? null;
  }

  private errorLogSize(): number {
    const p = this.errorLogPath();
    if (!p) return 0;
    try {
      return statSync(p).size;
    } catch {
      return 0;
    }
  }

  private screenApiError(st: ScreenTurn, answer: string): TurnView["apiError"] {
    const p = this.errorLogPath();
    if (p && this.errorLogSize() > st.errorLogSize) {
      try {
        const text = readFileSync(p, "utf8").slice(st.errorLogSize).trim();
        return { status: null, category: "upstream_error_log", text };
      } catch {
        // fall through to the screen
      }
    }
    const rows = screenErrorRows(this.screen);
    if (rows.length > 0 && !answer)
      return { status: null, category: "screen", text: rows.join("\n") };
    return null;
  }

  /* ───────────────────────────── the exit path ───────────────────────────── */

  /** Settle evidence for the current turn on the exit path (paths P, I, S without screen, X). */
  private exitSettle(): (SettleDecision & { settled: true }) | null {
    const view = this.follower.view();
    const d = decideSettle({
      turn: view.current,
      session: view.session,
      transcriptQuietMs: Number.MAX_SAFE_INTEGER,
      chatQuietMs: Number.MAX_SAFE_INTEGER,
      facts: null,
      paneExited: true,
      secondaryQuietMs: this.secondaryQuietMs,
      corroborationMs: 0,
    });
    if (!d.settled) return null;
    return { ...d, anomalies: d.anomalies.filter((a) => a !== "screen_unverified") };
  }

  /** §2.2: the exit is decided against the CURRENT turn only. */
  private applyExitPath(code: number | null): void {
    if (isTerminalPhase(this.phase)) return;
    const view = this.pollFollower(true);
    // a witness written just before the exit is still an acceptance
    if (this.phase === "ADMITTING" && this.admission && this.witnessed(view.current)) this.accept();
    // §7.3 step 7 (M-1c): an unwitnessed HOOK admission is abandoned first, so an
    // injection never turns a settled chain or a clean exit into a failure.
    const adm = this.admission;
    if (this.phase === "ADMITTING" && adm && adm.item.kind === "hook")
      this.hookAdmissionFailed(adm.item);
    // §7.3 step 6 (H1): a held turn is concluded with the exit code. An interactive
    // session then takes today's IDLE exit rules below.
    if (this.phase === "SETTLING") {
      this.endHold("exit");
      this.conclude(exitNoteOf(code));
      if (isTerminalPhase(this.phase)) return;
    }
    if (this.phase === "RUNNING") {
      const d = this.exitSettle();
      const t = this.follower.view().current;
      if (d && t) this.settle(t, d, code);
    }
    if (isTerminalPhase(this.phase)) return;
    if (this.cleanIdleExit(code)) {
      this.fire("exit_clean");
      return;
    }
    this.firePaneExit(code);
  }

  /**
   * §2.2 rule 2: interactive, IDLE, exit 0, after /exit or ≥ 1 settled turn, nothing
   * admitted. An exit seen only as ESRCH while the socket is lost has no code when magmux could
   * not name it either: after a delivered /exit that is still the clean exit it asked for.
   */
  private cleanIdleExit(code: number | null): boolean {
    if (this.phase !== "IDLE" || this.shape !== "interactive") return false;
    if (code !== 0 && !(code === null && this.exitRequested)) return false;
    return (this.exitRequested || this.turnsCompleted >= 1) && this.admission === null;
  }

  /** §2.2 rule 3: agent_rejected when the child's own refusal is on screen, else child_exited. */
  private firePaneExit(code: number | null): void {
    const text = `${this.exitLastLine}\n${this.exitScrollback}\n${screenText(this.screen)}`;
    const rejected =
      agentRejectedLine(screenText(this.screen)) ??
      agentRejectedLine(this.exitScrollback) ??
      agentRejectedLine(text);
    this.fire("pane_exit", {
      reason: rejected ? "agent_rejected" : "child_exited",
      detail: rejected
        ? rejected
        : `pane child exited ${code === null ? "(code unknown)" : `with code ${code}`}${this.exitLastLine ? `; last line: ${this.exitLastLine}` : ""}\n${screenTailOf(this.screen)}`,
    });
  }

  /* ───────────────────────────── public verbs ───────────────────────────── */

  snapshot(): PaneSnapshot {
    const view = this.follower.view();
    const terminal = isTerminalPhase(this.phase);
    // M4: a resize redraw is not activity, so it never resets idle_seconds
    const lastAct = Math.max(this.activityChangedAt, view.lastAppendAt ?? 0);
    const cur = view.current;
    const hasTranscript =
      view.availability === "ok" && view.usage.tokensIn + view.usage.tokensOut > 0;
    return {
      paneId: this.paneId,
      phase: this.phase,
      state: this.wire(),
      reason: this.phase === "COMPLETED" || !terminal ? null : this.reason,
      detail: this.detail,
      activity: terminal ? null : this.phaseActivity(),
      lastActivityAt: lastAct > 0 ? iso(lastAct) : null,
      idleSeconds:
        terminal || lastAct === 0 ? null : Math.max(0, Math.floor((Date.now() - lastAct) / 1000)),
      turnsCompleted: this.turnsCompleted,
      tokensIn: hasTranscript ? view.usage.tokensIn : null,
      tokensOut: hasTranscript ? view.usage.tokensOut : null,
      toolCalls: view.toolCalls,
      liveAnswerBytes: cur ? Buffer.byteLength(cur.assistantText.join("\n\n")) : 0,
      exitCode: this.exitCode,
      captureSource: this.lastCaptureSource,
      turnSource: this.turnSource,
      pendingInputs: callerCount(this.q),
      pendingHookInputs: hookCount(this.q),
      connected: this.client !== null,
      startedAt: iso(this.startedAtMs),
      endedAt: this.endedAtMs ? iso(this.endedAtMs) : null,
      transcriptPath: this.o.transcriptPath,
      panePid: this.panePidValue,
      screenTail: screenTailOf(this.screen),
      anomalies: [...this.anomalies].map(([k, n]) => (n > 1 ? `${k} ×${n}` : k)),
      claudeCodeVersion: this.claudeCodeVersion,
      shape: this.shape,
      turnEndRecordMissing:
        !terminal &&
        this.phase === "RUNNING" &&
        this.activity === "finishing" &&
        this.turnEndMissing,
      agentCountMismatch: !terminal && this.phase === "RUNNING" && this.agentMismatch !== null,
      recent: cur && cur.recent.length > 0 ? cur.recent : null,
    };
  }

  private phaseActivity(): string | null {
    const phase = this.phase;
    switch (phase) {
      case "RUNNING":
        return this.activity ?? "thinking";
      case "SETTLING":
        return this.activity ?? "hook";
      case "QUESTION":
        return "AskUserQuestion";
      case "PERMISSION":
        return this.activity;
      case "BOOTING":
      case "ADMITTING":
      case "IDLE":
      case "COMPLETED":
      case "FAILED":
      case "CANCELLED":
      case "TIMEOUT":
      case "EMPTY":
        return null;
      default:
        return assertNever(phase);
    }
  }

  capture(sinceSeq?: number, opts: { spans?: boolean } = {}): CaptureResult | CaptureUnchanged {
    const s = this.screen;
    if (sinceSeq !== undefined && sinceSeq === s.seq)
      return { unchanged: true, seq: s.seq, final: this.final };
    const out: CaptureResult = {
      seq: s.seq,
      cols: s.cols,
      rows: s.rows,
      cursor: { ...s.cursor },
      lines: [...s.lines],
      final: this.final,
    };
    if (opts.spans) out.spans = s.spans.map((r) => r.map((x) => [...x] as typeof x));
    return out;
  }

  send(text: string): SendResult {
    if (isTerminalPhase(this.phase)) return { ok: false, reason: "terminal" };
    if (/^\/(clear|resume)(\s|$)/.test(text.trim()))
      return { ok: false, reason: "unsupported_command" };
    const plan = planDelivery(text, this.turnDir, 0, this.o.readAvailable);
    if (plan.mode === "refused") return { ok: false, reason: "delivery_unavailable" };
    if (this.shape === "one-shot") this.shape = "interactive";
    this.q.items.push({ kind: "caller", text });
    this.escapeArmed = true;
    // Read the transcript first: a turn whose end record already landed settles HERE, and
    // its owner must see the converted shape (SettledTurn.shape) and the queued text.
    this.step(() => {
      this.pollFollower(true);
      // §7.3 step 4a (L-5): caller input ends a hold at once, in this step. The held
      // turn concludes on the converted shape (continue → IDLE) and the pump admits the
      // caller's text below; whatever settle() returns later fails the generation check.
      if (this.phase === "SETTLING" && !this.paneExited) {
        this.endHold("caller");
        this.conclude(null);
      }
      this.evaluate();
    });
    // Never report a queued prompt for a session this very step ended.
    if (isTerminalPhase(this.phase)) return { ok: false, reason: "terminal" };
    return { ok: true, queued: callerCount(this.q) };
  }

  async resize(cols: number, rows: number): Promise<PaneResizeOutcome> {
    const size = clampPaneSize(cols, rows);
    if (isTerminalPhase(this.phase)) return this.lastSizeOutcome();
    if (!this.supportsResize)
      throw new ContractErrorException(
        "resize_unsupported",
        'this magmux has no resize op (capabilities.verbs lacks "resize"); a newer magmux is needed'
      );
    if (!this.client) return this.pendingOutcome(size);
    // Same size and nothing in flight: no request. Otherwise magmux's `changed` decides.
    if (
      samePaneSize(this.appliedSize, size) &&
      samePaneSize(this.desiredSize, size) &&
      !this.resizeDraining
    )
      return { ...size, changed: false, seq: this.screen.seq };
    this.desiredSize = size;
    return new Promise<PaneResizeOutcome>((resolve, reject) => {
      this.resizeWaiters.push({ resolve, reject });
      this.kickResize();
    });
  }

  /** Store the size for the redial (`attach` applies it) and answer it as pending. */
  private pendingOutcome(size: PaneSize): PaneResizeOutcome {
    this.desiredSize = { ...size };
    return { ...size, changed: true, seq: this.screen.seq, pending: true };
  }

  /** A terminal pane's answer: the size of its last screen, unchanged. */
  private lastSizeOutcome(): PaneResizeOutcome {
    return { cols: this.screen.cols, rows: this.screen.rows, changed: false, seq: this.screen.seq };
  }

  /** A screen change at `at` falls within the resize quiet window. */
  private inResizeQuiet(at: number): boolean {
    return this.resizeQuietFrom > 0 && at >= this.resizeQuietFrom && at < this.resizeQuietUntil;
  }

  /** Open the quiet window (or keep the open one's start) and extend its end, never retract it. */
  private extendResizeQuiet(): void {
    const now = Date.now();
    if (now >= this.resizeQuietUntil) this.resizeQuietFrom = now;
    this.resizeQuietUntil = Math.max(this.resizeQuietUntil, now + RESIZE_QUIET_MS);
  }

  /**
   * A size no waiter carries is still owed: a `pending` one stored while the worker sat in
   * its screen wait, whose redial's `attach` kick found the worker running. Only a size the
   * worker has not sent on this connection is owed, so a refused one is never resent.
   */
  private resizeOwed(): boolean {
    return (
      !!this.client &&
      this.supportsResize &&
      !isTerminalPhase(this.phase) &&
      !samePaneSize(this.appliedSize, this.desiredSize) &&
      !samePaneSize(this.lastSentSize, this.desiredSize)
    );
  }

  /** Start the per-pane drain worker unless it runs already. */
  private kickResize(): void {
    if (this.resizeDraining) return;
    this.resizeDraining = true;
    void this.drainResize().finally(() => {
      this.resizeDraining = false;
      // a waiter, or an owed size, that arrived after the loop's last check
      if (this.resizeWaiters.length > 0 || this.resizeOwed()) this.kickResize();
    });
  }

  /**
   * The single resize worker of this pane (H3, M3): one request at a time, always the
   * LATEST desired size, so the sizes of a drag coalesce. Each send answers every waiter
   * queued before it; a waiter that arrives during it gets the next send. With no waiter
   * it runs once (`attach` re-applying the size after a redial), and again while a size is
   * owed. The phase is re-checked after every await: a terminal pane answers its last
   * size, `changed:false`.
   */
  private async drainResize(): Promise<void> {
    let first = true;
    while (first || this.resizeWaiters.length > 0 || this.resizeOwed()) {
      first = false;
      const batch = this.resizeWaiters.splice(0);
      const answer = (r: PaneResizeOutcome) => {
        for (const w of batch) w.resolve(r);
      };
      const fail = (e: ContractErrorException) => {
        for (const w of batch) w.reject(e);
      };
      if (isTerminalPhase(this.phase)) {
        answer(this.lastSizeOutcome());
        continue;
      }
      const want = { ...this.desiredSize };
      const c = this.client;
      if (!c) {
        answer(this.pendingOutcome(want));
        continue;
      }
      if (!this.supportsResize) {
        fail(new ContractErrorException("resize_unsupported", "this magmux has no resize op"));
        continue;
      }
      // opened before the send: the child's SIGWINCH redraw can arrive before the reply
      this.lastSentSize = want;
      this.extendResizeQuiet();
      const r = await c.request<{ cols?: number; rows?: number; changed?: boolean }>(
        { type: "resize", pane: 0, cols: want.cols, rows: want.rows },
        RESIZE_REPLY_MS
      );
      if (isTerminalPhase(this.phase)) {
        answer(this.lastSizeOutcome());
        continue;
      }
      if (!r.ok) {
        // magmux may have applied a request whose reply was lost: the size is unknown, and
        // its redraw may still arrive
        if (r.code === "client_lost" || r.code === "client_timeout") {
          this.appliedSize = null;
          this.extendResizeQuiet();
        }
        // the connection is gone: the redial's attach re-applies desiredSize
        if (r.code === "client_lost" || r.code === "client_closed") {
          answer(this.pendingOutcome(this.desiredSize));
          continue;
        }
        fail(
          new ContractErrorException(
            "delivery_unavailable",
            `magmux did not resize the pane: ${r.code}${r.error ? `: ${r.error}` : ""}`
          )
        );
        continue;
      }
      const set = {
        cols: typeof r.result.cols === "number" ? r.result.cols : want.cols,
        rows: typeof r.result.rows === "number" ? r.result.rows : want.rows,
      };
      this.appliedSize = set;
      if (r.result.changed !== true) {
        answer({ ...set, changed: false, seq: this.screen.seq });
        continue;
      }
      this.extendResizeQuiet();
      // H4: the answer's seq is the first screen at the new size (magmux's forced keyframe)
      await this.waitFor(
        () =>
          isTerminalPhase(this.phase) ||
          (this.screen.cols === set.cols && this.screen.rows === set.rows),
        RESIZE_SCREEN_MS
      );
      if (isTerminalPhase(this.phase)) {
        answer(this.lastSizeOutcome());
        continue;
      }
      answer({ ...set, changed: true, seq: this.screen.seq });
    }
  }

  turnAnswer(index: number): string {
    const done = this.answers.get(index);
    if (done !== undefined) return done;
    const cur = this.follower.view().current;
    return cur && cur.index === index ? cur.assistantText.join("\n\n") : "";
  }

  chainText(): string {
    const parts = this.chain.map((c) => c.answer);
    const lastIndex = this.chain[this.chain.length - 1]?.index ?? 0;
    const cur = this.follower.view().current;
    // the running chain turn: one above the last recorded index, not yet recorded
    if (cur && cur.index > lastIndex) parts.push(cur.assistantText.join("\n\n"));
    return parts.filter((a) => a !== "").join("\n\n");
  }

  assistantMessageIds(): readonly string[] {
    return this.follower.assistantMessageIds();
  }

  diagnostics(): PaneDiagnostics {
    const cur = this.follower.view().current;
    const rec = this.registryRec;
    const g = this.gate;
    return {
      magmuxStderr: this.stderrHead,
      registry: rec
        ? { status: rec.status, waitingFor: rec.waitingFor, version: rec.version }
        : null,
      preambleBytes: cur?.preambleBytes ?? 0,
      readCoverage: cur?.delivery
        ? {
            linesTotal: cur.delivery.lines,
            linesReturned: cur.readCoverage.linesReturned,
            complete: cur.readCoverage.complete,
            reads: cur.readCoverage.reads,
          }
        : null,
      gate:
        g && this.client
          ? { ready: g.ready, reason: g.reason, detail: g.detail, ageMs: Date.now() - g.receivedAt }
          : null,
      lastSend: this.lastSend ? { ...this.lastSend } : null,
    };
  }

  cancel(): { changed: boolean; state: SlotState } {
    return this.endBy("cancel");
  }

  expire(): { changed: boolean; state: SlotState } {
    return this.endBy("timeout");
  }

  private endBy(ev: "cancel" | "timeout"): { changed: boolean; state: SlotState } {
    if (isTerminalPhase(this.phase)) return { changed: false, state: this.wire() };
    this.step(() => this.fire(ev));
    return { changed: true, state: this.wire() };
  }

  reaped(): Promise<void> {
    return this.reapPromise ?? this.terminal.then(() => this.reapPromise ?? Promise.resolve());
  }

  panePid(): number | null {
    return this.panePidValue;
  }

  /* ───────────────────────────── terminal and reap ───────────────────────────── */

  private onTerminal(): void {
    this.endedAtMs = Date.now();
    this.final = true;
    this.admission = null;
    if (this.timeoutTimer) clearTimeout(this.timeoutTimer);
    if (this.hooks) {
      // every way out of SETTLING aborts the hold with its reason (§4.10)
      this.endHold("terminal");
      this.heldTurn = null;
      for (const item of this.q.items)
        if (item.kind === "hook") this.dropInjection(item, "session_ended");
      this.q.items = this.q.items.filter((i) => i.kind === "caller");
      try {
        this.hooks.fireEnd({ state: this.wire(), reason: this.reason, exitCode: this.exitCode });
      } catch {
        // never delays the terminal state or the reap
      }
    }
    if (!this.readySettled) {
      this.readySettled = true;
      this.resolveReady();
    }
    // after the step that made it terminal has finished (onTransition first)
    queueMicrotask(() => this.resolveTerminal(this.snapshot()));
    if (!this.reapPromise) this.reapPromise = this.reap();
  }

  private files(): { paneId: string; sockPath: string; launcherDir: string; turnDir: string } {
    return {
      paneId: this.paneId,
      sockPath: this.sockPath,
      launcherDir: this.ctlDir,
      turnDir: this.turnDir,
    };
  }

  private ms(normal: number, fast: number): number {
    return this.fastReap ? fast : normal;
  }

  private async waitFor(pred: () => boolean, ms: number): Promise<void> {
    const end = Date.now() + ms;
    while (!pred() && Date.now() < end) await Bun.sleep(25);
  }

  /** §2.10 — close_pane, magmux by its handle, the verified group backstop, verify, clean, watcher. */
  private async reap(): Promise<void> {
    await Promise.resolve(); // let the terminal step finish first
    this.reaping = true;
    if (this.ticker) clearInterval(this.ticker);
    this.ticker = null;
    if (this.gateTimer) clearInterval(this.gateTimer);
    this.gateTimer = null;
    await this.captureGroupBeforeReap();
    const c = this.client;
    if (c && !c.isClosed && !this.paneClosed) {
      const r = await c.request({ type: "close_pane", pane: 0, force: true }, this.ms(1000, 500));
      if (r.ok || r.code === "no_such_pane")
        await this.waitFor(() => this.paneClosed || c.isClosed, this.ms(3000, 1000));
    }
    if (this.magmux) await waitForExit(this.magmux, this.ms(3000, 1000));
    if (alive(this.magmux)) {
      this.magmux?.kill("SIGTERM");
      if (this.magmux) await waitForExit(this.magmux, this.ms(2000, 500));
      if (alive(this.magmux)) this.magmux?.kill("SIGKILL");
      if (this.magmux) await waitForExit(this.magmux, 1000);
    }
    await this.groupBackstop();
    await this.verifyAndClean();
  }

  /** Step 0: refresh the verified group while its members still carry their identity. */
  private async captureGroupBeforeReap(): Promise<void> {
    const table = await readProcessTableAsync();
    if (!table) return;
    if (!this.panePidValue && this.magmux?.pid) {
      const lead = table.find((r) => r.ppid === this.magmux?.pid && r.pgid === r.pid);
      if (lead) {
        const snap = verifiedGroupSnapshot(table, lead.pgid, this.identity);
        if (snap) this.panePidValue = lead.pid;
      }
    }
    refreshGroupOf(this, table);
  }

  /**
   * The verified group, or a recorded escaped descendant (own process group), is alive.
   * True while the table is unavailable: the reap stays unverified and keeps its files.
   */
  private async groupAlive(): Promise<boolean> {
    if (!this.group) return false;
    const table = await readProcessTableAsync();
    if (!table) return true;
    return groupCheck(table, this.group) || liveEscaped(table, this.group).length > 0;
  }

  /** The verified group (`-pgid`) and each live escaped descendant (its pid), re-read now. */
  private async backstopTargets(): Promise<number[]> {
    if (!this.group) return [];
    const table = await readProcessTableAsync();
    if (!table) return [];
    return [
      ...(groupCheck(table, this.group) ? [-this.group.pgid] : []),
      ...liveEscaped(table, this.group),
    ];
  }

  private async groupBackstop(): Promise<void> {
    for (const sig of ["SIGTERM", "SIGKILL"] as const) {
      const targets = await this.backstopTargets();
      if (targets.length === 0) return;
      for (const target of targets) signalQuietly(target, sig);
      const end = Date.now() + (sig === "SIGTERM" ? this.ms(2000, 500) : 1000);
      while (Date.now() < end && (await this.groupAlive())) await Bun.sleep(150);
    }
  }

  private async verifyAndClean(): Promise<void> {
    const groupGone = !(await this.groupAlive());
    const magGone = !alive(this.magmux);
    this.client?.close();
    if (groupGone && magGone) {
      removePaneFiles(this.root, this.files());
      this.reapFailed = false;
      await this.endWatcher();
      unregisterPane(this.paneId);
      return;
    }
    this.reapFailed = true;
    this.anomaly("reap_unverified");
    updateRecord(this.root, this.paneId, { reapFailed: true });
  }

  /** Re-run steps 4–6 (the registry's 2 s tick, after an unverified reap). */
  async retryReap(): Promise<boolean> {
    if (alive(this.magmux)) this.magmux?.kill("SIGKILL");
    await this.groupBackstop();
    await this.verifyAndClean();
    return !this.reapFailed;
  }

  /** Step 6, only after a verified reap: `done`, end stdin, then SIGKILL through the handle. */
  private async endWatcher(): Promise<void> {
    const w = this.watcher;
    if (!w || !alive(w)) return;
    try {
      w.stdin?.write("done\n");
      w.stdin?.end();
    } catch {
      // EPIPE: the watcher is already gone (R3-M1)
    }
    await waitForExit(w, 1000);
    if (alive(w)) w.kill("SIGKILL");
  }

  async shutdownReap(_reason: string): Promise<void> {
    this.fastReap = true;
    if (!isTerminalPhase(this.phase)) this.step(() => this.fire("cancel"));
    await (this.reapPromise ?? Promise.resolve());
  }

  killMagmuxSync(): void {
    if (alive(this.magmux)) this.magmux?.kill("SIGKILL");
  }
}

function signalQuietly(target: number, sig: NodeJS.Signals): void {
  try {
    process.kill(target, sig);
  } catch {
    // gone between the read and the signal
  }
}

/** The pane's size at launch: the owner's initial size, clamped, else the default. */
function launchSize(o: PaneSessionOptions): PaneSize {
  return o.initialSize
    ? clampPaneSize(o.initialSize.cols, o.initialSize.rows)
    : { cols: DEFAULT_PANE_COLS, rows: DEFAULT_PANE_ROWS };
}

/** A fresh admission of a typed, file or command plan; its first step follows the plan's kind. */
function newAdmission(a: {
  index: number;
  item: QueueItem;
  text: string;
  plan: Extract<Delivery, { mode: "typed" | "file" | "command" }>;
  initial: boolean;
  bound: number;
}): Admission {
  const now = Date.now();
  return {
    index: a.index,
    item: a.item,
    text: a.text,
    plan: a.plan,
    line: a.plan.line,
    initial: a.initial,
    startedAt: now,
    deadline: now + a.bound,
    step: a.plan.mode === "command" ? "type" : "submit",
    inFlight: false,
    attempts: 0,
    submittedUnproven: null,
    stuckRetried: false,
    panel: null,
    stopped: false,
    clearFirst: false,
    clearAfter: 0,
    lostType: null,
    last: null,
    noted: new Set(),
  };
}

/** The box may hold this admission's own text, as of the reply received now. */
function markClearFirst(adm: Admission): void {
  adm.clearFirst = true;
  adm.clearAfter = Date.now();
}

/**
 * The wire request of one admission step and the shape `sendBudgetMs` sizes it by. `keys`
 * counts the final Enter as one key (an upper bound either way). Every send is typed
 * (`typed:true`, R1.2: a paste is never retyped and is verified by token count). `noGate`
 * and `dismissDialogs` are never set.
 */
function sendShape(
  step: SubmitStep,
  line: string
): {
  msg: Record<string, unknown>;
  budget: { text: string; keys: number; submit: boolean };
} {
  switch (step) {
    case "submit":
      return {
        msg: { type: "send", pane: 0, text: line, typed: true, enter: true },
        budget: { text: line, keys: 1, submit: true },
      };
    case "type":
      return {
        msg: { type: "send", pane: 0, text: line, typed: true, enter: false },
        budget: { text: line, keys: 0, submit: false },
      };
    case "enter":
      // a final Enter key is a SUBMIT to the gate (verified `non_empty`), R1.5.4
      return {
        msg: { type: "send", pane: 0, keys: ["enter"], enter: false },
        budget: { text: "", keys: 1, submit: true },
      };
    default:
      return assertNever(step);
  }
}

/** `sendBudgetMs` minus its readiness wait: what an attempt costs beyond waiting for the box. */
function fixedSendMs(step: SubmitStep, line: string): number {
  const rt = SEND_READY_WAIT_DEFAULT_MS;
  return sendBudgetMs({ ...sendShape(step, line).budget, readyTimeoutMs: rt }) - rt;
}

/**
 * The `readyTimeoutMs` of the next attempt, or null when none fits (R1.4): the client
 * timeout (`sendBudgetMs + SEND_CLIENT_SLACK_MS`) must end by the deadline, and a command's
 * TYPE leaves room for its Enter SUBMIT. Never above magmux's default 10 s, never below
 * `MIN_READY_TIMEOUT_MS`.
 */
function readyTimeoutFor(step: SubmitStep, line: string, leftMs: number): number | null {
  const reserve =
    step === "type" ? fixedSendMs("enter", line) + SEND_CLIENT_SLACK_MS + MIN_READY_TIMEOUT_MS : 0;
  const rt = Math.min(
    SEND_READY_WAIT_DEFAULT_MS,
    leftMs - fixedSendMs(step, line) - SEND_CLIENT_SLACK_MS - reserve
  );
  return rt < MIN_READY_TIMEOUT_MS ? null : Math.floor(rt);
}

/** The latest reply of an admission that ended with nothing submitted, in the gate's words. */
function describeLastReply(
  adm: { last: SendOutcome | null; attempts: number },
  gate: GateInput | null
): string {
  const o = adm.last;
  if (!o) {
    const g = gate ? (gate.ready ? "ready" : (gate.reason ?? "not ready")) : "unknown";
    return adm.attempts === 0
      ? `no gated send fitted before the deadline (gate: ${g})`
      : `no magmux reply (gate: ${g})`;
  }
  switch (o.kind) {
    case "busy":
      return `last magmux reply: busy ${o.reason || "unknown"}${o.typed ? " (typed, Enter withheld)" : ""}${gate?.detail ? ` (${gate.detail})` : ""}`;
    case "not_accepted":
      return `last magmux reply: not_accepted ${o.reason}`;
    case "accepted":
      return `last magmux reply: ok ${o.accept} (${o.evidence})`;
    case "in_box":
      return "last magmux reply: in_box (the command was typed, its Enter never sent)";
    case "bad_request":
      return `last magmux reply: bad_request ${o.error}`;
    case "reply_lost":
    case "unsent":
    case "pane_gone":
      return `last magmux reply: ${o.code}`;
    case "unexpected":
      return `last magmux reply: ${o.code}`;
    default:
      return assertNever(o);
  }
}

/** The verdict note of a conclusion on the exit path. */
function exitNoteOf(code: number | null): string {
  return `pane child exited${code === null ? "" : ` ${code}`}`;
}

function isControl(text: string): boolean {
  const t = text.trim();
  return t === "/exit" || t === "/quit";
}

/** The question or dialog text a block reports to the owner. */
function blockText(pending: { name: string; input?: unknown }, dialog: string | null): string {
  if (pending.name === "AskUserQuestion") {
    const qs = (pending.input as { questions?: Array<{ question?: unknown }> } | undefined)
      ?.questions;
    const text = (qs ?? [])
      .map((q) => (typeof q.question === "string" ? q.question : ""))
      .filter(Boolean);
    if (text.length) return text.join("\n");
  }
  return dialog ?? pending.name;
}

/* ───────────────────────────── the entry point ───────────────────────────── */

export class PaneStartError extends Error {
  constructor(
    readonly code: string,
    message: string
  ) {
    super(message);
  }
}

interface PreparedPane {
  paneId: string;
  sockPath: string;
  cwd: string;
  ctlDir: string;
  turnDir: string;
  magmuxEnv: Record<string, string>;
}

/** Ids, dirs, launcher and environment. Nothing is spawned; on a throw the dirs are removed. */
function preparePane(
  o: PaneSessionOptions,
  root: string,
  parentEnv: Record<string, string | undefined>
): PreparedPane {
  let dirs: { ctlDir: string; turnDir: string } | null = null;
  try {
    const paneId = mintPaneId(o.kind, o.label);
    const sockPath = sockPathOf(root, paneId);
    const cwd = realpathSync(o.cwd);
    const launch = o.claudishSpawn ?? resolveClaudishLaunch(parentEnv);
    dirs = createLaunchDirs(root);
    const argv = buildClaudishPaneArgv(o.spawnModel, o.sessionUuid, dirs.turnDir, o.callerFlags);
    writeLauncherFiles(dirs.ctlDir, launcherScript(cwd, launch, argv));
    const { magmuxEnv } = buildPaneEnv({
      parentEnv,
      slotEnv: o.slotEnv,
      cwd,
      ctlDir: dirs.ctlDir,
      configFile: getConfigFileOverride(),
      ...launchSize(o),
    });
    return { paneId, sockPath, cwd, ...dirs, magmuxEnv };
  } catch (e) {
    for (const d of dirs ? [dirs.ctlDir, dirs.turnDir] : [])
      if (isLaunchDirPath(root, d)) rmSync(d, { recursive: true, force: true });
    if ((e as { code?: string }).code) throw e;
    throw new PaneStartError("pane_lost", e instanceof Error ? e.message : String(e));
  }
}

/**
 * Start a pane session. Throws `MagmuxUnavailableError`, `PaneLimitError` or
 * `PaneStartError` BEFORE anything is spawned; installs the shutdown hooks (idempotent).
 */
export async function startPaneSession(o: PaneSessionOptions): Promise<PaneSession> {
  const parentEnv = o.parentEnv ?? process.env;
  let took = false;
  let magmux: { binary: string };
  let root: string;
  try {
    if (SUBCOMMAND_WORDS.includes(o.spawnModel))
      throw new PaneStartError(
        "invalid_args",
        `model "${o.spawnModel}" is a claudish subcommand name`
      );
    magmux = await assertMagmuxAvailable(o.magmuxBinary);
    root = ensureSockRoot(o.sockRoot ?? sockRootFor(parentEnv));
    await ensureSwept(root);
    if (!paneShutdownHooksInstalled()) installPaneShutdownHooks();
    // a reservation the owner made for this run, else our own (which checks the limit); the
    // record is written before the next await, so the pane is never uncounted
    took = takePaneReservation();
    if (!took) {
      reservePanes(1, root);
      took = takePaneReservation();
    }
  } catch (e) {
    // A start that fails before it took its reservation still uses up the one its owner
    // made for it, so an owner that reserved N panes never leaks the count.
    if (!took) takePaneReservation();
    throw e;
  }
  const p = preparePane(o, root, parentEnv);
  try {
    writeRecord(root, {
      paneId: p.paneId,
      ownerPid: process.pid,
      ownerStart: ownerStartOfSelf(),
      watcherPid: null,
      magmuxPid: null,
      panePid: null,
      sessionUuid: o.sessionUuid,
      sockPath: p.sockPath,
      launcherDir: p.ctlDir,
      turnDir: p.turnDir,
      createdAt: new Date().toISOString(),
    });
  } catch (e) {
    // nothing was spawned: remove the dirs preparePane made (validated paths only)
    removePaneFiles(root, {
      paneId: p.paneId,
      sockPath: p.sockPath,
      launcherDir: p.ctlDir,
      turnDir: p.turnDir,
    });
    throw new PaneStartError("pane_lost", `cannot write the pane record: ${String(e)}`);
  }
  const session = new PaneSessionImpl(o, {
    paneId: p.paneId,
    sockPath: p.sockPath,
    root,
    ctlDir: p.ctlDir,
    turnDir: p.turnDir,
  });
  registerPane(session);
  await session.start({ magmuxBinary: magmux.binary, env: p.magmuxEnv, cwd: p.cwd });
  return session;
}