@alwith/module-computer 0.0.0-stage → 0.1.1

package/rust/src/gateway.rs

@@ -0,0 +1,774 @@
+//! Session-bound MCP transport and FIFO desktop ownership. No conversation persistence.
+use crate::Connection;
+use serde::Serialize;
+use serde_json::{Value, json};
+use std::{
+    collections::{HashMap, HashSet, VecDeque},
+    sync::{Arc, Mutex},
+    time::{Duration, Instant},
+};
+use tokio::{
+    io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader},
+    net::{TcpListener, TcpStream},
+    process::Command,
+    sync::{Notify, watch},
+};
+use uuid::Uuid;
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, specta::Type)]
+#[serde(rename_all = "camelCase")]
+pub struct Target {
+    pub pid: u32,
+    pub window_id: u32,
+}
+#[derive(Clone, Debug, Serialize, specta::Type)]
+#[serde(rename_all = "camelCase")]
+pub struct Activity {
+    pub session_id: String,
+    pub phase: String,
+    pub queue_position: usize,
+    pub owner_session_id: Option<String>,
+    pub action: Option<String>,
+    pub target: Option<Target>,
+    pub revision: u64,
+}
+struct PreviewCommand {
+    revision: u64,
+    focus: bool,
+    reply: tokio::sync::oneshot::Sender<Result<Value, String>>,
+}
+struct Entry {
+    session: Option<String>,
+    driver: Connection,
+    created: Instant,
+    cancel: watch::Sender<bool>,
+    connected: bool,
+    initialized: bool,
+    listed: bool,
+    tools: HashSet<String>,
+    labeled_tools: HashSet<String>,
+    preview: Option<tokio::sync::mpsc::UnboundedSender<PreviewCommand>>,
+}
+#[derive(Default)]
+struct State {
+    entries: HashMap<String, Entry>,
+    owner: Option<String>,
+    queue: VecDeque<String>,
+    running: HashSet<String>,
+    blocked: HashSet<String>,
+    action: Option<String>,
+    target: Option<Target>,
+    revision: u64,
+    in_flight: usize,
+    release_pending: bool,
+    faulted: bool,
+}
+pub struct Gateway {
+    state: Mutex<State>,
+    changed: Notify,
+    address: Mutex<Option<String>>,
+}
+impl Default for Gateway {
+    fn default() -> Self {
+        Self { state: Mutex::new(State::default()), changed: Notify::new(), address: Mutex::new(None) }
+    }
+}
+impl Gateway {
+    pub async fn listen(self: &Arc<Self>) -> Result<(), String> {
+        let listener = TcpListener::bind("127.0.0.1:0").await.map_err(|e| e.to_string())?;
+        *self.address.lock().unwrap() = Some(listener.local_addr().map_err(|e| e.to_string())?.to_string());
+        let weak = Arc::downgrade(self);
+        tokio::spawn(async move {
+            loop {
+                let Ok((stream, _)) = listener.accept().await else { break };
+                let Some(gateway) = weak.upgrade() else { break };
+                tokio::spawn(async move {
+                    let _ = gateway.serve(stream).await;
+                });
+            }
+        });
+        Ok(())
+    }
+    pub fn register(&self, driver: Connection) -> Result<(String, String), String> {
+        let address = self.address.lock().unwrap().clone().ok_or("Computer gateway is not ready")?;
+        let token = Uuid::new_v4().to_string();
+        let mut state = self.state.lock().unwrap();
+        state.entries.retain(|_, e| e.connected || e.created.elapsed() < Duration::from_secs(300));
+        state.entries.insert(
+            token.clone(),
+            Entry {
+                session: None,
+                driver,
+                created: Instant::now(),
+                cancel: watch::channel(false).0,
+                connected: false,
+                initialized: false,
+                listed: false,
+                tools: HashSet::new(),
+                labeled_tools: HashSet::new(),
+                preview: None,
+            },
+        );
+        Ok((token, address))
+    }
+    pub fn bind(&self, token: &str, session: &str) -> Result<(), String> {
+        if session.is_empty() {
+            return Err("Missing conversation identity".into());
+        }
+        let mut s = self.state.lock().unwrap();
+        if !s.entries.contains_key(token) {
+            return Err("Computer connection expired".into());
+        }
+        let previous: Vec<_> = s
+            .entries
+            .iter()
+            .filter(|(key, e)| key.as_str() != token && e.session.as_deref() == Some(session))
+            .map(|(key, _)| key.clone())
+            .collect();
+        if previous.iter().any(|key| s.owner.as_ref() == Some(key)) {
+            return Err("Cannot replace an active computer connection".into());
+        }
+        if s.entries[token].session.as_deref().is_some_and(|id| id != session) {
+            return Err("Computer connection is already bound".into());
+        }
+        for key in previous {
+            if let Some(e) = s.entries.remove(&key) {
+                e.cancel.send_replace(true);
+            }
+            s.queue.retain(|queued| queued != &key);
+        }
+        let e = s.entries.get_mut(token).ok_or("Computer connection expired")?;
+        if e.session.as_deref().is_some_and(|id| id != session) {
+            return Err("Computer connection is already bound".into());
+        }
+        e.session = Some(session.into());
+        drop(s);
+        self.changed.notify_waiters();
+        Ok(())
+    }
+    /// Readiness belongs to the actual Codex MCP connection, not a separate probe.
+    pub async fn ensure_ready(&self, session: &str) -> Result<(), String> {
+        tokio::time::timeout(Duration::from_secs(20), async {
+            loop {
+                {
+                    let s = self.state.lock().unwrap();
+                    if s.faulted {
+                        return Err("Computer transport needs to restart".into());
+                    }
+                    let e = s
+                        .entries
+                        .values()
+                        .find(|e| e.session.as_deref() == Some(session))
+                        .ok_or("Computer connection closed; retry to reconnect")?;
+                    if *e.cancel.borrow() {
+                        return Err("Computer connection revoked".into());
+                    }
+                    if e.initialized && e.listed {
+                        if ["list_windows", "get_window_state", "click", "run_steps"]
+                            .iter()
+                            .all(|name| e.tools.contains(*name))
+                        {
+                            return Ok(());
+                        }
+                        return Err("Computer server is missing required tools".into());
+                    }
+                }
+                tokio::time::sleep(Duration::from_millis(50)).await;
+            }
+        })
+        .await
+        .map_err(|_| "Computer MCP initialization timed out; retry to reconnect".to_string())?
+    }
+    fn observe_discovery(&self, token: &str, request: &Value, response: &Value) {
+        let mut s = self.state.lock().unwrap();
+        let Some(e) = s.entries.get_mut(token) else { return };
+        match request["method"].as_str() {
+            Some("initialize") => e.initialized = response["result"]["protocolVersion"].is_string(),
+            Some("tools/list") => {
+                e.listed = false;
+                if let Some(tools) = response["result"]["tools"].as_array() {
+                    if request["params"]["cursor"].is_null() {
+                        e.tools.clear();
+                        e.labeled_tools.clear();
+                    }
+                    e.labeled_tools.extend(
+                        tools
+                            .iter()
+                            .filter(|t| t["inputSchema"]["properties"].get("session").is_some())
+                            .filter_map(|t| t["name"].as_str().map(String::from)),
+                    );
+                    e.tools.extend(tools.iter().filter_map(|t| t["name"].as_str().map(String::from)));
+                    e.listed = response["result"]["nextCursor"].is_null();
+                }
+            }
+            _ => {}
+        }
+    }
+    /// Runtime is authoritative. Waiting for user input retains the lease.
+    pub fn sync_running(&self, running: HashSet<String>) {
+        let mut s = self.state.lock().unwrap();
+        s.blocked.retain(|id| running.contains(id));
+        s.running = running;
+        let entries = &s.entries;
+        let active = &s.running;
+        let keep: VecDeque<_> = s
+            .queue
+            .iter()
+            .filter(|key| entries.get(*key).and_then(|e| e.session.as_ref()).is_some_and(|id| active.contains(id)))
+            .cloned()
+            .collect();
+        s.queue = keep;
+        let finished = s
+            .owner
+            .as_ref()
+            .and_then(|k| s.entries.get(k))
+            .and_then(|e| e.session.as_ref())
+            .is_some_and(|id| !s.running.contains(id));
+        if finished {
+            if s.in_flight == 0 { release(&mut s) } else { s.release_pending = true }
+        }
+        drop(s);
+        self.changed.notify_waiters();
+    }
+    pub fn stop_session(&self, session: &str) {
+        let mut s = self.state.lock().unwrap();
+        if s.running.contains(session) {
+            s.blocked.insert(session.into());
+        }
+        let keys: Vec<_> =
+            s.entries.iter().filter(|(_, e)| e.session.as_deref() == Some(session)).map(|(k, _)| k.clone()).collect();
+        for key in keys {
+            s.queue.retain(|k| k != &key);
+        }
+        // An already dispatched native operation must drain before a new owner can enter.
+        if s.owner.as_ref().and_then(|k| s.entries.get(k)).and_then(|e| e.session.as_deref()) == Some(session) {
+            if s.in_flight == 0 { release(&mut s) } else { s.release_pending = true }
+        }
+        drop(s);
+        self.changed.notify_waiters();
+    }
+    pub fn stop_all(&self) {
+        let sessions: Vec<_> = self.state.lock().unwrap().entries.values().filter_map(|e| e.session.clone()).collect();
+        for id in sessions {
+            self.stop_session(&id)
+        }
+        let mut s = self.state.lock().unwrap();
+        for e in s.entries.values() {
+            e.cancel.send_replace(true);
+        }
+        *s = State::default();
+        drop(s);
+        self.changed.notify_waiters();
+    }
+    pub fn faulted(&self) -> bool {
+        self.state.lock().unwrap().faulted
+    }
+    pub fn activity(&self, session: &str) -> Activity {
+        let s = self.state.lock().unwrap();
+        let owner = s.owner.as_ref().and_then(|k| s.entries.get(k)).and_then(|e| e.session.clone());
+        let position = s
+            .queue
+            .iter()
+            .position(|k| s.entries.get(k).and_then(|e| e.session.as_deref()) == Some(session))
+            .map_or(0, |p| p + 1);
+        let active = owner.as_deref() == Some(session);
+        Activity {
+            session_id: session.into(),
+            phase: if active {
+                "active"
+            } else if position > 0 {
+                "queued"
+            } else {
+                "idle"
+            }
+            .into(),
+            queue_position: position,
+            owner_session_id: owner,
+            action: active.then(|| s.action.clone()).flatten(),
+            target: active.then(|| s.target.clone()).flatten(),
+            revision: s.revision,
+        }
+    }
+    async fn preview_command(&self, session: &str, revision: u64, focus: bool) -> Result<Value, String> {
+        let (reply, response) = tokio::sync::oneshot::channel();
+        {
+            let s = self.state.lock().unwrap();
+            let e = s.owner.as_ref().and_then(|token| s.entries.get(token)).ok_or("No active computer session")?;
+            if e.session.as_deref() != Some(session) || *e.cancel.borrow() || s.revision != revision {
+                return Err("Computer preview changed; try again".into());
+            }
+            e.preview
+                .as_ref()
+                .ok_or("Computer connection unavailable")?
+                .send(PreviewCommand { revision, focus, reply })
+                .map_err(|_| "Computer connection closed")?;
+        }
+        tokio::time::timeout(Duration::from_secs(if focus { 5 } else { 1 }), response)
+            .await
+            .map_err(|_| "Computer preview request timed out")?
+            .map_err(|_| "Computer connection closed")?
+    }
+    /// Internal reads share the MCP transport that owns the cursor session.
+    pub async fn cursor_position(&self, session: &str) -> Option<crate::preview::CursorPosition> {
+        let revision = self.activity(session).revision;
+        let response = self.preview_command(session, revision, false).await.ok()?;
+        let data = &response["structuredContent"];
+        if data["enabled"] != true {
+            return None;
+        }
+        let x = data["position"]["x"].as_f64()?;
+        let y = data["position"]["y"].as_f64()?;
+        (x.is_finite() && y.is_finite()).then_some(crate::preview::CursorPosition { x, y })
+    }
+    pub async fn focus_preview(&self, session: &str, revision: u64) -> Result<(), String> {
+        let response = self.preview_command(session, revision, true).await?;
+        if response["isError"] == true || response["structuredContent"]["activated"] != true {
+            return Err("The controlled window could not be focused".into());
+        }
+        Ok(())
+    }
+
+    async fn acquire(&self, token: &str, args: &Value, tool: &str) -> Result<(), String> {
+        loop {
+            let notified = self.changed.notified();
+            {
+                let mut s = self.state.lock().unwrap();
+                if s.faulted {
+                    return Err("Computer driver transport failed; restarting is required".into());
+                }
+                let e = s.entries.get(token).ok_or("Computer connection closed")?;
+                if *e.cancel.borrow() {
+                    return Err("Computer operation stopped".into());
+                }
+                if !e.initialized || !e.listed || !e.tools.contains(tool) {
+                    return Err("Computer tool is not ready or not registered".into());
+                }
+                if e.session.is_none() {
+                    return Err("Computer connection is not bound to a conversation".into());
+                }
+
+                if let Some(id) = e.session.clone() {
+                    if s.blocked.contains(&id) || !s.running.contains(&id) {
+                        return Err("Computer turn is not running".into());
+                    }
+                    if s.owner.as_deref() == Some(token)
+                        || (s.owner.is_none() && s.queue.front().is_none_or(|k| k == token))
+                    {
+                        s.queue.retain(|k| k != token);
+                        s.owner = Some(token.into());
+                        s.in_flight += 1;
+                        s.action = Some(tool.into());
+                        let next_target = target(args);
+                        let changed_app = args
+                            .get("pid")
+                            .and_then(Value::as_u64)
+                            .is_some_and(|pid| s.target.as_ref().is_some_and(|t| u64::from(t.pid) != pid));
+                        let clears_target = matches!(tool, "launch_app" | "get_desktop_state") || changed_app;
+                        if (next_target.is_some() || clears_target) && s.target != next_target {
+                            s.target = next_target;
+                            s.revision += 1;
+                        }
+                        return Ok(());
+                    }
+                    if !s.queue.iter().any(|k| k == token) {
+                        s.queue.push_back(token.into());
+                    }
+                }
+            }
+            notified.await;
+        }
+    }
+    fn complete(&self, token: &str, response: &Value) {
+        let mut s = self.state.lock().unwrap();
+        if s.owner.as_deref() != Some(token) {
+            return;
+        }
+        if let Some(t) = target(&response["result"]["structuredContent"])
+            && s.target.as_ref() != Some(&t)
+        {
+            s.target = Some(t);
+            s.revision += 1;
+        }
+        s.in_flight = s.in_flight.saturating_sub(1);
+        let cancelled = s.entries.get(token).is_none_or(|e| *e.cancel.borrow());
+        if s.in_flight == 0 && (s.release_pending || cancelled) {
+            release(&mut s)
+        }
+        drop(s);
+        self.changed.notify_waiters();
+    }
+    fn disconnect(&self, token: &str) {
+        let mut s = self.state.lock().unwrap();
+        s.queue.retain(|k| k != token);
+        // EOF while a call is outstanding is not proof that the native action stopped.
+        if s.owner.as_deref() == Some(token) && s.in_flight == 0 {
+            release(&mut s)
+        }
+        if s.owner.as_deref() != Some(token) {
+            s.entries.remove(token);
+        }
+        drop(s);
+        self.changed.notify_waiters();
+    }
+    async fn serve(self: Arc<Self>, stream: TcpStream) -> Result<(), String> {
+        let (reader, mut writer) = stream.into_split();
+        let mut reader = BufReader::new(reader);
+        let token = tokio::time::timeout(Duration::from_secs(5), read_line(&mut reader, 128))
+            .await
+            .map_err(|_| "Gateway authentication timed out")??;
+        let (driver, mut cancel) = {
+            let mut s = self.state.lock().unwrap();
+            let e = s.entries.get_mut(token.trim()).ok_or("Unknown computer connection")?;
+            if e.connected || *e.cancel.borrow() {
+                return Err("Computer connection cannot reconnect".into());
+            }
+            e.connected = true;
+            (clone_connection(&e.driver), e.cancel.subscribe())
+        };
+        let token = token.trim().to_owned();
+        let result = self.clone().relay(&token, driver, &mut cancel, &mut reader, &mut writer).await;
+        {
+            let mut state = self.state.lock().unwrap();
+            if state.owner.as_deref() == Some(&token) && state.in_flight > 0 {
+                state.faulted = true;
+            }
+        }
+        self.disconnect(&token);
+        result
+    }
+    async fn relay(
+        self: Arc<Self>, token: &str, driver: Connection, cancel: &mut watch::Receiver<bool>,
+        reader: &mut BufReader<tokio::net::tcp::OwnedReadHalf>, writer: &mut tokio::net::tcp::OwnedWriteHalf,
+    ) -> Result<(), String> {
+        use std::process::Stdio;
+        let mut command = Command::new(&driver.command);
+        command.env_clear();
+        for (key, value) in std::env::vars_os() {
+            if crate::inherited_environment(&key.to_string_lossy()) {
+                command.env(key, value);
+            }
+        }
+        command
+            .args(&driver.args)
+            .envs(driver.env.iter().map(|e| (&e.name, &e.value)))
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .kill_on_drop(true);
+        let mut child = command.spawn().map_err(|e| e.to_string())?;
+        let mut input = child.stdin.take().ok_or("Missing MCP stdin")?;
+        let mut output = BufReader::new(child.stdout.take().ok_or("Missing MCP stdout")?);
+        let (tx, mut rx) = tokio::sync::mpsc::channel::<String>(16);
+        // Read ahead while a request waits in the queue, so EOF cancels it immediately.
+        let incoming = async {
+            loop {
+                match read_line(reader, 1024 * 1024).await {
+                    Ok(line) => {
+                        if tx.send(line).await.is_err() {
+                            break;
+                        }
+                    }
+                    Err(_) => {
+                        let session = self.state.lock().unwrap().entries.get(token).and_then(|e| e.session.clone());
+                        if let Some(session) = session {
+                            self.stop_session(&session);
+                        }
+                        break;
+                    }
+                }
+            }
+            drop(tx);
+        };
+        let (preview_tx, mut preview_rx) = tokio::sync::mpsc::unbounded_channel::<PreviewCommand>();
+        self.state.lock().unwrap().entries.get_mut(token).ok_or("Computer connection closed")?.preview =
+            Some(preview_tx);
+        let forwarding = async {
+            loop {
+                let line = tokio::select! {
+                    line = rx.recv() => match line { Some(line) => line, None => break },
+                    Some(command) = preview_rx.recv() => {
+                        if command.reply.is_closed() { continue; }
+                        let args = {
+                            let mut s = self.state.lock().unwrap();
+                            if s.owner.as_deref() != Some(token) || s.revision != command.revision || s.release_pending {
+                                let _ = command.reply.send(Err("Computer preview changed; try again".into()));
+                                continue;
+                            }
+                            let mut args = json!({"session":format!("U {}", &token[..8])});
+                            if command.focus {
+                                let Some(target) = s.target.as_ref() else {
+                                    let _ = command.reply.send(Err("No controlled window".into()));
+                                    continue;
+                                };
+                                args["pid"] = json!(target.pid);
+                                args["window_id"] = json!(target.window_id);
+                            }
+                            s.in_flight += 1;
+                            args
+                        };
+                        let id = format!("preview-{}", Uuid::new_v4());
+                        let name = if command.focus { "bring_to_front" } else { "get_agent_cursor_state" };
+                        let request = json!({"jsonrpc":"2.0","id":id,"method":"tools/call","params":{"name":name,"arguments":args}});
+                        write_line(&mut input, &request.to_string()).await?;
+                        loop {
+                            let line = read_line(&mut output, 16 * 1024 * 1024).await?;
+                            let response: Value = serde_json::from_str(&line).map_err(|e| e.to_string())?;
+                            if response["id"] == id {
+                                self.complete(token, &json!({}));
+                                let result = response.get("result").cloned().ok_or_else(|| "Computer preview request failed".to_owned());
+                                let _ = command.reply.send(result);
+                                break;
+                            }
+                            write_line(writer, &line).await?;
+                        }
+                        continue;
+                    }
+                };
+                let mut request: Value = serde_json::from_str(&line).map_err(|e| e.to_string())?;
+                let call = request["method"] == "tools/call";
+                if call {
+                    let name = request["params"]["name"].as_str().ok_or("Missing tool name")?.to_owned();
+                    if let Err(error) = self.acquire(token, &request["params"]["arguments"], &name).await {
+                        let reply = json!({"jsonrpc":"2.0","id":request["id"],"result":{"isError":true,"content":[{"type":"text","text":error}]}});
+                        write_line(writer, &reply.to_string()).await?;
+                        continue;
+                    }
+                }
+                if call {
+                    let s = self.state.lock().unwrap();
+                    if s.entries
+                        .get(token)
+                        .is_some_and(|e| e.labeled_tools.contains(request["params"]["name"].as_str().unwrap_or("")))
+                    {
+                        let arguments = &mut request["params"]["arguments"];
+                        if arguments.is_null() {
+                            *arguments = json!({});
+                        }
+                        arguments
+                            .as_object_mut()
+                            .ok_or("Tool arguments must be an object")?
+                            .insert("session".into(), json!(format!("U {}", &token[..8])));
+                    }
+                }
+                write_line(&mut input, &request.to_string()).await?;
+                if request.get("id").is_none() {
+                    continue;
+                }
+                loop {
+                    let response = read_line(&mut output, 16 * 1024 * 1024).await?;
+                    let value: Value = serde_json::from_str(&response).map_err(|e| e.to_string())?;
+                    let matched = value.get("id") == request.get("id");
+                    if matched {
+                        self.observe_discovery(token, &request, &value);
+                    }
+                    if call && matched {
+                        self.complete(token, &value)
+                    }
+                    write_line(writer, &response).await?;
+                    if matched {
+                        break;
+                    }
+                }
+            }
+            Ok::<(), String>(())
+        };
+        // EOF stops queued work but lets an outstanding native action return before handoff.
+        let drain = async {
+            tokio::pin!(incoming, forwarding);
+            tokio::select! {
+                result = &mut forwarding => result,
+                _ = &mut incoming => tokio::time::timeout(Duration::from_secs(120), &mut forwarding).await.map_err(|_| "Native operation did not drain")?,
+            }
+        };
+        tokio::select! {result=drain=>result,_=cancel.changed()=>Err("Computer connection stopped".into())}
+    }
+}
+fn clone_connection(c: &Connection) -> Connection {
+    Connection {
+        generation: c.generation.clone(),
+        command: c.command.clone(),
+        args: c.args.clone(),
+        env: c.env.iter().map(|e| crate::Environment { name: e.name.clone(), value: e.value.clone() }).collect(),
+    }
+}
+fn release(s: &mut State) {
+    s.owner = None;
+    s.target = None;
+    s.action = None;
+    s.revision += 1;
+    s.release_pending = false;
+}
+fn target(v: &Value) -> Option<Target> {
+    Some(Target {
+        pid: u32::try_from(v.get("pid")?.as_u64()?).ok()?,
+        window_id: u32::try_from(v.get("window_id")?.as_u64()?).ok()?,
+    })
+}
+async fn read_line<R: tokio::io::AsyncBufRead + Unpin>(r: &mut R, limit: u64) -> Result<String, String> {
+    let mut line = String::new();
+    r.take(limit + 1).read_line(&mut line).await.map_err(|e| e.to_string())?;
+    if line.len() as u64 > limit || !line.ends_with('\n') {
+        return Err("Invalid MCP framing or closed connection".into());
+    }
+    Ok(line)
+}
+async fn write_line<W: tokio::io::AsyncWrite + Unpin>(w: &mut W, line: &str) -> Result<(), String> {
+    w.write_all(line.trim_end_matches('\n').as_bytes()).await.map_err(|e| e.to_string())?;
+    w.write_all(b"\n").await.map_err(|e| e.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn gateway() -> Gateway {
+        let g = Gateway::default();
+        *g.address.lock().unwrap() = Some("127.0.0.1:1".into());
+        g
+    }
+    #[tokio::test]
+    async fn preview_commands_use_the_owner_transport_and_reject_stale_or_other_sessions() {
+        let g = gateway();
+        let token = connection(&g, "a");
+        g.sync_running(["a".into()].into());
+        g.acquire(&token, &json!({"pid":1,"window_id":2}), "click").await.unwrap();
+        g.complete(&token, &json!({}));
+        let revision = g.activity("a").revision;
+        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
+        g.state.lock().unwrap().entries.get_mut(&token).unwrap().preview = Some(tx);
+        assert!(g.focus_preview("b", revision).await.is_err());
+        assert!(g.focus_preview("a", revision + 1).await.is_err());
+        assert!(rx.try_recv().is_err());
+        let (cursor, ()) = tokio::join!(g.cursor_position("a"), async {
+            let command = rx.recv().await.unwrap();
+            assert!(!command.focus);
+            command.reply.send(Ok(json!({"structuredContent":{"enabled":true,"position":{"x":40,"y":50}}}))).unwrap();
+        });
+        assert_eq!(cursor.unwrap().x, 40.0);
+        let (focused, ()) = tokio::join!(g.focus_preview("a", revision), async {
+            let command = rx.recv().await.unwrap();
+            assert!(command.focus);
+            command.reply.send(Ok(json!({"structuredContent":{"activated":true}}))).unwrap();
+        });
+        focused.unwrap();
+    }
+    #[tokio::test]
+    async fn readiness_and_replacement_are_session_scoped() {
+        let g = gateway();
+        *g.address.lock().unwrap() = Some("127.0.0.1:1".into());
+        let a = connection(&g, "a");
+        let b = connection(&g, "b");
+        assert!(g.ensure_ready("a").await.is_ok());
+        g.observe_discovery(&a, &json!({"method":"tools/list"}), &json!({"result":{"tools":[]}}));
+        assert!(g.ensure_ready("a").await.unwrap_err().contains("missing required"));
+        assert!(g.ensure_ready("b").await.is_ok());
+        let replacement = connection(&g, "a");
+        assert!(!g.state.lock().unwrap().entries.contains_key(&a));
+        assert!(g.state.lock().unwrap().entries.contains_key(&b));
+        assert!(g.state.lock().unwrap().entries.contains_key(&replacement));
+        assert!(g.ensure_ready("a").await.is_ok());
+    }
+
+    fn connection(g: &Gateway, id: &str) -> String {
+        let (token, _) = g
+            .register(Connection { generation: "g".into(), command: "unused".into(), args: vec![], env: vec![] })
+            .unwrap();
+        g.bind(&token, id).unwrap();
+        g.observe_discovery(
+            &token,
+            &json!({"method":"initialize"}),
+            &json!({"result":{"protocolVersion":"2024-11-05"}}),
+        );
+        g.observe_discovery(&token, &json!({"method":"tools/list"}), &json!({"result":{"tools":[{"name":"click"},{"name":"list_windows"},{"name":"get_window_state"},{"name":"run_steps"},{"name":"get_app_state"}]}}));
+        token
+    }
+    #[tokio::test]
+    async fn fifo_ownership_survives_tool_completion_until_runtime_finishes_turn() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        let b = connection(&g, "b");
+        g.sync_running(["a".into(), "b".into()].into());
+        g.acquire(&a, &json!({"pid":1,"window_id":2}), "click").await.unwrap();
+        g.complete(&a, &json!({}));
+        assert!(tokio::time::timeout(Duration::from_millis(10), g.acquire(&b, &json!({}), "click")).await.is_err());
+        assert_eq!(g.activity("b").queue_position, 1);
+        assert!(g.activity("b").target.is_none());
+        g.sync_running(["b".into()].into());
+        g.acquire(&b, &json!({"pid":3,"window_id":4}), "click").await.unwrap();
+        assert_eq!(g.activity("b").target, Some(Target { pid: 3, window_id: 4 }));
+    }
+    #[tokio::test]
+    async fn cancelled_owner_drains_before_handoff_and_is_blocked_for_the_turn() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        let b = connection(&g, "b");
+        g.sync_running(["a".into(), "b".into()].into());
+        g.acquire(&a, &json!({}), "run_steps").await.unwrap();
+        g.stop_session("a");
+        assert!(tokio::time::timeout(Duration::from_millis(10), g.acquire(&b, &json!({}), "click")).await.is_err());
+        assert!(g.acquire(&a, &json!({}), "click").await.is_err());
+        g.complete(&a, &json!({}));
+        g.acquire(&b, &json!({}), "click").await.unwrap();
+    }
+    #[tokio::test]
+    async fn cancelling_queued_conversation_never_stops_owner() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        let b = connection(&g, "b");
+        g.sync_running(["a".into(), "b".into()].into());
+        g.acquire(&a, &json!({}), "click").await.unwrap();
+        let _ = tokio::time::timeout(Duration::from_millis(10), g.acquire(&b, &json!({}), "click")).await;
+        g.stop_session("b");
+        assert_eq!(g.activity("a").phase, "active");
+        assert_eq!(g.activity("b").queue_position, 0);
+    }
+    #[tokio::test]
+    async fn closing_an_idle_session_does_not_block_its_next_turn() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        g.stop_session("a");
+        g.sync_running(["a".into()].into());
+        g.acquire(&a, &json!({}), "click").await.unwrap();
+    }
+    #[tokio::test]
+    async fn switching_apps_clears_the_previous_window_preview() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        g.sync_running(["a".into()].into());
+        g.acquire(&a, &json!({"pid":1,"window_id":2}), "get_window_state").await.unwrap();
+        g.complete(&a, &json!({}));
+        let revision = g.activity("a").revision;
+        g.acquire(&a, &json!({"pid":3}), "get_app_state").await.unwrap();
+        assert!(g.activity("a").target.is_none());
+        assert!(g.activity("a").revision > revision);
+    }
+    #[test]
+    fn binding_is_immutable_and_global_shutdown_invalidates_tokens() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        assert!(g.bind(&a, "b").is_err());
+        g.stop_all();
+        assert!(g.bind(&a, "a").is_err());
+    }
+    #[tokio::test]
+    async fn runtime_completion_does_not_release_an_in_flight_action() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        g.sync_running(["a".into()].into());
+        g.acquire(&a, &json!({}), "click").await.unwrap();
+        g.sync_running(HashSet::new());
+        assert_eq!(g.activity("a").phase, "active");
+        g.complete(&a, &json!({}));
+        assert_eq!(g.activity("a").phase, "idle");
+    }
+    #[tokio::test]
+    async fn stale_target_revisions_change_on_handoff() {
+        let g = gateway();
+        let a = connection(&g, "a");
+        g.sync_running(["a".into()].into());
+        g.acquire(&a, &json!({"pid":1,"window_id":2}), "click").await.unwrap();
+        let old = g.activity("a").revision;
+        g.complete(&a, &json!({}));
+        g.sync_running(HashSet::new());
+        assert_ne!(old, g.activity("a").revision);
+    }
+}