Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

62.9 KB
Raw Blame
import type { ScreenReader } from './screenReader.js'
import type { SubmissionReader } from './submissionReader.js'
import { createHash } from 'crypto'
import { composerHolds, composerShown, normalizedTerminalText, visibleTerminal } from '../engines/kit/submission.js'
import { launchBound } from '../core/engines/sessionBinding.js'
import type { RegisteredSession } from './registry.js'
import { sid } from './log.js'
import { isMessageHold, messageHoldText, messageWithheldText, passingHold, type MessageHold } from './messageHolds.js'
import type { MoveGate } from './hostMove/gate.js'
import { enterWithheldReason, TERMINAL_LEASE_REFUSED, type TerminalActionResult } from './terminalTypes.js'

const MAX_QUEUE_ITEMS = 8
const MAX_QUEUE_BYTES = 24 * 1024
const ITEM_TTL_MS = 5 * 60_000
// The window for an engine that declares none of its own (engines/submissionPolicies.ts declares Claude
// Code's and Codex's, with the reasons).
const SUBMIT_VERIFY_MS = 1_500
// OpenCode's accept signal is the reader's DB poll (~1s) surfacing a new user row → turn_started, so
// give it a slightly longer window than the file-based engines before a retry-Enter.
const OPENCODE_SUBMIT_VERIFY_MS = 2_500
// Kilo is opencode's fork and its user row lands on Enter the same way, read by the same 1s DB poll, so
// it gets the same window. Measured on a live pane: the row is written as the turn opens, not when the
// model replies — so this covers the poll, not model latency (which is Command Code's problem, not this).
const KILO_SUBMIT_VERIFY_MS = 2_500
// Pi has no composer glyph either, and its JSONL is written per completed message — give the derived
// turn_started a comparable window before re-pressing Enter.
const PI_SUBMIT_VERIFY_MS = 2_500
// Hermes' composer glyph (`❯`) is user-skinnable, so it is verified from the DB like opencode/pi. Its
// user row lands at turn start, so the window matches theirs.
const HERMES_SUBMIT_VERIFY_MS = 2_500
// Command Code's composer is a bare `>` (and `/`+`@` open autocompletes that swallow Enter), so it is
// verified from the transcript like opencode/pi/hermes. Unlike them it does not write the user record on
// Enter: the file is flushed per model round-trip, so the record only lands once the first response comes
// back (measured 3.2s on its fastest model). A shorter window fires a spurious retry-Enter on every
// injection and can raise a false "did not accept" — so this window covers model TTFT, not terminal echo.
const COMMANDCODE_SUBMIT_VERIFY_MS = 6_000
// Devin's accept signal is its sessions.db poll (~1s) surfacing the new user row. Unlike Command Code it
// writes that row on Enter rather than when the model round-trip commits (measured: turn_started 1.1s
// after paste), so it needs only the same poll-sized window as opencode/pi/hermes.
const DEVIN_SUBMIT_VERIFY_MS = 2_500
// Muse writes the `started` record as soon as it accepts the prompt, so the transcript answers within
// one poll — same window as the other store-verified engines.
const MUSE_SUBMIT_VERIFY_MS = 6_000
// Amp's plugin writes `turn_start` from the agent.start event, which fires the instant the prompt is
// accepted — no model round trip in between, so the same store-verified window fits.
const AMP_SUBMIT_VERIFY_MS = 6_000
// Grok's FIRST prompt creates the session, runs SessionStart + UserPromptSubmit hooks, then writes the
// user_message_chunk. The isolated real run took ~4.4s from paste to watcher-visible turn start; 2.5s
// pressed Enter a second time on every fresh agent even though the first submission was accepted.
const GROK_SUBMIT_VERIFY_MS = 6_000
// agy's first `PreInvocation` is what clears the fingerprint, and it only fires once the model call
// starts. Measured 3-5s from Enter to the first hook on a warm session; 8s leaves headroom without
// making a genuinely dropped message wait too long for its error.
const AGY_SUBMIT_VERIFY_MS = 8_000
// Copilot's first hook of a turn is `userPromptSubmitted`, which fires as soon as Enter is accepted —
// faster than agy's, which waits for the model call. 6s is the same headroom grok gets.
const COPILOT_SUBMIT_VERIFY_MS = 6_000
const CURSOR_TURN_SETTLE_MS = 750
const SUBMIT_MAX_RETRIES = 2
/** How long a paste the control lease refused, before a byte was written, waits for the lease, and how
 *  often it asks again. */
const LEASE_WAIT_MS = 15_000
const LEASE_RETRY_MS = 250
// Re-observe briefly while a submitted prompt awaits a transcript event. Reaching this limit is not
// evidence of rejection: Claude can hold an accepted follow-up while background agents finish.
const SUBMIT_MAX_OBSERVES = 5

export interface SessionInputDelivery {
  deliveryId: string
  sessionId: string
  state: 'queued' | 'delivered' | 'started' | 'rejected' | 'unknown'
  reason?: string
}

/**
 * What became of a person's message, one without a delivery id (the windows' and the phone's composers), said
 * once and for measurement only: the request's measurement had its start and nothing more (2026-10-19: 14 phone
 * messages, no outcome). `started`, its turn began; `taken`, the engine took it without a turn being seen yet (it
 * left the composer, or a running turn it follows ended). The person was told why for each of the next nine
 * (`agent_gone`, `runtime_gone`, `held`, `withheld`, `paste_failed`, `not_submitted`, `queue_full`,
 * `queue_expired`, `invalid`, nothing sent for most); `ambiguous`, `prompt_mismatch` and `turn_ended` were typed
 * and never confirmed either way; `cancelled`, the person stopped it.
 */
export type MessageOutcome = 'started' | 'taken' | 'agent_gone' | 'runtime_gone' | 'held' | 'withheld' | 'paste_failed'
  | 'not_submitted' | 'queue_full' | 'queue_expired' | 'invalid' | 'ambiguous' | 'prompt_mismatch' | 'turn_ended' | 'cancelled'
export type MessageReceipt = (outcome: MessageOutcome) => void

/** [receipt] said at most once, and never into the input path: a receipt that throws is measurement lost. */
function sayOnce(receipt?: MessageReceipt): MessageReceipt | undefined {
  if (!receipt) return undefined
  let said = false
  return (outcome) => {
    if (said) return
    said = true
    try { receipt(outcome) } catch { /* Optional measurement. */ }
  }
}

interface QueuedInput {
  deliveryId?: string
  inputContext?: string
  receipt?: MessageReceipt
  content: string
  bytes: number
  expiresAt: number
}

/** A message held while its agent changes host (`MoveGate`): submitted as itself at release, unless cancelled. */
interface HeldInput {
  deliveryId?: string
  bytes: number
  cancelled: boolean
}

interface InputState {
  /** The writes this agent's messages are making, one after another in the order they arrived. */
  writes?: Promise<void>
  deliveryId?: string
  deliveryFingerprint?: string
  dispatching?: boolean
  writing?: boolean
  cancelled?: boolean
  observedStart?: string
  turnOpen: boolean
  awaitingFingerprint: string | null
  awaitingContent: string | null
  /** The receipt of the person's message typed last, until it is settled ([settle]). */
  awaitingReceipt?: MessageReceipt
  /** Identical follow-ups still own different asynchronous composer observations. */
  personWriteVersion?: number
  controlLocked: boolean
  settling: boolean
  queue: QueuedInput[]
  /** The messages the move gate holds for this agent, in arrival order. Counted against the queue's limits,
   *  and cancellable as queued ones are. */
  held: HeldInput[]
  timer: NodeJS.Timeout | null
  settleTimer: NodeJS.Timeout | null
  retries: number
  observes: number
  ambiguousDispatch: boolean
}

export interface SessionInputDeps {
  readScreen: ScreenReader
  /** The reading of a typed prompt by the engines whose worker reads it (Claude Code, Codex): the pane after
   *  the paste, and a turn's prompt as recorded. Every verdict and every Enter stays here. */
  submission: SubmissionReader
  /** A team-only preflight at the actual write boundary. A reason proves no paste occurred. */
  beforeTeamWrite?: (session: RegisteredSession, deliveryId?: string) => Promise<string | null>
  onDelivery?: (event: SessionInputDelivery) => void
  getSession: (sessionId: string) => RegisteredSession | undefined
  validateRuntime: (session: RegisteredSession) => Promise<boolean>
  /** Boolean is retained for direct controller tests and legacy embedders. Production returns dispatch evidence. */
  inject: (terminalTarget: string, content: string, inputContext?: string) => Promise<boolean | TerminalActionResult>
  /** Host serializes the preflight and paste with other terminal writers. */
  injectTeam?: (terminalTarget: string, content: string, deliveryId: string) => Promise<boolean | TerminalActionResult>
  sendKey: (terminalTarget: string, key: string) => Promise<boolean | TerminalActionResult>
  capture?: (terminalTarget: string) => Promise<string | null>
  onError: (sessionId: string, message: string) => void
  /**
   * A message was accepted by the pane. Not every engine needs this — most announce the turn
   * themselves — but an engine that only writes its transcript once the turn is OVER has no other
   * moment at which a turn is known to have started, and this one is exact: we sent it.
   */
  onSubmitted?: (sessionId: string, content: string) => void
  /** Clock and timer for the lease wait; real ones by default. */
  now?: () => number
  sleep?: (ms: number) => Promise<void>
  /** While an agent changes host, its messages wait here and are typed into the pane it ends on. Absent: none
   *  is ever held. */
  moveGate?: MoveGate
}

/** A message not typed because of what the pane showed (messageHold.ts): nothing was written. */
function heldBack(delivery: boolean | TerminalActionResult): MessageHold | null {
  return typeof delivery !== 'boolean' && delivery.state === 'failed' && delivery.dispatch === 'not_started'
    && isMessageHold(delivery.reason) ? delivery.reason : null
}

/**
 * A write refused before a byte of it was written for a reason that passes: the pane's control lease, or
 * a screen with no composer on it yet, an engine starting or redrawing (messageHold.ts `passingHold`).
 */
function leaseRefused(delivery: boolean | TerminalActionResult): boolean {
  return typeof delivery !== 'boolean' && delivery.state === 'failed' && delivery.dispatch === 'not_started'
    && (delivery.reason === TERMINAL_LEASE_REFUSED || passingHold(delivery.reason))
}

function fingerprint(content: string): string {
  return createHash('sha256').update(content.replace(/\r\n/g, '\n').trim()).digest('hex')
}

/** Engine-aware prompt injection. Terminal TUIs get a bounded per-session FIFO while a turn is busy. */
export class SessionInputController {
  private states = new Map<string, InputState>()

  constructor(private readonly deps: SessionInputDeps) {}

  /**
   * An engine whose own TUI queues a message typed while a turn is running, and runs it when the turn ends,
   * says so in its submission policy (`typesWhileBusy`: Claude Code and Codex). For those the daemon types
   * immediately — the follow-up appears in the pane the moment it is spoken, and the TUI's queue is the one
   * the user can see and edit. Every other engine gets this file's FIFO, pasted only once the pane is idle.
   */
  private typesWhileBusy(engine: string): boolean {
    return this.deps.submission.policy(engine)?.typesWhileBusy === true
  }

  private swarmTypesWhileBusy(engine: string, deliveryId?: string): boolean {
    return !!deliveryId?.startsWith('team:service:superTabs:') && this.typesWhileBusy(engine)
  }

  private checksWhileBusy(session: RegisteredSession, state: InputState): boolean {
    return this.swarmTypesWhileBusy(session.engine, state.deliveryId)
      || (!state.deliveryId && this.swarmTypesWhileBusy(session.engine, state.queue[0]?.deliveryId))
  }

  /** Controller dependencies take the stable agent id, never a backend route. */
  private controlSession(id: string): RegisteredSession | undefined {
    return this.deps.getSession(id)
  }

  /**
   * The record the checks after a paste read the pane under. A message sent while its engine starts is
   * typed before the engine's first hook binds the conversation, and its turn can start after the verify
   * window: read as typed, the fenced readings refuse it and the message is reported unconfirmed. The
   * record as it now stands is taken when it is that launch, bound since (core/engines/sessionBinding.ts
   * `launchBound`); a rebind, a rotation, another pane or another process is read as typed, and fails closed.
   */
  private readingSession(session: RegisteredSession): RegisteredSession {
    return launchBound(session, this.controlSession(session.agentId))
  }

  /**
   * A paste the pane's control lease refused before a byte was written: the agent is there, but its
   * process is not yet the one the registry holds — a resume or restart moments ago, before the new
   * process was confirmed — or another writer holds the pane. Wait for the lease, up to
   * LEASE_WAIT_MS, rather than fail the message; nothing was written, so asking again can never type
   * it twice. Found end to end: a message sent as a resume was confirmed was refused 140 ms later and
   * lost, and a real engine takes seconds to confirm.
   */
  private async injectWhenLeased(
    write: () => Promise<boolean | TerminalActionResult>,
    current: () => boolean,
  ): Promise<boolean | TerminalActionResult> {
    const now = this.deps.now ?? Date.now
    const sleep = this.deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
    const deadline = now() + LEASE_WAIT_MS
    let delivery = await write()
    while (leaseRefused(delivery) && now() < deadline) {
      await sleep(LEASE_RETRY_MS)
      if (!current()) break
      delivery = await write()
    }
    return delivery
  }

  private state(sessionId: string): InputState {
    let value = this.states.get(sessionId)
    if (!value) {
      value = {
        turnOpen: false,
        awaitingFingerprint: null,
        awaitingContent: null,
        controlLocked: false,
        settling: false,
        queue: [],
        held: [],
        timer: null,
        settleTimer: null,
        retries: 0,
        observes: 0,
        ambiguousDispatch: false,
      }
      this.states.set(sessionId, value)
    }
    return value
  }

  setTurnOpen(sessionId: string, open: boolean): void {
    this.state(sessionId).turnOpen = open
  }

  private delivery(sessionId: string, deliveryId: string | undefined, state: SessionInputDelivery['state'], reason?: string): void {
    if (deliveryId) this.deps.onDelivery?.({ sessionId, deliveryId, state, ...(reason ? { reason } : {}) })
  }

  private finishDelivery(sessionId: string, state: InputState, outcome: SessionInputDelivery['state'], reason?: string): void {
    const id = state.deliveryId
    state.deliveryId = undefined
    state.deliveryFingerprint = undefined
    this.delivery(sessionId, id, outcome, reason)
  }

  /** The awaited person's message is settled as [outcome]: wherever its wait for a turn ends. */
  private settle(state: InputState, outcome: MessageOutcome): void {
    const receipt = state.awaitingReceipt
    state.awaitingReceipt = undefined
    receipt?.(outcome)
  }

  /** Revoke queued work only; a paste already in progress cannot be recalled. */
  cancelDelivery(deliveryId: string): boolean {
    for (const [sessionId, state] of this.states) {
      const held = state.held.findIndex((item) => item.deliveryId === deliveryId)
      if (held >= 0) {
        state.held[held].cancelled = true
        state.held.splice(held, 1)
        this.delivery(sessionId, deliveryId, 'rejected', 'cancelled')
        return true
      }
      const index = state.queue.findIndex((item) => item.deliveryId === deliveryId)
      if (index >= 0) {
        state.queue.splice(index, 1)
        this.delivery(sessionId, deliveryId, 'rejected', 'cancelled')
        return true
      }
      if (state.deliveryId === deliveryId && !state.writing && !state.awaitingFingerprint && !state.deliveryFingerprint) {
        state.cancelled = true
        this.finishDelivery(sessionId, state, 'rejected', 'cancelled')
        return true
      }
    }
    return false
  }

  /** [receipt]: what became of a person's message (one with no [deliveryId]), for its measurement. */
  submit(sessionId: string, content: string, deliveryId?: string, inputContext?: string, receipt?: MessageReceipt): void {
    const said = sayOnce(receipt)
    // An agent changing host has no pane to type into until the move ends: the message waits, as itself, and
    // is submitted then, through every check `submitNow` makes, into the pane the row then names.
    const agentId = this.controlSession(sessionId)?.agentId
    const gate = this.deps.moveGate
    if (agentId && gate?.holding(agentId)) {
      const state = this.state(sessionId)
      const bytes = Buffer.byteLength(content, 'utf8')
      if (this.refusedFull(sessionId, state, bytes, deliveryId, said)) return
      console.log(`[inject] ${sid(sessionId)} held · the agent is changing host · depth=${state.held.length + 1}`)
      const item: HeldInput = { deliveryId, bytes, cancelled: false }
      state.held.push(item)
      gate.enqueue(agentId, async () => {
        const at = state.held.indexOf(item)
        if (at >= 0) state.held.splice(at, 1)
        if (!item.cancelled) await this.submitNow(sessionId, content, deliveryId, inputContext, said)
      })
      return
    }
    void this.submitNow(sessionId, content, deliveryId, inputContext, said)
  }

  /**
   * `submit` past the move gate. Resolves once this message's write is done, or at once when it is queued
   * here or refused: the gate delivers what it held one at a time, and a keystroke held behind this message
   * must not land between its paste and its Enter.
   */
  private submitNow(sessionId: string, content: string, deliveryId?: string, inputContext?: string, said?: MessageReceipt): Promise<void> {
    const session = this.controlSession(sessionId)
    if (!session) {
      said?.('agent_gone')
      this.delivery(sessionId, deliveryId, 'rejected', 'agent_gone')
      if (!deliveryId?.startsWith('team:')) this.deps.onError(sessionId, 'This harness is no longer available.')
      return Promise.resolve()
    }
    const state = this.state(sessionId)
    this.dropExpired(sessionId, state)
    if (state.controlLocked
      || (this.swarmTypesWhileBusy(session.engine, deliveryId) && (state.writes || state.queue.length > 0))
      || (deliveryId && (state.deliveryId || state.dispatching || state.awaitingFingerprint
        || (!this.swarmTypesWhileBusy(session.engine, deliveryId) && (state.turnOpen || state.settling))))
      || (!this.typesWhileBusy(session.engine) && (state.turnOpen || state.awaitingFingerprint || state.settling))) {
      console.log(`[inject] ${sid(sessionId)} queued · engine=${session.engine} · depth=${state.queue.length + 1}`)
      this.enqueue(sessionId, state, content, deliveryId, inputContext, said)
      if (this.swarmTypesWhileBusy(session.engine, deliveryId) && state.turnOpen
        && !state.deliveryId && state.awaitingFingerprint && !state.timer) this.armSubmitCheck(sessionId, session, state)
      return Promise.resolve()
    }
    this.delivery(sessionId, deliveryId, 'queued')
    // One write at a time per agent, in the order the messages arrived. Claude Code and Codex take
    // typing while a turn runs, so a message is not held for the turn — but two pastes into one pane at
    // once interleave: one message's text lands between another's paste and its Enter, and the engine
    // receives a single prompt made of both. Found end to end: five messages sent within 30 ms became
    // two turns, "one" and "three" run together and the rest, out of order. Each write starts with the
    // agent as it is by then, which a restart in between may have changed.
    // With nothing in flight the write starts at once, so a cancel or a control request that follows
    // the submit sees it, as before.
    return this.scheduleWrite(sessionId, session, content, deliveryId, inputContext, said)
  }

  private scheduleWrite(sessionId: string, session: RegisteredSession, content: string, deliveryId?: string, inputContext?: string, receipt?: MessageReceipt): Promise<void> {
    const state = this.state(sessionId)
    const write = (): Promise<void> => this.inject(sessionId, this.controlSession(sessionId) ?? session, content, deliveryId, inputContext, receipt)
    const running = state.writes ? state.writes.then(write, write) : write()
    const settled: Promise<void> = running.catch(() => {}).then(() => {
      if (state.writes !== settled) return
      state.writes = undefined
      if (this.states.get(sessionId) === state && state.queue[0]?.deliveryId?.startsWith('team:service:superTabs:')) this.drainOne(sessionId, state)
    })
    state.writes = settled
    return settled
  }

  /** Reserve this pane for a short native control interaction such as `/model`. */
  /**
   * Take the terminal for a write that is not a new message.
   *
   * `forAnswer` exists because an engine's ask-the-user dialog opens INSIDE its turn — claude, agy and
   * every other engine with a question tool — so the `turnOpen` guard, which is there to stop an
   * INJECTED message colliding with a running turn, also blocked the one write that is only ever valid
   * during a turn. Measured on both claude and agy: the device's answer arrived, was refused here, and
   * the pane sat on the dialog looking like a hung agent, with nothing logged.
   *
   * Every other guard still applies: another writer holding the lock, a submit awaiting confirmation, a
   * settling turn, or queued messages all still refuse.
   */
  acquireControl(sessionId: string, opts?: { forAnswer?: boolean }): (() => void) | null {
    const session = this.controlSession(sessionId)
    if (!session) return null
    // Not while the agent changes host: what the holder typed would reach the pane being replaced. Refused
    // as a busy pane is, so the caller asks again (device input every 100 ms) and gets it after the move.
    const gate = this.deps.moveGate
    if (gate?.holding(session.agentId)) {
      gate.touch(session.agentId)
      return null
    }
    const state = this.state(sessionId)
    this.dropExpired(sessionId, state)
    const turnBlocks = state.turnOpen && !opts?.forAnswer
    if (state.controlLocked || turnBlocks || state.awaitingFingerprint || state.settling || state.queue.length > 0) return null
    state.controlLocked = true
    let released = false
    return () => {
      if (released) return
      released = true
      const current = this.states.get(sessionId)
      if (!current) return
      current.controlLocked = false
      this.drainOne(sessionId, current)
    }
  }

  /** Whether a caller holds this pane (`acquireControl`): a question being answered, a sequence of keys. */
  controlHeld(sessionId: string): boolean {
    return this.states.get(sessionId)?.controlLocked === true
  }

  onTurnStarted(sessionId: string, userMessage: string): void {
    const state = this.state(sessionId)
    const session = this.controlSession(sessionId)
    // An exact echo of the typed prompt needs no reading. Anything else is, for an engine whose worker
    // reads its submissions, that engine's to unwrap (Claude Code 2.1.283 records a bracketed paste inside
    // an envelope of its own), and is settled once it has; every other engine's record is compared whole.
    const observedFingerprint = fingerprint(userMessage)
    const engineReads = !!session && !!this.deps.submission.policy(session.engine)
    if (session && this.swarmTypesWhileBusy(session.engine, state.deliveryId) && state.deliveryFingerprint
      && state.deliveryFingerprint !== observedFingerprint && !state.writing) {
      // The native queue can start an earlier follow-up after the next has been pasted.
      // Only a matching echo settles this delivery; another start must leave its check armed.
      state.turnOpen = true
      const expected = state.deliveryFingerprint, deliveryId = state.deliveryId
      void this.echoes(session, userMessage, expected).then(matched => {
        if (matched && this.states.get(sessionId) === state && state.deliveryId === deliveryId
          && state.deliveryFingerprint === expected && state.awaitingContent !== null) {
          this.onTurnStarted(sessionId, state.awaitingContent)
        }
      })
      return
    }
    if (state.deliveryId && state.writing) state.observedStart = userMessage
    else if (state.deliveryId && state.deliveryFingerprint) {
      const expected = state.deliveryFingerprint
      if (expected === observedFingerprint || !engineReads) {
        this.finishDelivery(sessionId, state, expected === observedFingerprint ? 'started' : 'unknown',
          expected === observedFingerprint ? undefined : 'prompt_mismatch')
      } else {
        // Taken off the pane's state now, as a settled delivery is, so a write that follows never waits on
        // the reading; only what is said of this delivery waits for it.
        const deliveryId = state.deliveryId
        state.deliveryId = undefined
        state.deliveryFingerprint = undefined
        void this.echoes(session, userMessage, expected).then(started => this.delivery(sessionId, deliveryId,
          started ? 'started' : 'unknown', started ? undefined : 'prompt_mismatch'))
      }
    }
    if (state.settleTimer) clearTimeout(state.settleTimer)
    state.settleTimer = null
    state.settling = false
    state.turnOpen = true
    // Cursor does not clear its composer when it accepts a prompt: the submitted text stays on the "→"
    // line for the whole turn and long after it, so the terminal reads as if the question is still
    // waiting to be sent. Clearing before the NEXT paste (see inject) stops the two from running
    // together, but leaves that stale copy on screen in the meantime. Drop it as soon as the turn is
    // confirmed started.
    void this.clearCursorEcho(sessionId, userMessage)
    if (state.awaitingFingerprint) {
      const warn = () => console.warn(`[inject] ${sessionId.slice(0, 8)} observed a different terminal prompt while awaiting submit`)
      const expected = state.awaitingFingerprint
      const receipt = state.awaitingReceipt
      state.awaitingReceipt = undefined
      if (expected !== observedFingerprint) {
        if (engineReads) void this.echoes(session, userMessage, expected).then(matched => { if (!matched) warn(); receipt?.(matched ? 'started' : 'prompt_mismatch') })
        else { warn(); receipt?.('prompt_mismatch') }
      } else receipt?.('started')
      state.awaitingFingerprint = null
      state.awaitingContent = null
      state.retries = 0
      state.observes = 0
      state.ambiguousDispatch = false
      if (state.timer) clearTimeout(state.timer)
      state.timer = null
    }
    this.drainOne(sessionId, state)
  }

  /**
   * Whether a turn's prompt, as the engine recorded it, is the prompt typed: the part of the record the
   * engine says is the typed text, compared exactly. No reading is no match.
   */
  private async echoes(session: RegisteredSession, recorded: string, expected: string): Promise<boolean> {
    const span = await this.deps.submission.echo(session, recorded).catch(() => null)
    return !!span && fingerprint(recorded.slice(span.start, span.end)) === expected
  }

  /**
   * Remove Cursor's leftover copy of a just-submitted prompt from its composer.
   *
   * Guarded by a pane read on purpose: it only sends the clear when the composer still holds the exact
   * text we submitted. A blind C-u here would delete a follow-up the user had already started typing in
   * the terminal during the turn — a small window, but their keystrokes, not ours.
   */
  private async clearCursorEcho(sessionId: string, userMessage: string): Promise<void> {
    const session = this.controlSession(sessionId)
    if (session?.engine !== 'cursor' || !this.deps.capture) return
    try {
      const capture = await this.deps.capture(session.agentId)
      if (!capture || !cursorComposerContains(capture, userMessage)) return
      await this.deps.sendKey(session.agentId, 'C-u')
      console.log(`[inject] ${sid(sessionId)} cleared the echoed prompt from the Cursor composer`)
    } catch {
      /* best-effort cosmetics — never let this break the turn */
    }
  }

  onTurnEnded(sessionId: string): void {
    const state = this.state(sessionId)
    const current = this.controlSession(sessionId)
    if (current && this.swarmTypesWhileBusy(current.engine, state.deliveryId) && state.awaitingFingerprint) {
      // Ending the preceding turn says nothing about a follow-up already in the native queue.
      state.turnOpen = false
      this.armSubmitCheck(sessionId, current, state)
      return
    }
    if (!state.dispatching) this.finishDelivery(sessionId, state, 'unknown', 'turn_ended_without_start')
    // Typed while a turn ran, the engine holds it as that turn's follow-up; otherwise no turn was seen for it.
    this.settle(state, state.turnOpen ? 'taken' : 'turn_ended')
    state.turnOpen = false
    state.awaitingFingerprint = null
    state.awaitingContent = null
    state.retries = 0
    state.observes = 0
    state.ambiguousDispatch = false
    if (state.timer) clearTimeout(state.timer)
    state.timer = null
    const session = this.controlSession(sessionId)
    if (session?.engine === 'cursor') {
      // Cursor's stop hook can arrive just before its TUI has returned to the idle composer. A prompt
      // injected in that short window becomes a follow-up; Enter retries then enqueue it repeatedly.
      state.settling = true
      if (state.settleTimer) clearTimeout(state.settleTimer)
      state.settleTimer = setTimeout(() => {
        state.settleTimer = null
        state.settling = false
        this.drainOne(sessionId, state)
      }, CURSOR_TURN_SETTLE_MS)
      return
    }
    this.drainOne(sessionId, state)
  }

  cancel(sessionId: string): void {
    const session = this.controlSession(sessionId)
    if (!session) return
    void this.deps.validateRuntime(session).then(async (valid) => {
      if (!valid) { this.deps.onError(sessionId, 'This agent process is no longer running.'); return }
      await this.deps.sendKey(session.agentId, 'C-c')
      const state = this.state(sessionId)
      this.finishDelivery(sessionId, state, 'unknown', 'cancelled_after_paste')
      this.settle(state, 'cancelled')
      state.turnOpen = false
      state.awaitingFingerprint = null
      state.awaitingContent = null
      state.ambiguousDispatch = false
      if (state.timer) clearTimeout(state.timer)
      state.timer = null
      setTimeout(() => this.drainOne(sessionId, state), 250)
    })
  }

  async cancelConfirmed(sessionId: string): Promise<boolean> {
    const session = this.controlSession(sessionId)
    if (!session || !await this.deps.validateRuntime(session)) return false
    const result = await this.deps.sendKey(session.agentId, 'C-c')
    const state = this.state(sessionId)
    this.finishDelivery(sessionId, state, 'unknown', 'cancelled_after_paste')
    this.settle(state, 'cancelled')
    state.turnOpen = false
    state.awaitingFingerprint = null
    state.awaitingContent = null
    state.ambiguousDispatch = false
    if (state.timer) clearTimeout(state.timer)
    state.timer = null
    setTimeout(() => this.drainOne(sessionId, state), 250)
    return typeof result === 'boolean' ? result : result.dispatch === 'executed'
  }

  forget(sessionId: string): void {
    const state = this.states.get(sessionId)
    if (state?.timer) clearTimeout(state.timer)
    if (state?.settleTimer) clearTimeout(state.settleTimer)
    if (state) {
      this.finishDelivery(sessionId, state, state.writing || state.awaitingFingerprint || state.deliveryFingerprint ? 'unknown' : 'rejected', 'agent_gone')
      this.settle(state, 'ambiguous')
      for (const item of state.queue) {
        this.delivery(sessionId, item.deliveryId, 'rejected', 'agent_gone')
        item.receipt?.('agent_gone')
      }
      state.cancelled = true
    }
    this.states.delete(sessionId)
  }

  /** Preserve the established injection path for every caller that opts out of receipts. */
  private async injectLegacy(sessionId: string, session: RegisteredSession, content: string, inputContext?: string, receipt?: MessageReceipt): Promise<void> {
    const state = this.state(sessionId)
    state.personWriteVersion = (state.personWriteVersion ?? 0) + 1
    if (!(await this.deps.validateRuntime(session))) {
      console.warn(`[inject] ${sid(sessionId)} abort · engine=${session.engine} · process not running`)
      receipt?.('runtime_gone')
      this.deps.onError(sessionId, 'This agent process is no longer running.')
      return
    }
    if (session.engine === 'cursor') {
      // Cursor leaves the previous prompt sitting in its composer after the turn completes — the text is
      // still on the "→" line long after the answer and its recap have arrived. sendToTmux() types into
      // whatever is already there, so the next message is APPENDED to the last one and the pair is
      // submitted as a single run-on prompt:
      //   "…đầu tư dài hạn" + "Có nên mua thêm eth không…"
      // The agent then answers a question nobody asked, and the device shows a recap for it.
      //
      // The adapter already NOTICED this — onTurnStarted logs "observed a different terminal prompt while
      // awaiting submit" when the fingerprint of the started turn does not match what we sent — but it
      // only warned and carried on. Clear the line first so the composer is ours alone.
      //
      // C-u (kill-to-start-of-line) is a no-op on an empty composer, so this costs nothing in the normal
      // case. It does discard a draft a human was typing in the terminal — but pasting into that draft
      // would corrupt it into a run-on prompt anyway, which is worse and harder to notice.
      await this.deps.sendKey(session.agentId, 'C-u')
    }
    const delivery = await this.injectWhenLeased(() => this.write(session.agentId, content, inputContext),
      () => this.controlSession(session.agentId) !== undefined)
    const accepted = typeof delivery === 'boolean'
      ? delivery
      : delivery.state === 'succeeded' || delivery.dispatch === 'possibly_executed'
    const withheld = enterWithheldReason(delivery)
    if (withheld) {
      // Typed, its Enter not pressed: never pressed later either, which would send it into whatever is open.
      console.warn(`[inject] ${sid(sessionId)} typed, not sent · engine=${session.engine} · ${withheld} opened before Enter`)
      receipt?.('withheld')
      this.deps.onError(sessionId, messageWithheldText(session.engine, withheld))
      return
    }
    if (!accepted) {
      const held = heldBack(delivery)
      if (held) {
        console.warn(`[inject] ${sid(sessionId)} not typed · engine=${session.engine} · ${held}`)
        receipt?.('held')
        this.deps.onError(sessionId, messageHoldText(session.engine, held))
        return
      }
      console.warn(`[inject] ${sid(sessionId)} paste failed · engine=${session.engine} · target=${session.agentId}`)
      receipt?.('paste_failed')
      this.deps.onError(sessionId, 'The message could not be delivered to the agent.')
      return
    }
    console.log(`[inject] ${sid(sessionId)} paste ok · engine=${session.engine} · target=${session.agentId} · len=${content.length}`)
    // The one typed before it, never refused, was taken as the message before this one.
    this.settle(state, 'taken')
    state.awaitingReceipt = receipt
    state.awaitingFingerprint = fingerprint(content)
    state.awaitingContent = content
    state.retries = 0
    state.observes = 0
    state.ambiguousDispatch = typeof delivery !== 'boolean' && delivery.dispatch === 'possibly_executed'
    this.deps.onSubmitted?.(sessionId, content)
    this.armSubmitCheck(sessionId, session, state)
  }

  private write(id: string, content: string, inputContext?: string) {
    return inputContext ? this.deps.inject(id, content, inputContext) : this.deps.inject(id, content)
  }

  private async inject(sessionId: string, session: RegisteredSession, content: string, deliveryId?: string, inputContext?: string, receipt?: MessageReceipt): Promise<void> {
    const state = this.state(sessionId)
    if (!deliveryId) {
      // A later person write replaces the shared composer-check fields. Read the Swarm
      // acceptance first so its receipt is not lost merely because the person types sooner.
      if (this.swarmTypesWhileBusy(session.engine, state.deliveryId)) await this.settleSwarmAcceptance(sessionId, session, state)
      // A local submission keeps its original scheduling. Overlap removes our ability
      // to attribute a later terminal turn to the lamp; it must not block local input.
      this.finishDelivery(sessionId, state, 'unknown', 'prompt_mismatch')
      if (!receipt) return this.injectLegacy(sessionId, session, content, inputContext)
      // A write that threw may have typed something: unknown, and thrown on as before.
      return this.injectLegacy(sessionId, session, content, inputContext, receipt).catch((error: unknown) => {
        receipt('ambiguous')
        throw error
      })
    }
    state.deliveryId = deliveryId
    state.deliveryFingerprint = undefined
    state.dispatching = true
    state.cancelled = false
    try {
      if (!(await this.deps.validateRuntime(session))) {
        console.warn(`[inject] ${sid(sessionId)} abort · engine=${session.engine} · process not running`)
        this.finishDelivery(sessionId, state, 'rejected', 'runtime_gone_pre_paste')
        if (!deliveryId.startsWith('team:')) this.deps.onError(sessionId, 'This agent process is no longer running.')
        return
      }
      if (state.cancelled || this.states.get(sessionId) !== state) return
      if (deliveryId.startsWith('team:')) {
        const held = this.deps.beforeTeamWrite ? await this.deps.beforeTeamWrite(session, deliveryId) : 'team_waiting_unavailable'
        if (state.cancelled || this.states.get(sessionId) !== state) return
        if (held) { this.finishDelivery(sessionId, state, 'rejected', held); return }
      }
      if (session.engine === 'cursor' && !deliveryId.startsWith('team:')) {
        // Cursor leaves the previous prompt sitting in its composer after the turn completes — the text is
        // still on the "→" line long after the answer and its recap have arrived. sendToTmux() types into
        // whatever is already there, so the next message is APPENDED to the last one and the pair is
        // submitted as a single run-on prompt:
        //   "…đầu tư dài hạn" + "Có nên mua thêm eth không…"
        // The agent then answers a question nobody asked, and the device shows a recap for it.
        //
        // The adapter already NOTICED this — onTurnStarted logs "observed a different terminal prompt while
        // awaiting submit" when the fingerprint of the started turn does not match what we sent — but it
        // only warned and carried on. Clear the line first so the composer is ours alone.
        //
        // C-u (kill-to-start-of-line) is a no-op on an empty composer, so this costs nothing in the normal
        // case. It does discard a draft a human was typing in the terminal — but pasting into that draft
        // would corrupt it into a run-on prompt anyway, which is worse and harder to notice.
        await this.deps.sendKey(session.agentId, 'C-u')
      }
      if (state.cancelled || this.states.get(sessionId) !== state) return
      state.writing = true
      const delivery = await this.injectWhenLeased(() => (deliveryId.startsWith('team:') && this.deps.injectTeam
        ? this.deps.injectTeam(session.agentId, content, deliveryId) : this.write(session.agentId, content, inputContext)),
      () => !state.cancelled && this.states.get(sessionId) === state)
      state.writing = false
      if (state.cancelled || this.states.get(sessionId) !== state) return
      if (typeof delivery !== 'boolean' && delivery.state === 'failed' && delivery.dispatch === 'not_started' && delivery.reason.startsWith('team_waiting_')) {
        this.finishDelivery(sessionId, state, 'rejected', delivery.reason)
        return
      }
      const withheld = enterWithheldReason(delivery)
      if (withheld) {
        // Typed, its Enter not pressed: never pressed later either, which would send it into whatever is open.
        console.warn(`[inject] ${sid(sessionId)} typed, not sent · engine=${session.engine} · ${withheld} opened before Enter`)
        this.finishDelivery(sessionId, state, 'rejected', 'enter_withheld')
        if (!deliveryId.startsWith('team:')) this.deps.onError(sessionId, messageWithheldText(session.engine, withheld))
        return
      }
      const held = heldBack(delivery)
      if (held) {
        console.warn(`[inject] ${sid(sessionId)} not typed · engine=${session.engine} · ${held}`)
        this.finishDelivery(sessionId, state, 'rejected', held)
        // An Agent Messages turn is automatic, and its mailbox hears of the refusal; anyone else's is a person's to see.
        if (!deliveryId.startsWith('team:')) this.deps.onError(sessionId, messageHoldText(session.engine, held))
        return
      }
      const accepted = typeof delivery === 'boolean'
        ? delivery
        : delivery.state === 'succeeded' || delivery.dispatch === 'possibly_executed'
      if (!accepted) {
        console.warn(`[inject] ${sid(sessionId)} paste failed · engine=${session.engine} · target=${session.agentId}`)
        this.finishDelivery(sessionId, state, 'rejected', 'paste_failed')
        this.deps.onError(sessionId, 'The message could not be delivered to the agent.')
        return
      }
      console.log(`[inject] ${sid(sessionId)} paste ok · engine=${session.engine} · target=${session.agentId} · len=${content.length}`)
      state.awaitingFingerprint = fingerprint(content)
      state.deliveryFingerprint = state.awaitingFingerprint
      state.awaitingContent = content
      state.retries = 0
      state.observes = 0
      state.ambiguousDispatch = typeof delivery !== 'boolean' && delivery.dispatch === 'possibly_executed'
      state.dispatching = false
      if (!this.swarmTypesWhileBusy(session.engine, state.deliveryId)) this.delivery(sessionId, state.deliveryId, 'delivered')
      if (state.observedStart !== undefined) {
        const observed = state.observedStart
        state.observedStart = undefined
        this.onTurnStarted(sessionId, observed)
      }
      this.deps.onSubmitted?.(sessionId, content)
      this.armSubmitCheck(sessionId, session, state)
    } catch {
      this.finishDelivery(sessionId, state, state.writing || state.awaitingFingerprint ? 'unknown' : 'rejected', state.writing || state.awaitingFingerprint ? 'dispatch_ambiguous' : 'runtime_gone_pre_paste')
      this.deps.onError(sessionId, 'The message delivery could not be confirmed. Check the agent before trying again.')
    } finally {
      state.writing = false
      state.dispatching = false
      if (!state.awaitingFingerprint && !state.turnOpen) this.drainOne(sessionId, state)
    }
  }

  private armSubmitCheck(sessionId: string, session: RegisteredSession, state: InputState): void {
    if (state.timer) clearTimeout(state.timer)
    state.timer = setTimeout(() => {
      state.timer = null
      if (!state.awaitingFingerprint || (state.turnOpen && !this.checksWhileBusy(session, state))) return
      const retry = this.retrySubmit(sessionId, session, state)
      if (state.deliveryId) void retry.catch(() => this.failAmbiguousSubmission(sessionId, state))
      else void retry
    }, this.deps.submission.policy(session.engine)?.verifyMs ?? (session.engine === 'opencode'
        ? OPENCODE_SUBMIT_VERIFY_MS
        : session.engine === 'pi'
          ? PI_SUBMIT_VERIFY_MS
          : session.engine === 'hermes'
            ? HERMES_SUBMIT_VERIFY_MS
            : session.engine === 'commandcode'
              ? COMMANDCODE_SUBMIT_VERIFY_MS
              : session.engine === 'devin'
                ? DEVIN_SUBMIT_VERIFY_MS
                : session.engine === 'muse'
                  ? MUSE_SUBMIT_VERIFY_MS
                  : session.engine === 'amp'
                    ? AMP_SUBMIT_VERIFY_MS
                    : session.engine === 'kilo'
                      ? KILO_SUBMIT_VERIFY_MS
                      : session.engine === 'grok'
                        ? GROK_SUBMIT_VERIFY_MS
                        : session.engine === 'agy'
                          ? AGY_SUBMIT_VERIFY_MS
                          : session.engine === 'copilot'
                            ? COPILOT_SUBMIT_VERIFY_MS
                      : SUBMIT_VERIFY_MS))
  }

  private async retrySubmit(sessionId: string, session: RegisteredSession, state: InputState): Promise<void> {
    if (state.turnOpen && !state.deliveryId) {
      await this.observeBusyPerson(sessionId, session, state)
      return
    }
    if (this.swarmTypesWhileBusy(session.engine, state.deliveryId)) {
      // Use the same native composer reading as person input. A cleared composer confirms
      // queue acceptance without waiting for a new turn; automatic traffic never retries Enter.
      if (await this.settleSwarmAcceptance(sessionId, session, state)) return
      if (++state.observes <= SUBMIT_MAX_OBSERVES) this.armSubmitCheck(sessionId, session, state)
      else this.failAmbiguousSubmission(sessionId, state)
      return
    }
    if (state.deliveryId?.startsWith('team:')) {
      // Team traffic is automatic. A missing transcript start is not permission to press Enter
      // again: the message may already be in the engine's queue. Inbox/reply correlation can
      // still finish the exchange even when the terminal receipt remains uncertain.
      if (++state.observes <= SUBMIT_MAX_OBSERVES) this.armSubmitCheck(sessionId, session, state)
      else this.failAmbiguousSubmission(sessionId, state)
      return
    }
    if (session.engine === 'cursor') {
      const capture = await this.deps.capture?.(session.agentId)
      if (!state.awaitingFingerprint || state.turnOpen) return
      if (await this.dialogOverComposer(sessionId, session, state, capture)) return
      const draftPending = !!capture && cursorComposerContains(capture, state.awaitingContent ?? '')
      if (state.ambiguousDispatch && !draftPending) {
        this.failAmbiguousSubmission(sessionId, state)
        return
      }
      if (capture && cursorSubmissionAccepted(capture, state.awaitingContent ?? '')) {
        if (state.deliveryId && ++state.observes > SUBMIT_MAX_OBSERVES) {
          this.failAmbiguousSubmission(sessionId, state)
          return
        }
        // The transcript hook can trail the TUI by a moment. Observe again without pressing Enter:
        // another Enter here would duplicate a running/queued follow-up.
        this.armSubmitCheck(sessionId, session, state)
        return
      }
      if (!draftPending) {
        console.warn(`[inject] ${sid(sessionId)} not accepted · engine=cursor · composer clear of draft`)
        state.awaitingFingerprint = null
        state.awaitingContent = null
        this.settle(state, 'not_submitted')
        this.finishDelivery(sessionId, state, 'unknown', 'not_submitted')
        this.deps.onError(sessionId, 'The agent did not accept the message. Please try again.')
        return
      }
    } else if (session.engine === 'opencode' || session.engine === 'kilo' || session.engine === 'pi' || session.engine === 'hermes' || session.engine === 'muse'
      || session.engine === 'amp' || session.engine === 'grok' || session.engine === 'agy' || session.engine === 'copilot') {
      // OpenCode has no composer glyph, and the submitted text stays visible in the message area, so a
      // pane scrape can't tell "still in the composer" from "already sent". Rely purely on the reader-
      // derived turn_started (a new user row in opencode.db) to clear awaitingFingerprint; if it hasn't
      // arrived yet, fall through to a bounded retry-Enter, then error.
      if (!state.awaitingFingerprint || state.turnOpen) return
      if (state.ambiguousDispatch) {
        this.failAmbiguousSubmission(sessionId, state)
        return
      }
    } else {
      // Claude Code and Codex (their worker reads the pane) and Command Code: verify against the terminal
      // before pressing Enter again or declaring failure.
      const capture = await this.deps.capture?.(session.agentId)
      if (!state.awaitingFingerprint || state.turnOpen) return
      if (await this.dialogOverComposer(sessionId, session, state, capture)) return
      // Command Code writes the user line to its transcript only once the model has finished THINKING, so
      // the turn_started this used to wait for can be half a minute late on a real task — and the user
      // watched the terminal accept the message and start working while the device claimed it had been
      // refused. The pane says so immediately: a running turn shows "esc to interrupt". Treat that as the
      // acceptance it is, rather than timing out into an error the user can see is false.
      if (capture && session.engine === 'commandcode' && /esc to interrupt/i.test(visibleTerminal(capture))) {
        console.log(`[inject] ${sid(sessionId)} accepted (agent working) · engine=commandcode`)
        // Keep the optional delivery fingerprint for the real transcript start.
        // Visible work confirms acceptance; it must not be timed out as a failed submit.
        state.awaitingFingerprint = null
        state.awaitingContent = null
        state.observes = 0
        state.ambiguousDispatch = false
        this.settle(state, 'taken')
        return
      }
      if (capture) {
        // The engine's own reading for Claude Code and Codex, from their worker; the core's for the others.
        const prompt = state.awaitingContent ?? ''
        const reading = this.deps.submission.policy(session.engine)
          ? await this.deps.submission.read(this.readingSession(session), capture, prompt).catch(() => null)
          : { draft: composerHolds(capture, prompt), composer: composerShown(capture) }
        if (this.states.get(sessionId) !== state || !state.awaitingFingerprint || state.turnOpen) return
        // No reading is no evidence (the engine's worker down, or the agent rebound while it read): never
        // an Enter on it, and never a claim the message was or was not taken, as for an unreadable screen.
        if (!reading) {
          this.failAmbiguousSubmission(sessionId, state)
          return
        }
        if (!reading.draft) {
          this.leftComposer(sessionId, session, state, reading.composer)
          return
        }
      }
      // capture === null (dep missing / unreadable) → fall through to today's blind retry/error so a
      // real delivery failure is never hidden.
      if (!capture && state.ambiguousDispatch) {
        this.failAmbiguousSubmission(sessionId, state)
        return
      }
    }
    if (state.retries >= SUBMIT_MAX_RETRIES) {
      console.warn(`[inject] ${sid(sessionId)} not accepted · engine=${session.engine} · gave up after ${state.retries} retries`)
      state.awaitingFingerprint = null
      state.awaitingContent = null
      state.ambiguousDispatch = false
      this.settle(state, 'not_submitted')
      this.finishDelivery(sessionId, state, 'unknown', 'not_submitted')
      this.deps.onError(sessionId, 'The agent did not accept the message. Please try again.')
      return
    }
    state.retries++
    const valid = await this.deps.validateRuntime(session)
    if (!valid) {
      this.finishDelivery(sessionId, state, 'unknown', 'runtime_gone_post_paste')
      this.settle(state, 'runtime_gone')
      state.awaitingFingerprint = null
      state.awaitingContent = null
      state.ambiguousDispatch = false
      this.deps.onError(sessionId, 'This agent process is no longer running.')
      return
    }
    if (state.deliveryId && (this.states.get(sessionId) !== state || !state.awaitingFingerprint || state.turnOpen)) return
    // Said once the engine is known to be there: an engine that exited gets no Enter, and the log used
    // to claim one anyway.
    console.log(`[inject] ${sid(sessionId)} resubmit Enter · engine=${session.engine} · retry=${state.retries}/${SUBMIT_MAX_RETRIES}`)
    // Only the submit key is retried. The prompt body is never pasted twice.
    const delivery = await this.deps.sendKey(session.agentId, 'Enter')
    state.ambiguousDispatch = typeof delivery === 'boolean'
      ? !delivery
      : delivery.dispatch === 'possibly_executed'
    this.armSubmitCheck(sessionId, session, state)
  }

  /** A queued Swarm item may follow a person input already accepted by the busy engine. Observe only
   * enough to release it: a hidden composer or unavailable reader must leave the person's receipt for
   * its real turn event, as before, rather than run the idle retry/error path. */
  private async observeBusyPerson(sessionId: string, session: RegisteredSession, state: InputState): Promise<void> {
    const expected = state.awaitingFingerprint, version = state.personWriteVersion
    if (!expected || state.observes >= SUBMIT_MAX_OBSERVES) return
    const current = () => this.states.get(sessionId) === state && state.awaitingFingerprint === expected && state.personWriteVersion === version
      && !state.deliveryId && state.turnOpen && this.swarmTypesWhileBusy(session.engine, state.queue[0]?.deliveryId)
    if (!current()) return
    state.observes++
    const capture = await this.deps.capture?.(session.agentId).catch(() => null)
    if (!current() || !capture) return
    const screen = await this.deps.readScreen(this.readingSession(session), capture).catch(() => null)
    if (!current() || !screen || screen.messageHold) return
    const reading = await this.deps.submission.read(this.readingSession(session), capture, state.awaitingContent ?? '').catch(() => null)
    if (!current() || !reading) return
    if (reading.composer && !reading.draft && !state.ambiguousDispatch) {
      state.awaitingFingerprint = null
      state.awaitingContent = null
      state.observes = 0
      this.settle(state, 'taken')
      this.drainOne(sessionId, state)
    } else if (state.observes < SUBMIT_MAX_OBSERVES) this.armSubmitCheck(sessionId, session, state)
  }

  /** Settle only this pasted Swarm prompt, before its composer state can be replaced by another writer. */
  private async settleSwarmAcceptance(sessionId: string, session: RegisteredSession, state: InputState): Promise<boolean> {
    const expected = state.awaitingFingerprint, deliveryId = state.deliveryId
    if (!expected || state.ambiguousDispatch) return false
    const capture = await this.deps.capture?.(session.agentId).catch(() => null)
    if (this.states.get(sessionId) !== state || state.awaitingFingerprint !== expected || state.deliveryId !== deliveryId) return true
    if (!capture) return false
    const record = this.readingSession(session)
    const [reading, screen] = await Promise.all([
      this.deps.submission.read(record, capture, state.awaitingContent ?? '').catch(() => null),
      this.deps.readScreen(record, capture).catch(() => null),
    ])
    if (this.states.get(sessionId) !== state || state.awaitingFingerprint !== expected || state.deliveryId !== deliveryId) return true
    // Enter was executed after the pre-Enter dialog guard. A permission or question
    // that replaced the composer afterwards is acceptance, as it is for person input.
    const asked = screen?.messageHold === 'permission_open' || screen?.messageHold === 'question_open'
    if (!asked && !(reading && !reading.draft && reading.composer)) return false
    this.finishDelivery(sessionId, state, 'delivered')
    state.awaitingFingerprint = null
    state.awaitingContent = null
    state.observes = 0
    if (state.timer) clearTimeout(state.timer)
    state.timer = null
    this.drainOne(sessionId, state)
    return true
  }

  /**
   * Our text left the composer: submitted, or queued by the TUI as a follow-up while busy. A real
   * turn_started will confirm and clear this; keep observing (bounded) WITHOUT pressing Enter — a second
   * Enter could double-submit a queued follow-up — and WITHOUT a spurious error.
   */
  private leftComposer(sessionId: string, session: RegisteredSession, state: InputState, composer: boolean): void {
    if (state.observes < SUBMIT_MAX_OBSERVES) {
      state.observes++
      console.log(`[inject] ${sid(sessionId)} accepted (queued/submitted) · engine=${session.engine} · observe=${state.observes}/${SUBMIT_MAX_OBSERVES}`)
      this.armSubmitCheck(sessionId, session, state)
      return
    }
    // An ambiguous dispatch with no visible draft still may have run. It can never justify Enter.
    if (state.ambiguousDispatch) {
      this.failAmbiguousSubmission(sessionId, state)
      return
    }
    if (state.deliveryId || !composer) {
      // A receipt promises a correlated turn, which the pane alone cannot prove. Report unknown,
      // also when no composer is visible. Never retry Enter into a dialog or a new human draft.
      this.failAmbiguousSubmission(sessionId, state)
      return
    }
    // The paste succeeded and our text left the composer. Stop polling without claiming that the
    // agent started or failed. Its real turn event can arrive much later; pressing Enter again can
    // submit somebody else's draft. This was the false "Claude didn't start" on a queued voice turn.
    console.log(`[inject] ${sid(sessionId)} submit left composer; awaiting agent turn · engine=${session.engine}`)
    state.awaitingFingerprint = null
    state.awaitingContent = null
    state.observes = 0
    this.settle(state, 'taken')
    if (this.swarmTypesWhileBusy(session.engine, state.queue[0]?.deliveryId)) this.drainOne(sessionId, state)
  }

  /**
   * A dialog, a menu or a view over the composer, settled without an Enter. The prompt line the retry
   * reads is then the transcript's echo of this very message, not a draft, and an Enter answers the
   * dialog: on a permission prompt, "1. Yes", a command nobody approved. A prompt or a question the
   * agent asks means the message was taken and its turn has reached a tool; anything else leaves it
   * unknown, as does any delivery with a receipt, which the pane alone cannot settle.
   */
  private async dialogOverComposer(sessionId: string, session: RegisteredSession, state: InputState, capture: string | null | undefined): Promise<boolean> {
    if (capture === undefined) return false
    const screen = await this.deps.readScreen(this.readingSession(session), capture)
    if (this.states.get(sessionId) !== state || state.turnOpen || !state.awaitingFingerprint) return true
    const hold = screen ? screen.messageHold : 'screen_unreadable'
    if (!hold) return false
    if (state.deliveryId || (hold !== 'permission_open' && hold !== 'question_open')) {
      this.failAmbiguousSubmission(sessionId, state)
      return true
    }
    console.log(`[inject] ${sid(sessionId)} accepted (${hold} on screen) · engine=${session.engine}`)
    state.awaitingFingerprint = null
    state.awaitingContent = null
    state.observes = 0
    state.ambiguousDispatch = false
    this.settle(state, 'taken')
    if (this.swarmTypesWhileBusy(session.engine, state.queue[0]?.deliveryId)) this.drainOne(sessionId, state)
    return true
  }

  private failAmbiguousSubmission(sessionId: string, state: InputState): void {
    this.finishDelivery(sessionId, state, 'unknown', 'dispatch_ambiguous')
    this.settle(state, 'ambiguous')
    state.awaitingFingerprint = null
    state.awaitingContent = null
    state.ambiguousDispatch = false
    this.deps.onError(sessionId, 'The message delivery could not be confirmed. Check the agent before trying again.')
  }

  private drainOne(sessionId: string, state: InputState): void {
    // A queued message whose turn is due while the agent changes host goes behind what the gate holds.
    const agentId = this.controlSession(sessionId)?.agentId
    const gate = this.deps.moveGate
    if (agentId && gate?.holding(agentId)) {
      gate.enqueue(agentId, async () => { const current = this.states.get(sessionId); if (current) await this.drainNow(sessionId, current) })
      return
    }
    void this.drainNow(sessionId, state)
  }

  private async drainNow(sessionId: string, state: InputState): Promise<void> {
    this.dropExpired(sessionId, state)
    const current = this.controlSession(sessionId)
    const busySwarm = !!current && this.swarmTypesWhileBusy(current.engine, state.queue[0]?.deliveryId)
    // A person write may still be awaiting its terminal result when several chat
    // deliveries arrive. Reserve one Swarm receipt only after that writer finishes.
    if (busySwarm && state.writes) return
    if (state.controlLocked || (!busySwarm && (state.turnOpen || state.settling)) || state.awaitingFingerprint) return
    if (state.queue[0]?.deliveryId && (state.dispatching || state.deliveryId)) return
    const next = state.queue.shift()
    if (!next) return
    const session = this.controlSession(sessionId)
    if (!session) {
      this.delivery(sessionId, next.deliveryId, 'rejected', 'agent_gone')
      next.receipt?.('agent_gone')
      if (!next.deliveryId?.startsWith('team:')) this.deps.onError(sessionId, 'This harness is no longer available.')
      return
    }
    if (busySwarm) await this.scheduleWrite(sessionId, session, next.content, next.deliveryId, next.inputContext, next.receipt)
    else await this.inject(sessionId, session, next.content, next.deliveryId, next.inputContext, next.receipt)
  }

  private enqueue(sessionId: string, state: InputState, content: string, deliveryId?: string, inputContext?: string, receipt?: MessageReceipt): void {
    const bytes = Buffer.byteLength(content, 'utf8')
    if (this.refusedFull(sessionId, state, bytes, deliveryId, receipt)) return
    state.queue.push({ content, bytes, expiresAt: Date.now() + ITEM_TTL_MS, deliveryId, inputContext, ...(receipt ? { receipt } : {}) })
    this.delivery(sessionId, deliveryId, 'queued')
  }

  /** Refuse a message of [bytes] when the agent's queued and held messages are at their limits. */
  private refusedFull(sessionId: string, state: InputState, bytes: number, deliveryId?: string, receipt?: MessageReceipt): boolean {
    const waiting = [...state.queue, ...state.held]
    const waitingBytes = waiting.reduce((sum, item) => sum + item.bytes, 0)
    if (waiting.length < MAX_QUEUE_ITEMS && waitingBytes + bytes <= MAX_QUEUE_BYTES) return false
    this.delivery(sessionId, deliveryId, 'rejected', 'queue_full')
    receipt?.('queue_full')
    if (!deliveryId?.startsWith('team:')) this.deps.onError(sessionId, 'This agent already has too many queued messages. Try again after the current operation finishes.')
    return true
  }

  private dropExpired(sessionId: string, state: InputState): void {
    const now = Date.now()
    const expiredLocalInput = state.queue.some(item => item.expiresAt <= now && !item.deliveryId?.startsWith('team:'))
    for (const item of state.queue) {
      if (item.expiresAt > now) continue
      this.delivery(sessionId, item.deliveryId, 'rejected', 'queue_expired')
      item.receipt?.('queue_expired')
    }
    state.queue = state.queue.filter((item) => item.expiresAt > now)
    if (expiredLocalInput) this.deps.onError(sessionId, 'A queued message expired before the agent became available.')
  }
}

function cursorComposerContains(capture: string, content: string): boolean {
  const visible = visibleTerminal(capture)
  const marker = visible.lastIndexOf('→')
  if (marker < 0) return false
  const expected = normalizedTerminalText(content)
  return !!expected && normalizedTerminalText(visible.slice(marker + 1)).includes(expected)
}

function cursorSubmissionAccepted(capture: string, content: string): boolean {
  const visible = visibleTerminal(capture)
  if (/\bfollow-ups\b/i.test(visible)) return true
  if (/\b(?:Working|Running subagent|Thinking)\b/i.test(visible)) return true
  return !cursorComposerContains(visible, content)
}