Skip to content

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

42.8 KB
Raw Blame
/**
 * `InteractiveDriver`: session hooks for `claudish -i` (hook-system architecture §7.5).
 *
 * In `wrap` mode claudish launched a visible `-w` magmux and Claude Code is pane 0. In
 * `ambient` mode claudish runs inside a magmux someone else started (a `team --grid`
 * pane, a pane the user opened) and its pane is found by process ancestry
 * (`pane/own-pane.ts`). Either way the driver is a SECOND client on that socket (S2,
 * measured: `watch` frames and `send {typed:true}` both work there), and it is the only
 * part of claudish that types into the human's session.
 *
 * What it does, per turn:
 *
 *   - **Turns.** One `TranscriptFollower` on the session's transcript. The first turn
 *     opens at offset 0 with the HUMAN witness, so a prompt given on the command line,
 *     which Claude Code may write before the REPL is drawn, is witnessed. After each
 *     settle the next turn opens at the current offset with the same witness; an
 *     injected turn uses the `text` witness of the line it typed. The human witness is
 *     matched by provenance (`isHumanPrompt`): a task notification never matches it,
 *     so a background re-wake (D23) stays the turn it woke — it never makes a pending
 *     injection stale and never resets the cap.
 *   - **Settle.** `decideSettle`, with the same screen facts as a pane. The phase is the
 *     latch: one `binding.settle()` per settled turn, `SETTLING` while it runs, and a
 *     re-wake or a human prompt during the hold ends it (`rewake`, `caller`).
 *   - **Delivery gate.** An injection is typed only when the turn is idle, the box is
 *     drawn, empty, and has not changed for `typingHoldMs` (1,500 ms), no dialog or
 *     working row shows, no menu is open, and the recovery banner holds no lease. It is
 *     ONE `send {typed:true, enter:true}` of a plain line, or of the instruction to Read
 *     a turn file in the `--add-dir` turn directory. Never Esc, never into a dialog. The
 *     residual race — a keystroke landing between the last check and the send — is
 *     accepted: magmux has no atomic "send if empty".
 *   - **Acceptance.** The typed line's witness must appear within `acceptMs` (30 s),
 *     else the injection is dropped `send_not_accepted`.
 *   - **Session events.** `sessionStart` at the first empty REPL box; `sessionBlocked`
 *     on a question or a permission dialog; `sessionEnd` from `stop()`, which the
 *     launcher awaits for at most 1.5 s.
 *   - **Session id.** The minted `--session-id` from boot; then whatever id the proxy's
 *     requests carry (`InProcessSink.onSessionId`), so `/clear` retargets the follower
 *     and a `--resume`d launch finds its transcript. Until an id is known the driver
 *     opens no turn and types nothing; queued injections wait under the 10-minute rule.
 */

import { existsSync, statSync } from "node:fs";
import { join } from "node:path";
import { log, logStderr } from "../../logger.js";
import {
  SEND_READY_WAIT_DEFAULT_MS,
  classifySendReply,
  sendBudgetMs,
} from "../../pane/input-gate.js";
import { MagmuxClient } from "../../pane/magmux-client.js";
import { findOwnPane } from "../../pane/own-pane.js";
import {
  type Delivery,
  deliveryRefusal,
  planDelivery,
  writeTurnFile,
} from "../../pane/prompt-delivery.js";
import {
  choiceDialog,
  hasChoiceDialog,
  inputBox,
  isWorking,
  readBoot,
} from "../../pane/screen-classifier.js";
import {
  type MagmuxFrame,
  type ScreenState,
  applyFrame,
  emptyScreen,
} from "../../pane/screen-model.js";
import {
  CORROBORATION_MS,
  type CorroborationFacts,
  SECONDARY_QUIET_MS,
  decideSettle,
} from "../../pane/settle-rule.js";
import {
  TranscriptFollower,
  type TranscriptView,
  type TurnDelivery,
  type TurnView,
  type Witness,
  lastHumanPromptOffset,
} from "../../pane/transcript-follower.js";
import { transcriptPathFor } from "../../session/session-discovery.js";
import type { HookEngine } from "../engine.js";
import {
  type HookQueueItem,
  type InjectionQueueState,
  afterAdmission,
  emptyQueueState,
  hookCount,
  next as nextQueueDecision,
} from "../injection/queue.js";
import { type InProcessSink, reportInjectionUnavailable } from "../injection/sinks.js";
import type { SessionInfo } from "../public.js";
import {
  type HoldAbortReason,
  type HoldInjection,
  type HoldResult,
  type SessionHookBinding,
  createSessionHookBinding,
} from "./binding.js";

/** The box must have been empty and unchanged this long before an injection is typed. */
export const TYPING_HOLD_MS = 1_500;
/** The typed line's witness must appear within this long. */
export const ACCEPT_TIMEOUT_MS = 30_000;
/** `sessionEnd` hooks get at most this long before the launcher shuts its proxy down. */
export const SESSION_END_WAIT_MS = 1_500;
const TICK_MS = 250;
const WATCH_FPS = 4;
/** The REPL box must read empty this long before `sessionStart` fires. */
const REPL_STABLE_MS = 500;
/** How long a session id learned from a request may wait for its transcript to appear. */
const RETARGET_WAIT_MS = 10_000;
/** Added to a send's budget for the client timeout, as a pane does. */
const SEND_CLIENT_SLACK_MS = 2_000;
/** How long a lost send reply waits for `reconnect()` before the admission fails. */
const RECONNECT_WAIT_MS = 10_000;
const DEFAULT_MAX_CONSECUTIVE = 3;

/* ───────────────────────────── the turn phase ───────────────────────────── */

/**
 * The driver's turn phase. Unlike a pane it never ends the session: Claude Code is the
 * human's, and claudish only waits, reads and (rarely) types.
 *
 *   NONE       no session id known yet: nothing is followed
 *   OPEN       a human-witness turn is open and not yet accepted: the session is idle
 *   ADMITTING  an injection was typed; its text witness is awaited
 *   RUNNING    the turn was accepted and has not settled
 *   SETTLING   settled and recorded; `binding.settle()` runs (the latch)
 *   STOPPED    Claude Code exited, or the launcher stopped the driver
 */
export type DriverPhase = "NONE" | "OPEN" | "ADMITTING" | "RUNNING" | "SETTLING" | "STOPPED";

type DriverEvent =
  | "session_known"
  | "human_accepted"
  | "deliver"
  | "hook_accepted"
  | "admit_failed"
  | "settle_open"
  | "settle_hold"
  | "hold_done"
  | "rewake"
  | "retarget"
  | "stop";

const EDGES = {
  NONE: { session_known: "OPEN", stop: "STOPPED" },
  OPEN: {
    human_accepted: "RUNNING",
    deliver: "ADMITTING",
    rewake: "RUNNING",
    retarget: "OPEN",
    stop: "STOPPED",
  },
  ADMITTING: {
    hook_accepted: "RUNNING",
    admit_failed: "OPEN",
    retarget: "OPEN",
    stop: "STOPPED",
  },
  RUNNING: { settle_open: "OPEN", settle_hold: "SETTLING", retarget: "OPEN", stop: "STOPPED" },
  SETTLING: {
    hold_done: "OPEN",
    rewake: "RUNNING",
    human_accepted: "RUNNING",
    retarget: "OPEN",
    stop: "STOPPED",
  },
  STOPPED: {},
} as const satisfies Record<DriverPhase, Partial<Record<DriverEvent, DriverPhase>>>;

/** The next phase, or null when `ev` is not legal from `phase`. */
export function nextDriverPhase(phase: DriverPhase, ev: DriverEvent): DriverPhase | null {
  const row = EDGES[phase] as Partial<Record<DriverEvent, DriverPhase>>;
  return row[ev] ?? null;
}

/* ───────────────────────────── options ───────────────────────────── */

export interface InteractiveDriverOptions {
  mode: "wrap" | "ambient";
  /** the wrap's `--id` control socket, or the ambient `MAGMUX_SOCK` */
  sockPath: string;
  /** Claude Code's pane: 0 in a wrap. Absent → found by ancestry (ambient). */
  pane?: number;
  /** test seam for the ancestry search; `list` returns the `list` reply's result */
  findPane?: (list: () => Promise<unknown>) => Promise<number | null>;
  /** Claude Code's working directory (the transcript slug is its realpath) */
  cwd: string;
  /** the minted or user-given `--session-id`; null after `--resume`/`--continue`/`--fork-session` */
  sessionId: string | null;
  /** Claude Code's projects directory (`projectsDir(childEnv)`) */
  projectsRoot: string;
  /** the `--add-dir` turn directory (0700) where long injections are written */
  turnDir: string;
  /** false when Claude Code's flags remove the Read tool */
  readAvailable: boolean;
  /** the model as the user asked for it (`ctx.session.model`) */
  model: string;
  /** the launcher's in-process sink: proxy-event lines and request session ids */
  sink: InProcessSink;
  /** the engine a binding is built over; ignored when `binding` is given */
  engine?: HookEngine;
  /** test seam: any `SessionHookBinding` */
  binding?: SessionHookBinding;
  /** the recovery banner holds the pane (`recoveryOverlayHeld`) */
  overlayHeld?: () => boolean;
  /** stderr, for the one-line "unavailable" notices */
  warn?: (line: string) => void;
  /** test seams; production passes none */
  timings?: {
    tickMs?: number;
    typingHoldMs?: number;
    acceptMs?: number;
    replStableMs?: number;
    secondaryQuietMs?: number;
    corroborationMs?: number;
    connectMs?: number;
  };
}

/** What the driver can tell a test or the debug log about itself. */
export interface DriverSnapshot {
  phase: DriverPhase;
  pane: number | null;
  sessionId: string | null;
  booted: boolean;
  turnIndex: number;
  settles: number;
  callerAdmitted: number;
  consecutiveHookTurns: number;
  pendingHookInputs: number;
  available: boolean;
}

interface OpenTurn {
  index: number;
  offset: number;
  witness: Witness;
  delivery: TurnDelivery | null;
  hookCaused: boolean;
}

interface Admission {
  item: HookQueueItem;
  startedAt: number;
}

/* ───────────────────────────── the driver ───────────────────────────── */

export class InteractiveDriver {
  private phase: DriverPhase = "NONE";
  private readonly o: InteractiveDriverOptions;
  private readonly binding: SessionHookBinding;
  private readonly warn: (line: string) => void;
  private client: MagmuxClient | null = null;
  private pane: number | null;
  private screen: ScreenState = emptyScreen(160, 50);
  private framePending = false;
  private follower: TranscriptFollower | null = null;
  private sessionId: string | null;
  /** ids this driver followed and left (`/clear`): a late request naming one is ignored */
  private readonly retired = new Set<string>();
  private pendingSid: { id: string; since: number } | null = null;

  private q: InjectionQueueState;
  private current: OpenTurn | null = null;
  /** the turn that settled last, kept so a re-wake can re-open it */
  private settledTurn: OpenTurn | null = null;
  private lastAcceptedIndex = 0;
  private fileSeq = 0;
  private admission: Admission | null = null;
  private settles = 0;
  private blockedToolId: string | null = null;

  private booted = false;
  private bootKind: string | null = null;
  private bootKindSince = 0;
  private startCallerSeq = 1;

  private holdGen = 0;
  private holdController: AbortController | null = null;
  private holdWatchdog: ReturnType<typeof setTimeout> | null = null;

  private lastBoxKey: string | null = null;
  private boxChangedAt = Date.now();
  private lastPollAt = 0;
  private lastChatOffset: number | null = null;
  private lastChatSeenAt = Date.now();
  private readonly startedAt = Date.now();

  private ticker: ReturnType<typeof setInterval> | null = null;
  private unsubscribeSession: (() => void) | null = null;
  private unavailable = false;
  private stopping: Promise<void> | null = null;

  constructor(o: InteractiveDriverOptions) {
    this.o = o;
    this.warn = o.warn ?? logStderr;
    this.pane = o.pane ?? null;
    this.sessionId = o.sessionId;
    const session: SessionInfo = {
      kind: "interactive",
      role: null,
      id: o.sessionId ?? "",
      claudeSessionId: o.sessionId,
      model: o.model,
      cwd: o.cwd,
      shape: "interactive",
      injection: "available",
    };
    if (o.binding) this.binding = o.binding;
    else if (o.engine) this.binding = createSessionHookBinding(o.engine, session, o.sink.inbox);
    else throw new Error("InteractiveDriver needs an engine or a binding");
    this.q = emptyQueueState(this.binding.maxConsecutive ?? DEFAULT_MAX_CONSECUTIVE);
    this.binding.attach?.({
      queueInjections: (items) => this.step(() => this.queueInjections(items)),
    });
  }

  /* ───────────────────────────── lifecycle ───────────────────────────── */

  /**
   * Connect, find the pane, subscribe to its frames and start following. Never throws:
   * a driver that cannot reach its pane makes injection `unavailable` (one stderr line)
   * and still fires `sessionStart` and `sessionEnd`.
   */
  async start(): Promise<void> {
    this.unsubscribeSession = this.o.sink.onSessionId((sid) =>
      this.step(() => this.noteRequestSession(sid))
    );
    if (this.sessionId) this.follow(this.sessionId, 0);
    try {
      this.client = await MagmuxClient.connect(this.o.sockPath, {
        timeoutMs: this.o.timings?.connectMs ?? 10_000,
        alive: () => this.phase !== "STOPPED",
      });
    } catch (err) {
      this.goUnavailable(`cannot reach magmux at ${this.o.sockPath}: ${String(err)}`);
      return;
    }
    if (this.currentPhase() === "STOPPED") {
      this.client.close();
      return;
    }
    if (this.pane === null) {
      const client = this.client;
      const list = async () => {
        const r = await client.request({ type: "list" });
        return r.ok ? r.result : null;
      };
      this.pane = await (this.o.findPane ?? ((l) => findOwnPane(l)))(list);
      if (this.pane === null) {
        this.goUnavailable("this claudish's magmux pane was not found");
        return;
      }
    }
    await this.subscribe(this.client);
    this.ticker = setInterval(() => this.step(() => this.evaluate()), this.ms("tickMs", TICK_MS));
    log(
      `[hooks] interactive driver on magmux pane ${this.pane} (${this.o.mode}), session ${this.sessionId ?? "(not known yet)"}`
    );
  }

  /**
   * Claude Code exited (or the launcher is shutting down): end any hold, drop what is
   * queued, fire `sessionEnd` and wait for it at most `SESSION_END_WAIT_MS`. Idempotent.
   */
  stop(outcome: { state: string; reason: string | null; exitCode: number | null }): Promise<void> {
    if (this.stopping) return this.stopping;
    this.stopping = (async () => {
      this.step(() => {
        if (this.phase === "SETTLING") this.endHold("terminal");
        this.admission = null;
        this.transition("stop");
        for (const item of this.q.items)
          if (item.kind === "hook") this.dropInjection(item, "session_ended");
        this.q.items = [];
      });
      if (this.ticker) clearInterval(this.ticker);
      this.ticker = null;
      this.unsubscribeSession?.();
      this.o.sink.markUnavailable();
      try {
        this.binding.fireEnd(outcome);
      } catch {
        // a binding's failure must not hold the launcher
      }
      await raceTimeout(this.binding.endSettled?.() ?? Promise.resolve(), SESSION_END_WAIT_MS);
      // what no settle took is journaled before the launcher shuts its proxy down
      try {
        this.binding.sweepInbox?.();
      } catch {
        // journaling never holds the launcher
      }
      this.client?.close();
      this.client = null;
    })();
    return this.stopping;
  }

  snapshot(): DriverSnapshot {
    return {
      phase: this.phase,
      pane: this.pane,
      sessionId: this.sessionId,
      booted: this.booted,
      turnIndex: this.current?.index ?? this.lastAcceptedIndex,
      settles: this.settles,
      callerAdmitted: this.q.callerAdmitted,
      consecutiveHookTurns: this.q.consecutiveHookTurns,
      pendingHookInputs: hookCount(this.q),
      available: !this.unavailable,
    };
  }

  private goUnavailable(why: string): void {
    this.unavailable = true;
    this.o.sink.markUnavailable();
    log(`[hooks] interactive driver: ${why}; hook injection is unavailable for this session`);
    reportInjectionUnavailable(this.warn);
    this.binding.updateSession?.({ injection: "unavailable" });
    // No screen to find the REPL box on: the session started when Claude Code did.
    this.fireStart();
  }

  private async subscribe(client: MagmuxClient): Promise<void> {
    const pane = this.pane as number;
    client.on("frame", (f: MagmuxFrame) => {
      if (f.pane !== undefined && f.pane !== pane) return;
      this.screen = applyFrame(this.screen, f);
      this.framePending = true;
      this.noteBox();
      this.step(() => this.evaluate());
    });
    client.on("disconnected", () => {
      if (this.client === client) this.client = null;
      if (this.phase !== "STOPPED") void this.reconnect();
    });
    const r = await client.request({ type: "watch", pane, mode: "frames", fps: WATCH_FPS });
    if (!r.ok) log(`[hooks] interactive driver: watch pane ${pane} refused: ${r.code} ${r.error}`);
  }

  /** magmux keeps its panes when a client leaves: redial while the session lives. */
  private async reconnect(): Promise<void> {
    let delay = 100;
    for (let i = 0; i < 20 && this.phase !== "STOPPED" && !this.client; i++) {
      await Bun.sleep(delay);
      try {
        const c = await MagmuxClient.dial(this.o.sockPath);
        if (this.currentPhase() === "STOPPED") {
          c.close();
          return;
        }
        this.client = c;
        await this.subscribe(c);
        return;
      } catch {
        delay = Math.min(1_000, delay * 2);
      }
    }
  }

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

  private step(fn: () => void): void {
    try {
      fn();
    } catch (err) {
      // The driver must never take the launcher down with it.
      log(
        `[hooks] interactive driver step failed: ${err instanceof Error ? err.stack : String(err)}`
      );
    }
  }

  /** The phase, read through a call so a narrowing from an earlier check never sticks. */
  private currentPhase(): DriverPhase {
    return this.phase;
  }

  private transition(ev: DriverEvent): boolean {
    const next = nextDriverPhase(this.phase, ev);
    if (!next) {
      log(`[hooks] interactive driver: illegal ${this.phase} --${ev}`);
      return false;
    }
    this.phase = next;
    return true;
  }

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

  /* ───────────────────────────── the session id ───────────────────────────── */

  /** Start following `sid`'s transcript, with the first turn at `offset`. */
  private follow(sid: string, offset: number): void {
    const path = transcriptPathFor(this.o.cwd, sid, this.o.projectsRoot);
    this.follower = new TranscriptFollower(path, join(path.replace(/\.jsonl$/, ""), "subagents"));
    this.sessionId = sid;
    this.settledTurn = null;
    this.lastPollAt = Date.now();
    this.binding.updateSession?.({ id: sid, claudeSessionId: sid });
    // From a mid-file offset the follower must start reading THERE, not at byte 0.
    this.openHumanTurn(offset, offset > 0);
    if (this.phase === "NONE") this.transition("session_known");
  }

  /** A proxy request named `sid`: a `/clear`, or the session of a resumed launch. */
  private noteRequestSession(sid: string): void {
    if (this.phase === "STOPPED" || sid === this.sessionId || this.retired.has(sid)) return;
    if (this.pendingSid?.id !== sid) this.pendingSid = { id: sid, since: Date.now() };
    this.tryRetarget();
  }

  /**
   * Follow the pending session id once its transcript exists. The turn opens at its
   * last human prompt: Claude Code writes the prompt before the request that names the
   * session, so that prompt is the running turn's witness.
   */
  private tryRetarget(): void {
    const p = this.pendingSid;
    if (!p) return;
    const path = transcriptPathFor(this.o.cwd, p.id, this.o.projectsRoot);
    if (!existsSync(path)) {
      if (Date.now() - p.since > RETARGET_WAIT_MS) {
        log(`[hooks] interactive driver: no transcript for session ${p.id}; not following it`);
        this.pendingSid = null;
      }
      return;
    }
    this.pendingSid = null;
    if (this.phase === "SETTLING") this.endHold("caller");
    if (this.admission) {
      this.dropInjection(this.admission.item, "stale");
      this.admission = null;
    }
    if (this.sessionId) this.retired.add(this.sessionId);
    log(`[hooks] interactive driver: following session ${p.id}`);
    const offset = lastHumanPromptOffset(path) ?? fileSizeOf(path);
    const wasNone = this.phase === "NONE";
    this.follow(p.id, offset);
    if (!wasNone && this.phase !== "OPEN") this.transition("retarget");
  }

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

  private pollFollower(force = false): TranscriptView | null {
    const f = this.follower;
    if (!f) return null;
    const now = Date.now();
    if (force || this.framePending || now - this.lastPollAt >= 1_000) {
      f.poll();
      this.lastPollAt = now;
      this.framePending = false;
    }
    const view = f.view();
    const off = view.current?.lastChatOffset ?? null;
    if (off !== this.lastChatOffset) {
      this.lastChatOffset = off;
      this.lastChatSeenAt = now;
    }
    return view;
  }

  private evaluate(): void {
    if (this.phase === "STOPPED") return;
    if (this.pendingSid) this.tryRetarget();
    this.checkBoot();
    const view = this.pollFollower();
    if (!view) return;
    const t = view.current;
    // Read after the steps above, any of which can move the phase.
    const phase: DriverPhase = this.currentPhase();
    switch (phase) {
      case "NONE":
      case "STOPPED":
        return;
      case "OPEN":
        if (t?.acceptedAt) this.humanAccepted();
        else if (this.settledTurn && t?.unwitnessedChatOffset != null) this.rewake();
        else this.pump();
        return;
      case "ADMITTING":
        this.evalAdmission(t);
        return;
      case "RUNNING":
        this.evalRunning(view);
        return;
      case "SETTLING":
        if (t?.acceptedAt) {
          // A human prompt during the hold ends it at once: the human goes first (rule 3).
          this.endHold("caller");
          this.humanAccepted();
        } else if (t?.unwitnessedChatOffset != null) {
          this.endHold("rewake");
          this.rewake();
        }
        return;
      default:
        assertNeverPhase(phase);
    }
  }

  /** `sessionStart` fires at the first empty REPL box, held stable for `replStableMs`. */
  private checkBoot(): void {
    if (this.booted || this.unavailable || this.screen.seq === 0) return;
    const r = readBoot(this.screen);
    const now = Date.now();
    if (r.kind !== this.bootKind) {
      this.bootKind = r.kind;
      this.bootKindSince = now;
    }
    if (r.kind === "repl" && now - this.bootKindSince >= this.ms("replStableMs", REPL_STABLE_MS)) {
      this.booted = true;
      this.fireStart();
    }
  }

  private fireStart(): void {
    // The session's first human turn counts as its initial prompt (§4.7 rule 3): a
    // `sessionStart` injection survives it, whether it was given on the command line
    // (already admitted here) or typed after the box appeared.
    this.startCallerSeq = Math.max(1, this.q.callerAdmitted);
    try {
      this.binding.fireStart();
    } catch {
      // a binding's failure must not break the driver
    }
  }

  private openHumanTurn(offset: number, readFromOffset = false): void {
    const turn: OpenTurn = {
      index: this.lastAcceptedIndex + 1,
      offset,
      witness: { kind: "human" },
      delivery: null,
      hookCaused: false,
    };
    if (readFromOffset) this.follower?.rewindTo(turn);
    else this.follower?.openTurn(turn);
    this.current = turn;
    this.blockedToolId = null;
  }

  /** Close what the follower has read so far, then open a human turn at its end. */
  private openHumanTurnHere(): void {
    this.follower?.poll();
    this.lastPollAt = Date.now();
    this.openHumanTurn(this.follower?.size() ?? 0);
  }

  private humanAccepted(): void {
    const cur = this.current;
    if (!cur) return;
    // Rule 3 and the cap: a human turn is a caller admission. Hook items queued before it
    // are stale, and the run of hook-caused turns ends.
    Object.assign(this.q, afterAdmission(this.q, { kind: "caller", text: "" }));
    this.lastAcceptedIndex = cur.index;
    this.lastChatSeenAt = Date.now();
    this.transition("human_accepted");
  }

  /**
   * A background notification woke the model after its turn settled (D23). The driver
   * had opened the next turn, which the notification does not witness, so the settled
   * turn is re-opened from its own offset and runs on as the SAME turn: no caller
   * admission, no cap reset, the same index when it settles again.
   */
  private rewake(): void {
    const turn = this.settledTurn;
    if (!turn || !this.follower) return;
    this.follower.rewindTo(turn);
    this.current = turn;
    this.lastChatSeenAt = Date.now();
    this.transition("rewake");
  }

  private evalAdmission(t: TurnView | null): void {
    const adm = this.admission;
    if (!adm) return;
    if (t?.acceptedAt) {
      this.admission = null;
      this.lastAcceptedIndex = this.current?.index ?? this.lastAcceptedIndex + 1;
      this.lastChatSeenAt = Date.now();
      this.transition("hook_accepted");
      return;
    }
    if (Date.now() - adm.startedAt >= this.ms("acceptMs", ACCEPT_TIMEOUT_MS))
      this.admitFailed("no witness in time");
  }

  private admitFailed(why: string): void {
    const adm = this.admission;
    if (!adm || this.phase !== "ADMITTING") return;
    this.admission = null;
    log(`[hooks] interactive driver: injection not accepted (${why})`);
    this.dropInjection(adm.item, "send_not_accepted");
    this.openHumanTurnHere();
    this.transition("admit_failed");
  }

  /**
   * Settle corroboration in the settle rule's shape. The driver reads the SCREEN, not
   * magmux's input gate: the pane it follows may be ungated (an ambient pane, a test's
   * headless one), and the gate's published view names pane 0 only. So `gate.ready` is
   * the screen's box drawn and empty with no choice dialog, as the driver settled on
   * before; corroboration can delay a transcript-proven ending, never veto it (the
   * settle rule's grace).
   */
  private corroborationFacts(): CorroborationFacts | null {
    if (!this.client) return null;
    const reason = screenNotIdleReason(this.screen);
    return {
      gate: { ready: reason === null, dialog: null, reason },
      working: isWorking(this.screen),
      aboveBoxQuietMs: Date.now() - this.screen.aboveBoxChangedAt,
    };
  }

  private evalRunning(view: TranscriptView): void {
    const t = view.current;
    if (!t) return;
    this.checkBlocked(t);
    const now = Date.now();
    const decision = decideSettle({
      turn: t,
      session: view.session,
      transcriptQuietMs: now - (view.lastAppendAt ?? this.startedAt),
      chatQuietMs: now - this.lastChatSeenAt,
      facts: this.corroborationFacts(),
      paneExited: false,
      secondaryQuietMs: this.ms("secondaryQuietMs", SECONDARY_QUIET_MS),
      corroborationMs: this.ms("corroborationMs", CORROBORATION_MS),
      // the grace is the secondary window, as a pane's (`GATE_GRACE_MS`)
      corroborationGraceMs: this.ms("secondaryQuietMs", SECONDARY_QUIET_MS),
    });
    if (decision.settled) this.record(t, decision.by === "local_command", decision.stopReason);
  }

  /** `sessionBlocked`, once per blocking tool: a question, or a permission/plan dialog. */
  private checkBlocked(t: TurnView): void {
    const pending = t.pendingTool;
    if (!pending) {
      this.blockedToolId = null;
      return;
    }
    if (pending.id === this.blockedToolId) return;
    let kind: "question" | "permission" | null = null;
    if (pending.name === "AskUserQuestion") kind = "question";
    else if (this.client && hasChoiceDialog(this.screen)) kind = "permission";
    if (!kind) return;
    this.blockedToolId = pending.id;
    const text = choiceDialog(this.screen)?.text ?? pending.name;
    try {
      this.binding.fireBlocked({ kind, text });
    } catch {
      // observe-only
    }
  }

  /* ───────────────────────────── settle, hold ───────────────────────────── */

  /**
   * The turn settled: open the next (human) turn at the current offset, then hold for
   * the session hooks when they have work, else go straight to OPEN.
   */
  private record(t: TurnView, localCommand: boolean, stopReason: string | null): void {
    const cur = this.current;
    if (!cur) return;
    this.settles++;
    this.settledTurn = cur;
    const info = {
      index: cur.index,
      answer: localCommand ? (t.localCommandOutput ?? "") : t.assistantText.join("\n\n"),
      stopReason,
      apiError: t.apiError !== null,
      hookCaused: cur.hookCaused,
      consecutiveHookTurns: this.q.consecutiveHookTurns,
      callerInputPending: false,
      shape: "interactive" as const,
    };
    this.openHumanTurnHere();
    let work = false;
    try {
      work = this.binding.hasIdleWork(hookCount(this.q) > 0);
    } catch {
      work = false;
    }
    if (!work) {
      this.transition("settle_open");
      this.pump();
      return;
    }
    this.startHold(info);
  }

  private startHold(info: Parameters<SessionHookBinding["settle"]>[0]): void {
    this.holdGen++;
    const gen = this.holdGen;
    this.transition("settle_hold");
    const ctl = new AbortController();
    this.holdController = ctl;
    let bound: number;
    try {
      bound = this.binding.holdBoundMs();
    } catch {
      bound = 0;
    }
    let p: Promise<HoldResult>;
    try {
      p = Promise.resolve(this.binding.settle(info, ctl.signal));
    } catch (e) {
      p = Promise.reject(e);
    }
    p.catch((err: unknown) => ({ injections: [], error: String(err) }) as HoldResult)
      .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 without its result; the binding acts on `reason` (§4.7 rule 12). */
  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);
  }

  private completeHold(gen: number, r: HoldResult): void {
    if (gen !== this.holdGen || this.phase !== "SETTLING") return;
    for (const a of r.anomalies ?? []) log(`[hooks] interactive driver: ${a}`);
    // the last tick's poll can be up to a second old. A human prompt or a re-wake
    // that reached the transcript since ends the hold HERE, exactly as if a tick had seen
    // it during the hold, and the result goes back to the binding under that reason.
    const t = this.pollFollower(true)?.current;
    const ended: HoldAbortReason | null = t?.acceptedAt
      ? "caller"
      : t?.unwitnessedChatOffset != null
        ? "rewake"
        : null;
    if (ended) {
      // a settle still running (the watchdog fired) learns the reason through its signal
      this.endHold(ended);
      if (r.error === undefined) {
        try {
          this.binding.abandon?.(r, ended);
        } catch {
          // journaling never breaks the driver
        }
      }
      if (ended === "caller") this.humanAccepted();
      else this.rewake();
      return;
    }
    if (r.error !== undefined) {
      log(
        `[hooks] interactive driver: ${r.error === "watchdog" ? "hook_hold_watchdog" : `hook_hold_error ${r.error}`}`
      );
      this.endHold(r.error === "watchdog" ? "watchdog" : "error");
    } else {
      this.holdGen++;
      if (this.holdWatchdog) clearTimeout(this.holdWatchdog);
      this.holdWatchdog = null;
      this.holdController = null;
    }
    const now = Date.now();
    for (const i of r.injections) this.q.items.push(this.hookItemOf(i, now));
    this.transition("hold_done");
    this.pump();
  }

  /* ───────────────────────────── the queue and the gate ───────────────────────────── */

  /** `sessionStart` injections no hold took (the binding's `attach`). */
  private queueInjections(items: HoldInjection[]): void {
    if (this.phase === "STOPPED" || this.unavailable) {
      for (const i of items)
        this.dropInjection(i, this.unavailable ? "unavailable" : "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,
      callerSeq: i.source === "sessionStart" ? this.startCallerSeq : this.q.callerAdmitted,
      source: i.source,
    };
  }

  /** As in a pane: typed text or a file, never a slash command. */
  private readonly canDeliver = (text: string): boolean =>
    !text.trimStart().startsWith("/") && deliveryRefusal(text, this.o.readAvailable) === null;

  /**
   * The delivery gate (§7.5). Every condition is read from the screen and the open
   * turn at this instant; nothing here waits.
   */
  private gateOpen(now: number): boolean {
    if (this.phase !== "OPEN" || !this.booted || this.unavailable) return false;
    if (!this.client || this.pane === null || !this.follower) return false;
    const t = this.follower.view().current;
    if (!t || t.acceptedAt !== null || t.unwitnessedChatOffset !== null) return false;
    const box = inputBox(this.screen);
    if (!box || box.text !== "" || box.menuOpen) return false;
    if (hasChoiceDialog(this.screen) || isWorking(this.screen)) return false;
    if (now - this.boxChangedAt < this.ms("typingHoldMs", TYPING_HOLD_MS)) return false;
    if (this.o.overlayHeld?.()) return false;
    return true;
  }

  /**
   * Read the transcript NOW, before the gate decides, and act on what it shows. A
   * human prompt or a re-wake written since the last tick moves the phase (the item stays
   * queued); typing on the strength of an older poll is typing over a running turn.
   * `deliver` takes its turn boundary from this same read.
   */
  private openTurnIdleNow(): boolean {
    if (this.phase !== "OPEN") return false;
    const t = this.pollFollower(true)?.current;
    if (t?.acceptedAt) {
      this.humanAccepted();
      return false;
    }
    if (this.settledTurn && t?.unwitnessedChatOffset != null) {
      this.rewake();
      return false;
    }
    return true;
  }

  /** The box's text (or its absence) changed: the typing hold restarts. */
  private noteBox(): void {
    const box = inputBox(this.screen);
    const key = box ? box.text : "\u0000none";
    if (key !== this.lastBoxKey) {
      this.lastBoxKey = key;
      this.boxChangedAt = Date.now();
    }
  }

  private pump(): void {
    if (this.q.items.length === 0) return;
    if (!this.openTurnIdleNow()) return;
    const now = Date.now();
    if (!this.gateOpen(now)) return;
    const d = nextQueueDecision(this.q, now, "IDLE", this.canDeliver);
    this.q.items = d.remaining;
    for (const { item, reason } of d.drop) this.dropInjection(item, reason);
    if (d.deliver?.kind === "hook") this.deliver(d.deliver);
  }

  private deliver(item: HookQueueItem): void {
    const follower = this.follower;
    const client = this.client;
    const pane = this.pane;
    if (!follower || !client || pane === null) return;
    Object.assign(this.q, afterAdmission(this.q, item));
    // the turn boundary is the read `openTurnIdleNow` just checked (same step)
    const offset = follower.size();
    const plan: Delivery = planDelivery(
      item.text,
      this.o.turnDir,
      ++this.fileSeq,
      this.o.readAvailable
    );
    if (plan.mode !== "typed" && plan.mode !== "file") {
      // canDeliver already refused anything else; a slash command is invalid at the action
      this.dropInjection(item, "delivery_unavailable");
      return;
    }
    try {
      writeTurnFile(plan);
    } catch (err) {
      log(`[hooks] interactive driver: turn file not written: ${String(err)}`);
      this.dropInjection(item, "delivery_unavailable");
      return;
    }
    const turn: OpenTurn = {
      index: this.lastAcceptedIndex + 1,
      offset,
      witness: plan.witness,
      delivery: plan.mode === "file" ? { file: plan.file, text: plan.fileContent } : null,
      hookCaused: true,
    };
    follower.openTurn(turn);
    this.current = turn;
    this.admission = { item, startedAt: Date.now() };
    try {
      this.binding.noteDelivered?.(item);
    } catch {
      // journaling never breaks delivery
    }
    this.transition("deliver");
    const adm = this.admission;
    // On a pane magmux gates (its command names Claude Code, as the `-w` wrap's does) the send waits for
    // the box and answers only with evidence, so the client timeout is the gated budget:
    // a shorter one reads a slow gated answer as a lost reply.
    const rt = SEND_READY_WAIT_DEFAULT_MS;
    const timeout =
      sendBudgetMs({ readyTimeoutMs: rt, text: plan.line, keys: 1, submit: true }) +
      SEND_CLIENT_SLACK_MS;
    void client
      .request(
        { type: "send", pane, text: plan.line, typed: true, enter: true, readyTimeoutMs: rt },
        timeout
      )
      .then(async (r) => {
        if (r.ok || this.admission !== adm) return;
        const out = classifySendReply(r);
        // a lost REPLY is not a refusal. The line may already be typed, or typed
        // and entered; the screen and the transcript decide, as in a pane.
        // Once it landed, the text witness accepts it within `acceptMs` as usual.
        if (out.kind === "reply_lost" && out.code !== "timeout") {
          if (await this.landedAfterLostReply(adm, pane, plan.line)) return;
        } else if (out.kind === "not_accepted" && enterMayHaveBeenPressed(out)) {
          // the gate pressed Enter (or another writer may have): never pressed again;
          // the text witness accepts it, or `acceptMs` drops it
          log(
            `[hooks] interactive driver: send not confirmed (${out.reason}); awaiting the witness`
          );
          return;
        }
        if (this.admission === adm)
          this.step(() => this.admitFailed(`send refused: ${r.code} ${r.error}`));
      });
  }

  /**
   * After a lost send reply: the line is in the box (its Enter was lost: press it now),
   * or it was submitted (its witness, or its echo above the box). False when neither.
   *
   * A lost reply can mean a lost connection, whose client delivers nothing more: the
   * screen is judged, and Enter sent, through the client connected NOW, after a frame
   * it delivered. Enter goes only while `adm` is still the pending admission, and only
   * its own reply, or the transcript and screen after it, says the line landed.
   */
  private async landedAfterLostReply(adm: Admission, pane: number, line: string): Promise<boolean> {
    const head = line.slice(0, 40);
    // Twice: the Enter itself can meet a connection that is closing.
    for (let attempt = 0; attempt < 2; attempt++) {
      const seen = this.screen.seq;
      const client = await this.connectedClient(RECONNECT_WAIT_MS);
      if (!client) return false;
      await this.frameAfter(seen, 1_000);
      if (!inputBox(this.screen)?.text.startsWith(head)) break;
      if (this.admission !== adm) return false;
      log("[hooks] interactive driver: send reply lost; the line is in the box, pressing Enter");
      const r = await client.request({ type: "send", pane, keys: ["enter"], enter: false }, 10_000);
      if (r.ok) return true;
      log(`[hooks] interactive driver: Enter after a lost reply: ${r.code} ${r.error}`);
    }
    const landed = this.submitted(head);
    if (landed) log("[hooks] interactive driver: send reply lost; the line was submitted");
    return landed;
  }

  /** The line starting with `head` was submitted: its witness, or its echo above the box. */
  private submitted(head: string): boolean {
    const t = this.pollFollower(true)?.current;
    return (
      (t?.acceptedAt ?? null) !== null || this.screen.lines.some((l) => l.startsWith(`❯ ${head}`))
    );
  }

  /** The client that is connected now, waiting up to `ms` for `reconnect()` to replace a lost one. */
  private async connectedClient(ms: number): Promise<MagmuxClient | null> {
    const end = Date.now() + ms;
    for (;;) {
      const c = this.client;
      if (c && !c.isClosed) return c;
      if (Date.now() >= end || this.phase === "STOPPED") return null;
      await Bun.sleep(25);
    }
  }

  /** Resolves once a frame newer than `seq` arrived, or after `ms`. */
  private frameAfter(seq: number, ms: number): Promise<void> {
    if (this.screen.seq !== seq) return Promise.resolve();
    return this.nextFrame(ms);
  }

  /** Resolves on the next frame, or after `ms`. */
  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();
    });
  }

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

/** Why the screen does not show an idle REPL (a choice dialog, no box, text in it); null when it does. */
function screenNotIdleReason(screen: ScreenState): string | null {
  if (hasChoiceDialog(screen)) return "choice_dialog";
  const box = inputBox(screen);
  if (!box) return "no_input_box";
  return box.text === "" ? null : "box_not_empty";
}

/** A gated `not_accepted` after which Enter was, or may have been, pressed. */
function enterMayHaveBeenPressed(o: { reason: string; maybeSubmitted: boolean }): boolean {
  return o.reason === "still_in_box" || o.reason === "unconfirmed" || o.maybeSubmitted;
}

function assertNeverPhase(p: never): never {
  throw new Error(`unhandled driver phase ${String(p)}`);
}

function fileSizeOf(path: string): number {
  try {
    return statSync(path).size;
  } catch {
    return 0;
  }
}

function raceTimeout(p: Promise<unknown>, ms: number): Promise<void> {
  return new Promise((resolve) => {
    const t = setTimeout(resolve, ms);
    p.then(
      () => {
        clearTimeout(t);
        resolve();
      },
      () => {
        clearTimeout(t);
        resolve();
      }
    );
  });
}