omp-mobile 0.2.0 → 0.4.0

package/NOTICE

@@ -4,3 +4,7 @@ Copyright (c) 2026 Rinai
 Licensed under the Apache License, Version 2.0. See the LICENSE file.
 
 OMP Mobile is not affiliated with oh-my-pi or Tailscale.
+
+The app bundles the Geist typeface (Copyright 2023 Vercel, in collaboration with basement.studio) and the
+JetBrains Mono typeface (Copyright 2020 The JetBrains Mono Project Authors), both under the SIL Open Font
+License 1.1; see app/assets/fonts.

package/README.md

@@ -13,13 +13,15 @@
 
 OMP Mobile is a native phone app for [oh-my-pi](https://github.com/can1357/oh-my-pi) (OMP), with a small daemon on each computer. Start, follow and steer OMP sessions from the phone: transcript, tool calls, approvals, and the sessions you started in a terminal.
 
-- **Native app:** The app draws the transcript, tool cards, thinking, Markdown and composer itself. No WebView, no web page.
+- **Native app:** The app draws the transcript, tool cards, thinking, Markdown and composer itself, in OMP's own look (Geist, JetBrains Mono, the π mark). No WebView, no web page.
+- **A transcript you can follow:** each stretch of tool calls folds into one card that shows the step running now and sums itself up when done ("Edited 2 files, ran 3"); tap a step for its command, diff and output. The view stays on the newest message while you are at the bottom and stays put while you read back.
 - **The whole transcript:** images the user sent and images tools produce (screenshots, opened files), edit diffs with their intent, tool results, Markdown tables, OMP's todo list, context usage and queued messages.
 - **Model switching:** tap the model in the composer to pick from OMP's catalog — grouped by provider and searchable — and set its thinking level. The model chip follows the session when it changes.
+- **Photos to the agent:** attach photos from the library or the camera; they are downscaled on the phone and sent with your message.
 - **Approvals on the phone:** OMP's own tool approvals and questions arrive as a sheet, and the turn waits for your answer.
 - **Terminal sessions:** Sessions you started in a terminal on the computer are listed too and continue on the phone. One still open in a terminal waits until that terminal exits.
 - **Notifications:** Android notifications for approvals, questions, and finished turns while the app is in the background.
-- **All your machines:** Pair each computer by QR code, switch between them from the session list. A reopened chat shows at once, also offline.
+- **All your machines:** Pair each computer by QR code and give it a name on the phone. Tap a chat's title for every session on every computer — searchable, with what needs you first. The app opens on the computer you used last; a reopened chat shows at once, also offline.
 - **Tailscale only:** The daemon listens on the computer's Tailscale address and admits only your own devices. No relay or cloud service of its own.
 - **An OMP plugin:** `/mobile` in OMP starts the daemon in the background and shows the pairing code. The daemon keeps running after the terminal closes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-mobile",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The computer side of OMP Mobile: runs oh-my-pi sessions and serves them to the phone app over Tailscale.",
   "keywords": [
     "mobile",

package/src/omp-extension.mjs

@@ -9,13 +9,19 @@
  *
  * It runs on the Bun that ships inside omp (`BUN_BE_BUN=1`), so no separate
  * Node.js is needed, and binds this computer's Tailscale IPv4 (`--host tailscale`).
+ *
+ * In every omp it is loaded into, it also watches for the daemon's takeover
+ * request for the session that omp has open (a file beside the session file,
+ * see `takeover.mjs`): it then says where the session went, stops the turn and
+ * closes omp through OMP's own shutdown, so the phone can continue it.
  */
 import { spawn } from "node:child_process";
-import { accessSync, closeSync, constants, mkdirSync, openSync, readFileSync } from "node:fs";
+import { accessSync, closeSync, constants, mkdirSync, openSync, readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderQr } from "./qr.mjs";
+import { requestPath } from "./takeover.mjs";
 
 const HOME = join(homedir(), ".omp-mobile");
 const STATE_FILE = join(HOME, "daemon.json");
@@ -26,6 +32,11 @@ const START_TIMEOUT_MS = 20_000;
 const POLL_MS = 1_500;
 /** How long the code stays up without a phone connecting. */
 const SHOW_MS = 5 * 60_000;
+/** How often the session's takeover request is looked for, and how stale one may be. */
+const TAKEOVER_POLL_MS = 1_000;
+const TAKEOVER_MAX_AGE_MS = 60_000;
+/** How long a running turn gets to stop before omp closes anyway. */
+const TAKEOVER_IDLE_WAIT_MS = 5_000;
 const SUBCOMMANDS = [
   { value: "status", label: "status", description: "Is the daemon running, and where" },
   { value: "stop", label: "stop", description: "Stop the background daemon" },
@@ -138,9 +149,12 @@ async function startDaemon(cwd) {
   throw new Error(`The omp-mobile daemon did not start (${reason}).\n${logTail()}`);
 }
 
+/** Time the daemon gets to close its omp processes (each up to SIGINT + SIGTERM waits) before it is killed. */
+const STOP_TIMEOUT_MS = 25_000;
+
 async function stopDaemon(state) {
   process.kill(state.pid, "SIGTERM");
-  const deadline = Date.now() + 5_000;
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
   while (Date.now() < deadline && alive(state.pid)) await new Promise((resolveWait) => setTimeout(resolveWait, 100));
   if (alive(state.pid)) process.kill(state.pid, "SIGKILL");
 }
@@ -180,7 +194,51 @@ export function pairingWidget({ title, code, notes }) {
   });
 }
 
+/**
+ * The daemon's takeover request for this process and session, if there is a
+ * fresh one. A request for another process or an old one is left alone.
+ * @returns {{device: string} | undefined}
+ */
+export function takeoverRequest(sessionFile, sessionId, pid = process.pid, now = Date.now()) {
+  if (typeof sessionFile !== "string" || sessionFile === "") return undefined;
+  let request;
+  try {
+    request = JSON.parse(readFileSync(requestPath(sessionFile), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (request?.pid !== pid || request.sessionId !== sessionId) return undefined;
+  if (typeof request.at !== "number" || now - request.at > TAKEOVER_MAX_AGE_MS) return undefined;
+  return { device: typeof request.device === "string" && request.device !== "" ? request.device : "OMP Mobile" };
+}
+
 export default function ompMobile(pi) {
+  /** The takeover watch for the session this omp has open. */
+  let watching;
+  let leaving = false;
+
+  pi.on("session_start", (_event, ctx) => {
+    if (watching !== undefined) ctx.clearTimer(watching);
+    watching = ctx.setInterval(async () => {
+      if (leaving) return;
+      const file = ctx.sessionManager.getSessionFile();
+      const request = takeoverRequest(file, ctx.sessionManager.getSessionId());
+      if (request === undefined) return;
+      leaving = true;
+      // Taking the request is the answer the daemon waits for before it would signal.
+      rmSync(requestPath(file), { force: true });
+      // OMP closes once the session is idle; the daemon signals it if that does not come soon,
+      // and tells the terminal where the session went once omp is gone.
+      ctx.ui.notify(`OMP Mobile: this session continues on ${request.device}. Closing omp here…`, "warning");
+      if (!ctx.isIdle()) {
+        ctx.abort();
+        const deadline = Date.now() + TAKEOVER_IDLE_WAIT_MS;
+        while (!ctx.isIdle() && Date.now() < deadline) await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+      }
+      ctx.shutdown();
+    }, TAKEOVER_POLL_MS);
+  });
+
   /** The pairing code on screen: its watcher and when it appeared. */
   let showing;
 

package/src/omp-sessions.mjs

@@ -42,7 +42,7 @@ export function promptTitle(content) {
  * A title as one line of at most 80 characters. OMP's title cards start with
  * a Nerd Font icon (private-use code points) a phone font has no glyph for.
  */
-function oneLine(text) {
+export function oneLine(text) {
   return text
     .replace(/[\uE000-\uF8FF\u{F0000}-\u{10FFFF}]/gu, "")
     .trim()

package/src/rpc-frame.mjs

@@ -0,0 +1,135 @@
+/**
+ * OMP's RPC framing, the parts the daemon needs to read protocol v2.
+ *
+ * Protocol v1 caps every JSON line at 1 MiB; a response above that arrives as
+ * `{success: false, error: "RPC response exceeded the transport limit"}`. After
+ * `negotiate_protocol` v2, OMP splits a larger frame into `rpc_chunk` lines
+ * (base64 slices of the frame's UTF-8 bytes) that reassemble up to 64 MiB.
+ * The limits and checks mirror OMP's `rpc-frame.ts` so a frame OMP accepts
+ * is one this decoder accepts.
+ */
+
+/** Maximum UTF-8 size of one newline-delimited RPC frame, including the newline. */
+export const MAX_RPC_FRAME_BYTES = 1024 * 1024;
+/** Maximum UTF-8 size of one logical frame reassembled by protocol v2. */
+export const MAX_RPC_REASSEMBLED_BYTES = 64 * 1024 * 1024;
+/** Bytes of the original frame carried by one chunk. */
+export const RPC_CHUNK_PAYLOAD_BYTES = 256 * 1024;
+
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/**
+ * Whether OMP's `ready` frame offers protocol v2 with the limits this decoder implements.
+ * @param {unknown} ready
+ */
+export function supportsProtocolV2(ready) {
+  if (ready === null || typeof ready !== "object") return false;
+  const value = /** @type {Record<string, unknown>} */ (ready);
+  return (
+    value.type === "ready" &&
+    Array.isArray(value.supportedProtocolVersions) &&
+    value.supportedProtocolVersions.includes(2) &&
+    value.maxFrameBytes === MAX_RPC_FRAME_BYTES &&
+    value.maxReassembledFrameBytes === MAX_RPC_REASSEMBLED_BYTES
+  );
+}
+
+/** @param {unknown} data */
+function decodeBase64(data) {
+  if (typeof data !== "string" || data.length === 0 || !BASE64.test(data)) throw new Error("invalid rpc chunk data");
+  const bytes = Buffer.from(data, "base64");
+  if (bytes.toString("base64") !== data) throw new Error("invalid rpc chunk data");
+  return bytes;
+}
+
+/**
+ * Reassembles `rpc_chunk` sequences. Feed it every parsed line in order: a
+ * plain frame comes straight back, a chunk returns undefined until its
+ * sequence completes, then the reassembled frame. Any violation throws, and
+ * the decoder is left empty for the next frame.
+ */
+export class RpcFrameDecoder {
+  /** @type {{chunkId: string, count: number, byteLength: number, nextIndex: number, chunks: Buffer[], receivedBytes: number} | undefined} */
+  #pending = undefined;
+
+  /**
+   * @param {unknown} value
+   * @returns {object | undefined}
+   */
+  push(value) {
+    try {
+      return this.#push(value);
+    } catch (error) {
+      this.#pending = undefined;
+      throw error;
+    }
+  }
+
+  /** @param {unknown} value */
+  #push(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("rpc frame must be an object");
+    const frame = /** @type {Record<string, unknown>} */ (value);
+    if (frame.type !== "rpc_chunk") {
+      if (this.#pending !== undefined) throw new Error("rpc chunk sequence interrupted");
+      return frame;
+    }
+    const { chunkId, index, count, byteLength } = frame;
+    if (
+      typeof chunkId !== "string" ||
+      chunkId.length === 0 ||
+      chunkId.length > 128 ||
+      !Number.isSafeInteger(index) ||
+      !Number.isSafeInteger(count) ||
+      !Number.isSafeInteger(byteLength) ||
+      /** @type {number} */ (index) < 0 ||
+      /** @type {number} */ (count) < 2 ||
+      /** @type {number} */ (count) > Math.ceil(MAX_RPC_REASSEMBLED_BYTES / RPC_CHUNK_PAYLOAD_BYTES) ||
+      /** @type {number} */ (index) >= /** @type {number} */ (count) ||
+      /** @type {number} */ (byteLength) < MAX_RPC_FRAME_BYTES ||
+      /** @type {number} */ (byteLength) > MAX_RPC_REASSEMBLED_BYTES
+    ) {
+      throw new Error("invalid rpc chunk metadata");
+    }
+    const bytes = decodeBase64(frame.data);
+    if (bytes.byteLength > RPC_CHUNK_PAYLOAD_BYTES) throw new Error("rpc chunk payload exceeds the transport limit");
+    if (this.#pending === undefined) {
+      if (index !== 0) throw new Error("rpc chunk sequence must start at index 0");
+      this.#pending = { chunkId, count: /** @type {number} */ (count), byteLength: /** @type {number} */ (byteLength), nextIndex: 0, chunks: [], receivedBytes: 0 };
+    }
+    const pending = this.#pending;
+    if (pending.chunkId !== chunkId || pending.count !== count || pending.byteLength !== byteLength || pending.nextIndex !== index) {
+      throw new Error("rpc chunk sequence mismatch");
+    }
+    pending.chunks.push(bytes);
+    pending.receivedBytes += bytes.byteLength;
+    pending.nextIndex += 1;
+    if (pending.receivedBytes > pending.byteLength) throw new Error("rpc chunk sequence exceeds its byte length");
+    if (pending.nextIndex < pending.count) return undefined;
+    this.#pending = undefined;
+    if (pending.receivedBytes !== pending.byteLength) throw new Error("rpc chunk sequence ended short of its byte length");
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(pending.chunks, pending.receivedBytes));
+    const reassembled = JSON.parse(text);
+    if (reassembled === null || typeof reassembled !== "object" || Array.isArray(reassembled)) {
+      throw new Error("reassembled rpc frame must be an object");
+    }
+    if (reassembled.type === "rpc_chunk") throw new Error("reassembled rpc frame must not be a chunk");
+    return reassembled;
+  }
+}
+
+/**
+ * Split one frame into the `rpc_chunk` lines OMP v2 writes for it (used by tests and fakes).
+ * @param {object} frame
+ * @param {string} chunkId
+ * @returns {string[]}
+ */
+export function chunkFrame(frame, chunkId) {
+  const bytes = Buffer.from(JSON.stringify(frame), "utf8");
+  const count = Math.ceil(bytes.byteLength / RPC_CHUNK_PAYLOAD_BYTES);
+  const lines = [];
+  for (let index = 0; index < count; index += 1) {
+    const data = bytes.subarray(index * RPC_CHUNK_PAYLOAD_BYTES, (index + 1) * RPC_CHUNK_PAYLOAD_BYTES).toString("base64");
+    lines.push(JSON.stringify({ type: "rpc_chunk", chunkId, index, count, byteLength: bytes.byteLength, data }));
+  }
+  return lines;
+}

package/src/rpc-session.mjs

@@ -9,8 +9,11 @@ import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
+import { RpcFrameDecoder, supportsProtocolV2 } from "./rpc-frame.mjs";
 
 const START_TIMEOUT_MS = 45_000;
+/** How long omp gets to leave after `SIGINT`, and again after `SIGTERM`, when the daemon closes it. */
+const CLOSE_WAIT_MS = 10_000;
 
 /**
  * The environment without `BUN_BE_BUN`: /mobile starts the daemon under omp's
@@ -21,6 +24,38 @@ function withoutBunFlag(env) {
   return rest;
 }
 const REQUEST_TIMEOUT_MS = 60_000;
+/** Messages per `get_messages_page` request: OMP's maximum; a page also stays under 768 KiB. */
+const MESSAGE_PAGE_LIMIT = 256;
+/** OMP's `get_messages_page` codes that mean "page later or read it whole", as OMP's own client treats them. */
+const PAGE_FALLBACK_CODES = new Set(["session_busy", "stale_cursor"]);
+const PAGE_FALLBACK_MESSAGES = new Set([
+  "Cannot page messages while the session is changing",
+  "RPC message cursor is stale",
+]);
+
+/**
+ * A failed RPC command: OMP's error text, and its machine-readable `code` when it sent one.
+ */
+export class RpcCommandError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} command
+   * @param {string | undefined} code
+   */
+  constructor(message, command, code) {
+    super(message);
+    this.name = "RpcCommandError";
+    this.command = command;
+    this.code = code;
+  }
+}
+
+/** Whether a paging failure should fall back to one whole `get_messages`. */
+function pageFallback(error) {
+  if (!(error instanceof Error)) return false;
+  if (error instanceof RpcCommandError && error.code !== undefined && PAGE_FALLBACK_CODES.has(error.code)) return true;
+  return PAGE_FALLBACK_MESSAGES.has(error.message);
+}
 
 /** Events that carry no useful state to the phone. */
 const IGNORED_UI = new Set(["setStatus", "setWidget", "setTitle", "set_editor_text"]);
@@ -88,6 +123,9 @@ export class RpcSession extends EventEmitter {
     this.lastState = null;
     this.lastError = null;
     this.stderr = "";
+    /** 1 until OMP accepts `negotiate_protocol` v2; then frames above 1 MiB arrive as chunks. */
+    this.protocolVersion = 1;
+    this.frames = new RpcFrameDecoder();
   }
 
   /** Start the process and resolve once it printed `ready`. */
@@ -132,7 +170,14 @@ export class RpcSession extends EventEmitter {
       });
     });
     lines.on("line", (line) => this.#onLine(line));
-    await ready;
+    const hello = await ready;
+    // v1 caps every frame at 1 MiB: a long session's messages or a large tool
+    // result would come back as a transport-limit error. v2 chunks them instead.
+    if (supportsProtocolV2(hello)) {
+      const response = await this.request("negotiate_protocol", { protocolVersion: 2 });
+      if (response.data?.protocolVersion !== 2) throw new Error("omp RPC protocol v2 negotiation failed");
+      this.protocolVersion = 2;
+    }
     this.started = true;
     return this;
   }
@@ -141,11 +186,13 @@ export class RpcSession extends EventEmitter {
   #onLine(line) {
     let message;
     try {
-      message = JSON.parse(line);
+      message = this.frames.push(JSON.parse(line));
     } catch {
       this.emit("protocol-error", { line: line.slice(0, 500) });
       return;
     }
+    // A chunk of a larger frame: the frame is handled once its last chunk arrives.
+    if (message === undefined) return;
     this.updatedAt = Date.now();
     if (message.type === "ready") {
       this.emit("ready", message);
@@ -155,7 +202,9 @@ export class RpcSession extends EventEmitter {
       const pending = message.id ? this.pending.get(message.id) : undefined;
       if (pending !== undefined && message.id) {
         this.pending.delete(message.id);
-        if (message.success === false) pending.reject(new Error(message.error || `RPC ${message.command} failed`));
+        if (message.success === false) {
+          pending.reject(new RpcCommandError(message.error || `RPC ${message.command} failed`, message.command, message.code));
+        }
         else pending.resolve(message);
         return;
       }
@@ -252,12 +301,50 @@ export class RpcSession extends EventEmitter {
     return data;
   }
 
-  /** @returns {Promise<{messages: object[]}>} */
+  /**
+   * The session's messages. Under protocol v2 they are read in pages, as OMP's
+   * own RPC client does: one `get_messages` answer is a single frame, which a
+   * long uncompacted session outgrows. A page that cannot be read now (the
+   * session is changing, or the cursor went stale) falls back to the whole list
+   * in one response, which v2 may chunk.
+   * @returns {Promise<{messages: object[]}>}
+   */
   async getMessages() {
+    // As OMP's own client: pages only once v2 is negotiated (an OMP that offers v2 pages).
+    if (this.protocolVersion === 2) {
+      try {
+        return { messages: await this.#drainPages() };
+      } catch (error) {
+        if (!pageFallback(error)) throw error;
+      }
+    }
     const response = await this.request("get_messages");
     return response.data ?? { messages: [] };
   }
 
+  async #drainPages() {
+    const messages = [];
+    const seen = new Set();
+    /** @type {number | undefined} */
+    let total;
+    /** @type {string | undefined} */
+    let cursor;
+    do {
+      const response = await this.request("get_messages_page", cursor === undefined ? { limit: MESSAGE_PAGE_LIMIT } : { cursor, limit: MESSAGE_PAGE_LIMIT });
+      const page = response.data ?? {};
+      if (!Number.isSafeInteger(page.totalMessages) || page.totalMessages < 0 || (total !== undefined && page.totalMessages !== total)) {
+        throw new Error("omp message pages returned an inconsistent total");
+      }
+      total = page.totalMessages;
+      if (Array.isArray(page.messages)) messages.push(...page.messages);
+      cursor = typeof page.nextCursor === "string" && page.nextCursor !== "" ? page.nextCursor : undefined;
+      if (cursor !== undefined && seen.has(cursor)) throw new Error("omp message pages repeated a cursor");
+      if (cursor !== undefined) seen.add(cursor);
+    } while (cursor !== undefined);
+    if (messages.length !== total) throw new Error("omp message pages ended before the advertised total");
+    return messages;
+  }
+
   /**
    * The models this session can switch to, compacted for a phone list.
    * OMP waits out background discovery first, so this can take a few seconds.
@@ -293,9 +380,12 @@ export class RpcSession extends EventEmitter {
     return this.getState();
   }
 
-  /** @param {string} text */
-  async prompt(text) {
-    return this.request("prompt", { message: text });
+  /**
+   * @param {string} text
+   * @param {{type: "image", data: string, mimeType: string}[]} [images] OMP `ImageContent` parts sent with the text.
+   */
+  async prompt(text, images = []) {
+    return this.request("prompt", images.length > 0 ? { message: text, images } : { message: text });
   }
 
   async abort() {
@@ -315,16 +405,47 @@ export class RpcSession extends EventEmitter {
     this.#settle(id, answer.cancelled === true ? "cancelled" : "answered");
   }
 
-  close() {
-    if (this.closed) return;
+  /**
+   * Stop the omp child the way Ctrl+C does: `SIGINT`, then `SIGTERM`, each
+   * followed by a wait. OMP routes both through its teardown (the turn is
+   * aborted, the session file flushed, its lock released). Never `SIGKILL`: a
+   * process cut off mid-write can leave a session half saved. Resolves to how
+   * it left, or `"running"` when it ignored both signals.
+   * @param {{sigint?: number, sigterm?: number}} [waits] milliseconds after each signal
+   * @returns {Promise<"exited" | "SIGINT" | "SIGTERM" | "running">}
+   */
+  close(waits = {}) {
+    if (this.closing !== undefined) return this.closing;
     this.closed = true;
     for (const pending of this.pending.values()) pending.reject(new Error("omp session closed"));
     this.pending.clear();
-    this.child?.kill("SIGTERM");
-    setTimeout(() => {
-      if (this.child !== undefined && this.child.exitCode === null) this.child.kill("SIGKILL");
-    }, 2_000).unref();
+    const child = this.child;
+    this.closing = (async () => {
+      if (child === undefined || child.exitCode !== null || child.signalCode !== null) return "exited";
+      const exited = new Promise((resolveExit) => child.once("exit", () => resolveExit(true)));
+      for (const [signal, wait] of /** @type {const} */ ([
+        ["SIGINT", waits.sigint ?? CLOSE_WAIT_MS],
+        ["SIGTERM", waits.sigterm ?? CLOSE_WAIT_MS],
+      ])) {
+        try {
+          child.kill(signal);
+        } catch {
+          return "exited";
+        }
+        let timer;
+        const left = await Promise.race([
+          exited,
+          new Promise((resolveWait) => {
+            timer = setTimeout(() => resolveWait(false), wait);
+          }),
+        ]);
+        clearTimeout(timer);
+        if (left) return signal;
+      }
+      return "running";
+    })();
+    return this.closing;
   }
 }
 
-export { REQUEST_TIMEOUT_MS, START_TIMEOUT_MS };
+export { REQUEST_TIMEOUT_MS, START_TIMEOUT_MS, MESSAGE_PAGE_LIMIT, CLOSE_WAIT_MS };

package/src/server.mjs

@@ -18,7 +18,8 @@ import { renderQr } from "./qr.mjs";
 import { RpcSession } from "./rpc-session.mjs";
 import { Admission, Tailscale, isLoopbackHost } from "./admission.mjs";
 import { AttentionTracker, serveEvents } from "./attention.mjs";
-import { listOmpSessions, promptTitle, sessionOwners } from "./omp-sessions.mjs";
+import { listOmpSessions, oneLine, promptTitle, sessionOwners } from "./omp-sessions.mjs";
+import { askOwnerToLeave, forksOf, isOmpCommand, processInfo, sessionBusy, takeoverFarewell, tellTerminal } from "./takeover.mjs";
 
 const { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const PROTOCOL = 1;
@@ -42,14 +43,60 @@ const STATE_EVENTS = new Set([
   "todo_auto_clear",
   "goal_updated",
 ]);
+/** Image types a phone may attach to a prompt: what the camera and the photo picker produce. */
+const PROMPT_IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif"]);
+/** At most this many images per prompt, each at most this many decoded bytes. */
+const MAX_PROMPT_IMAGES = 8;
+const MAX_PROMPT_IMAGE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * The images of a `prompt` frame as OMP's `ImageContent`, checked: base64 that
+ * round-trips, a known image type, bounded count and size. Anything else is
+ * refused whole rather than sent half.
+ * @param {unknown} value
+ * @returns {{type: "image", data: string, mimeType: string}[]}
+ */
+export function promptImages(value) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new Error("images must be a list");
+  if (value.length > MAX_PROMPT_IMAGES) throw new Error(`at most ${MAX_PROMPT_IMAGES} images per message`);
+  return value.map((image, index) => {
+    const data = image?.data;
+    const mimeType = image?.mimeType;
+    if (typeof mimeType !== "string" || !PROMPT_IMAGE_TYPES.has(mimeType)) throw new Error(`image ${index + 1}: unsupported type`);
+    if (typeof data !== "string" || data === "") throw new Error(`image ${index + 1}: no data`);
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.byteLength === 0 || bytes.toString("base64") !== data) throw new Error(`image ${index + 1}: data is not base64`);
+    if (bytes.byteLength > MAX_PROMPT_IMAGE_BYTES) throw new Error(`image ${index + 1}: larger than ${MAX_PROMPT_IMAGE_BYTES / 1024 / 1024} MB`);
+    return { type: "image", data, mimeType };
+  });
+}
+
+/**
+ * What this daemon supports beyond protocol 1, for an app to offer only what
+ * the computer it talks to can do. `prompt-images`: `prompt` frames carry `images`;
+ * `takeover`: `POST /sessions/:id/takeover` continues a session another omp process holds.
+ */
+const FEATURES = ["prompt-images", "takeover"];
+/** Who a phone continues a session on, as the terminal it leaves is told. */
+const DEFAULT_DEVICE = "OMP Mobile";
+/** Close code after an `open_failed` frame: the session socket opened only to say why the session could not. */
+const OPEN_FAILED_CLOSE_CODE = 4000;
 /** OMP's content-addressed image store under `<omp home>/agent/blobs`. */
 const BLOB_NAME = /^[0-9a-f]{64}$/;
 
-/** @typedef {{id: string, title: string, cwd: string, status: string, model?: string, createdAt: number, updatedAt: number, sessionFile?: string, origin: "daemon" | "omp", openElsewhere?: boolean}} SessionSummary */
+/** @typedef {{pid: number, busy: boolean, terminal: boolean}} SessionOwner */
+/** @typedef {{id: string, title: string, cwd: string, status: string, model?: string, createdAt: number, updatedAt: number, sessionFile?: string, origin: "daemon" | "omp", openElsewhere?: boolean, owner?: SessionOwner, waiting?: number}} SessionSummary */
 
-/** An error with the HTTP status it answers. */
-function httpError(status, message) {
-  return Object.assign(new Error(message), { status });
+/** An error with the HTTP status it answers, and any detail its JSON answer carries. */
+function httpError(status, message, detail = {}) {
+  return Object.assign(new Error(message), { status, detail });
+}
+
+/** The JSON answer for a failed request: the reason and the error's detail (a 409's `owner`). */
+function errorBody(error) {
+  const detail = error !== null && typeof error === "object" && typeof error.detail === "object" ? error.detail : {};
+  return { error: error instanceof Error ? error.message : String(error), ...detail };
 }
 
 function parseArgs(argv) {
@@ -300,10 +347,10 @@ function readBody(req) {
   });
 }
 
-function titleOf(messages, state, cwd) {
-  if (typeof state?.sessionName === "string" && state.sessionName.trim() !== "") {
-    return state.sessionName.trim();
-  }
+export function titleOf(messages, state, cwd) {
+  // OMP's session names can start with a Nerd Font icon, as its stored titles do (see `oneLine`).
+  const named = typeof state?.sessionName === "string" ? oneLine(state.sessionName) : "";
+  if (named !== "") return named;
   if (Array.isArray(messages)) {
     const title = promptTitle(messages.find((message) => message?.role === "user")?.content);
     if (title !== "") return title;
@@ -364,6 +411,8 @@ class SessionEntry {
       updatedAt: this.updatedAt,
       sessionFile: this.state?.sessionFile,
       origin: "daemon",
+      // OMP questions and tool approvals still waiting for an answer: the session needs the user.
+      waiting: this.openRequests().length,
     };
   }
 
@@ -434,10 +483,11 @@ class SessionEntry {
     return this.rpc.extensionRequests instanceof Map ? [...this.rpc.extensionRequests.values()] : [];
   }
 
+  /** Disconnect the phones and stop omp gracefully (see `RpcSession.close`). */
   close() {
     this.closed = true;
-    this.rpc.close();
     for (const client of this.clients) client.close(1001, "session closed");
+    return this.rpc.close();
   }
 }
 
@@ -451,6 +501,11 @@ class Daemon {
   constructor(options, token, identity = {}) {
     this.options = options;
     this.token = token;
+    /**
+     * Where failures nothing else reports go: the daemon's output is `~/.omp-mobile/daemon.log`.
+     * @type {(error: unknown) => void}
+     */
+    this.log = options.log ?? ((error) => console.error(`${new Date().toISOString()} ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`));
     this.admission = identity.admission;
     this.user = identity.user ?? "";
     this.startedAt = Date.now();
@@ -468,6 +523,8 @@ class Daemon {
     this.ompSessions = new Map();
     /** Resumes in flight, so two opens of one session start one process. @type {Map<string, Promise<SessionEntry>>} */
     this.starting = new Map();
+    /** Takeovers in flight, so two phones asking at once ask the owner once. @type {Map<string, Promise<object>>} */
+    this.takingOver = new Map();
     this.server = createServer((req, res) => void this.admitHttp(req, res));
     this.wsServer = new WebSocketServer({ noServer: true });
     this.server.on("upgrade", (req, socket, head) => void this.admitUpgrade(req, socket, head));
@@ -530,6 +587,7 @@ class Daemon {
         sessionCount: this.sessions.size,
         cwd: this.options.cwd,
         user: this.user || null,
+        features: FEATURES,
       });
       return;
     }
@@ -580,6 +638,13 @@ class Daemon {
         sendJson(res, 201, { session: entry.summary() });
         return;
       }
+      const takeover = /^\/sessions\/([^/]+)\/takeover$/.exec(url.pathname);
+      if (takeover !== null && req.method === "POST") {
+        const body = await readBody(req);
+        const device = typeof body.device === "string" && body.device.trim() !== "" ? body.device.trim().slice(0, 60) : DEFAULT_DEVICE;
+        sendJson(res, 200, await this.takeOver(decodeURIComponent(takeover[1]), device));
+        return;
+      }
       const match = /^\/sessions\/([^/]+)$/.exec(url.pathname);
       if (match !== null) {
         const id = decodeURIComponent(match[1]);
@@ -601,9 +666,10 @@ class Daemon {
       }
       sendJson(res, 404, { error: "not found" });
     } catch (error) {
-      sendJson(res, typeof error?.status === "number" ? error.status : 500, {
-        error: error instanceof Error ? error.message : String(error),
-      });
+      const status = typeof error?.status === "number" ? error.status : 500;
+      // A refusal the API defines (404, 409, 410) is an answer; anything else is a failure worth keeping.
+      if (status >= 500) this.log(error);
+      sendJson(res, status, errorBody(error));
     }
   }
 
@@ -627,12 +693,26 @@ class Daemon {
     const others = found
       .filter((session) => !known.has(session.id))
       .map((session) => ({ ...session, status: "idle", origin: "omp" }));
-    const marked = [...dormant, ...others].map((session) =>
-      owners?.has(session.id) === true ? { ...session, openElsewhere: true } : session,
+    const marked = await Promise.all(
+      [...dormant, ...others].map(async (session) => {
+        const pid = owners?.get(session.id);
+        if (pid === undefined) return session;
+        return { ...session, openElsewhere: true, owner: await this.ownerOf(pid, session.sessionFile) };
+      }),
     );
     return [...live, ...marked];
   }
 
+  /**
+   * What the phone is told about the process holding a session: whether it is
+   * mid-turn (by the session file's last message) and runs in a terminal.
+   * @returns {Promise<SessionSummary["owner"]>}
+   */
+  async ownerOf(pid, sessionFile) {
+    const info = await processInfo(pid);
+    return { pid, busy: typeof sessionFile === "string" && sessionBusy(sessionFile), terminal: info?.tty !== undefined };
+  }
+
   /** Which sessions some omp process holds open (`undefined`: cannot tell). */
   owners() {
     return sessionOwners(join(this.options.ompHome, "run", "session-owners"));
@@ -657,7 +737,9 @@ class Daemon {
    */
   ensureLive(id) {
     const live = this.sessions.get(id);
-    if (live !== undefined) return Promise.resolve(live);
+    if (live !== undefined && !live.closed) return Promise.resolve(live);
+    // Its OMP process exited: resume it afresh instead of serving a dead session.
+    if (live !== undefined) this.sessions.delete(id);
     let starting = this.starting.get(id);
     if (starting === undefined) {
       starting = this.resume(id).finally(() => this.starting.delete(id));
@@ -674,7 +756,9 @@ class Daemon {
     // stays with the process that has it (a terminal) until that one exits.
     const owner = (await this.owners())?.get(id);
     if (owner !== undefined) {
-      throw httpError(409, `This session is open in another omp process (pid ${owner}). Close it there to continue here.`);
+      throw httpError(409, `This session is open in another omp process (pid ${owner}). Close it there to continue here.`, {
+        owner: await this.ownerOf(owner, stored.sessionFile),
+      });
     }
     const rpc = new RpcSession({
       cwd: stored.cwd,
@@ -683,16 +767,73 @@ class Daemon {
       autoApprove: this.options.autoApprove,
       extraArgs: this.options.approvalMode ? ["--approval-mode", this.options.approvalMode] : [],
     });
-    await rpc.start();
-    const entry = new SessionEntry(stored.cwd, rpc);
-    await entry.hydrate();
-    entry.id = id;
-    entry.onChange = (changed) => this.remember(changed);
-    entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
-    entry.bind();
-    this.sessions.set(id, entry);
-    this.remember(entry);
-    return entry;
+    // Until the session is registered the process is ours alone to close: left
+    // running it would hold the session's owner lock, so every later open would
+    // be refused as "open in another omp process" naming this very child.
+    try {
+      await rpc.start();
+      const entry = new SessionEntry(stored.cwd, rpc);
+      await entry.hydrate();
+      entry.id = id;
+      entry.onChange = (changed) => this.remember(changed);
+      entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.bind();
+      this.sessions.set(id, entry);
+      this.remember(entry);
+      return entry;
+    } catch (error) {
+      rpc.close();
+      throw error;
+    }
+  }
+
+  /**
+   * Continue a session another omp process holds: ask that process to leave
+   * (see `takeover.mjs`), then open the session here. Concurrent takeovers of
+   * one session share one attempt.
+   * @param {string} id
+   * @param {string} device Who continues it, as the terminal is told.
+   */
+  takeOver(id, device) {
+    let running = this.takingOver.get(id);
+    if (running === undefined) {
+      running = this.runTakeover(id, device).finally(() => this.takingOver.delete(id));
+      this.takingOver.set(id, running);
+    }
+    return running;
+  }
+
+  async runTakeover(id, device) {
+    const live = this.sessions.get(id);
+    if (live !== undefined && !live.closed) return { ...live.snapshot(), takeover: { pid: null, via: "live", waitedMs: 0, busy: false, forks: [] } };
+    // The phone may take over a session listed before this daemon started.
+    if (!this.registry.has(id) && !this.ompSessions.has(id)) await this.listSessions();
+    const stored = this.registry.get(id) ?? this.ompSessions.get(id);
+    if (stored === undefined || typeof stored.sessionFile !== "string") throw httpError(404, "unknown session");
+    if (!existsSync(stored.sessionFile)) throw httpError(410, "session file is gone");
+    const owners = await this.owners();
+    if (owners === undefined) throw httpError(503, "Cannot tell which process holds this session (lsof is not available).");
+    const pid = owners.get(id);
+    let outcome = { pid: null, via: "free", waitedMs: 0, busy: false, forks: [] };
+    if (pid !== undefined) {
+      const info = await processInfo(pid);
+      if (info !== undefined && !isOmpCommand(info.command)) {
+        throw httpError(409, `The process holding this session (pid ${pid}) is not omp; it is left alone.`);
+      }
+      const busy = sessionBusy(stored.sessionFile);
+      const since = Date.now();
+      const left = await askOwnerToLeave({ pid, sessionId: id, sessionFile: stored.sessionFile, device, timings: this.options.takeoverTimings });
+      // The kernel drops the lock with the process; give a slow exit a moment.
+      const deadline = Date.now() + 3_000;
+      while ((await this.owners())?.get(id) === pid && Date.now() < deadline) await new Promise((wait) => setTimeout(wait, 100));
+      // Whoever looks at the terminal sees why omp closed.
+      if (info?.tty !== undefined) tellTerminal(info.tty, takeoverFarewell(device));
+      const forks = forksOf(dirname(stored.sessionFile), id, since);
+      if (forks.length > 0) this.log(new Error(`taking over ${id} from pid ${pid} left forked session files: ${forks.join(", ")}`));
+      outcome = { pid, via: left.via, waitedMs: left.waitedMs, busy, forks };
+    }
+    const entry = await this.ensureLive(id);
+    return { ...entry.snapshot(), takeover: outcome };
   }
 
   async createSession(cwd) {
@@ -703,19 +844,21 @@ class Daemon {
       autoApprove: this.options.autoApprove,
       extraArgs: this.options.approvalMode ? ["--approval-mode", this.options.approvalMode] : [],
     });
-    await rpc.start();
-    const entry = new SessionEntry(cwd, rpc);
-    await entry.hydrate();
-    if (entry.id === "") {
+    try {
+      await rpc.start();
+      const entry = new SessionEntry(cwd, rpc);
+      await entry.hydrate();
+      if (entry.id === "") throw new Error("omp returned no session id");
+      entry.onChange = (changed) => this.remember(changed);
+      entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.bind();
+      this.sessions.set(entry.id, entry);
+      this.remember(entry);
+      return entry;
+    } catch (error) {
       rpc.close();
-      throw new Error("omp returned no session id");
+      throw error;
     }
-    entry.onChange = (changed) => this.remember(changed);
-    entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
-    entry.bind();
-    this.sessions.set(entry.id, entry);
-    this.remember(entry);
-    return entry;
   }
 
   handleUpgrade(req, socket, head) {
@@ -745,10 +888,15 @@ class Daemon {
         });
       })
       .catch((error) => {
-        const status = typeof error?.status === "number" ? error.status : 404;
-        socket.write(`HTTP/1.1 ${status} ${STATUS_CODES[status] ?? "Error"}\r\n\r\n`);
-        socket.destroy();
-        this.log?.(error);
+        const status = typeof error?.status === "number" ? error.status : 500;
+        if (status >= 500) this.log(error);
+        // A browser-style client only sees that the upgrade failed, never why. Finish
+        // the handshake instead, say why the session cannot open, and close: the app
+        // shows the reason and stops retrying what a retry cannot fix.
+        this.wsServer.handleUpgrade(req, socket, head, (ws) => {
+          ws.send(JSON.stringify({ type: "open_failed", status, ...errorBody(error) }));
+          ws.close(OPEN_FAILED_CLOSE_CODE, "session did not open");
+        });
       });
   }
 
@@ -763,8 +911,10 @@ class Daemon {
     try {
       switch (message.type) {
         case "prompt": {
-          if (typeof message.text !== "string" || message.text.trim() === "") throw new Error("empty prompt");
-          await entry.rpc.prompt(message.text);
+          const images = promptImages(message.images);
+          const text = typeof message.text === "string" ? message.text : "";
+          if (text.trim() === "" && images.length === 0) throw new Error("empty prompt");
+          await entry.rpc.prompt(text, images);
           ws.send(JSON.stringify({ type: "accepted", command: "prompt" }));
           return;
         }
@@ -822,7 +972,14 @@ class Daemon {
           throw new Error(`unknown command ${String(message.type)}`);
       }
     } catch (error) {
-      ws.send(JSON.stringify({ type: "error", error: error instanceof Error ? error.message : String(error) }));
+      // `command` names the frame that failed, so the app can tell a refused prompt from any other error.
+      ws.send(
+        JSON.stringify({
+          type: "error",
+          command: typeof message?.type === "string" ? message.type : undefined,
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      );
     }
   }
 
@@ -846,8 +1003,12 @@ class Daemon {
   async close() {
     for (const end of this.streams) end();
     this.streams.clear();
-    for (const entry of this.sessions.values()) entry.close();
+    // Each omp saves and releases its session before the daemon exits.
+    const closing = [...this.sessions.values()].map((entry) => entry.close());
     this.sessions.clear();
+    const outcomes = await Promise.all(closing);
+    const stuck = outcomes.filter((outcome) => outcome === "running").length;
+    if (stuck > 0) console.error(`omp-mobile: ${stuck} omp process(es) ignored SIGINT and SIGTERM and are still running`);
     this.wsServer.close();
     await new Promise((resolveClose) => this.server.close(() => resolveClose()));
   }

package/src/takeover.mjs

@@ -0,0 +1,244 @@
+/**
+ * Taking a session over from the other omp process that holds it.
+ *
+ * OMP lets one process write a session: the first write takes the session's
+ * owner lock (`<omp home>/run/session-owners/<id>.lock`, an OS lock the
+ * kernel drops when the process exits), and a second process that writes the
+ * same session moves to a new file (a fork with `parentSession` set) instead
+ * of mixing entries into the owner's journal. OMP has no way to attach a
+ * second process to a running one (Collab needs the owner to host a room on
+ * a relay), so the phone continues a session by asking its owner to leave:
+ *
+ * 1. A request file beside the session file (`.<name>.omp-mobile-takeover`)
+ *    that the omp-mobile extension in the owner watches: it says where the
+ *    session went, stops the turn, and exits through OMP's own shutdown.
+ * 2. Without an answer from the extension, the owner gets `SIGINT`, then
+ *    `SIGTERM`: OMP routes both through the teardown its Ctrl+C runs (the
+ *    turn is aborted, the session flushed and closed with a `session_exit`
+ *    entry, the lock released). Never `SIGKILL`.
+ *
+ * Only the owner is ever signalled: a process that holds the session without
+ * owning it would fork it into a new file as it saves on exit.
+ */
+import { execFile } from "node:child_process";
+import { closeSync, constants, openSync, readdirSync, readSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** How long each step waits before the next, in milliseconds. */
+export const TAKEOVER_TIMINGS = {
+  /** For the extension to pick up the request (it polls every second). */
+  ack: 2_500,
+  /** For an owner whose extension took the request to exit (OMP closes once its session is idle). */
+  extensionExit: 10_000,
+  /** After `SIGINT`, then after `SIGTERM`. */
+  sigint: 10_000,
+  sigterm: 10_000,
+  poll: 100,
+};
+
+/** How far from the end of a session file the last message is looked for. */
+const TAIL_BYTES = 256 * 1024;
+
+/** The request file the owner's extension watches. */
+export function requestPath(sessionFile) {
+  return join(dirname(sessionFile), `.${basename(sessionFile)}.omp-mobile-takeover`);
+}
+
+/** Whether `pid` is a live process this user may signal. */
+export function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+/**
+ * What a process is: its command and controlling terminal (`ttys007`), or
+ * `undefined` when there is no such process.
+ * @returns {Promise<{pid: number, command: string, tty: string | undefined} | undefined>}
+ */
+export function processInfo(pid) {
+  return new Promise((resolveInfo) => {
+    execFile("ps", ["-o", "tty=", "-o", "args=", "-p", String(pid)], { timeout: 5_000 }, (error, stdout) => {
+      const line = stdout?.split("\n").find((text) => text.trim() !== "");
+      if (error || line === undefined) {
+        resolveInfo(undefined);
+        return;
+      }
+      const [, tty = "", command = ""] = /^\s*(\S+)\s+(.*)$/.exec(line) ?? [];
+      resolveInfo({ pid, command: command.trim(), tty: /^(\?+|-)$/.test(tty) || tty === "" ? undefined : tty });
+    });
+  });
+}
+
+/** Whether a command line runs omp: the binary, or an interpreter running a script named omp. */
+export function isOmpCommand(command) {
+  const [program = "", script = ""] = command.trim().split(/\s+/);
+  return /(^|\/)omp$/.test(program) || /(^|\/)(node|bun)$/.test(program) && /(^|\/)omp$/.test(script);
+}
+
+/**
+ * Whether the session's last message leaves a turn running: a prompt or tool
+ * result not answered yet, or an assistant message that called tools. OMP
+ * writes the assistant's reply when it ends, so a streaming turn ends in the
+ * user's prompt.
+ * @param {string} sessionFile
+ */
+export function sessionBusy(sessionFile) {
+  let fd;
+  try {
+    fd = openSync(sessionFile, "r");
+    const size = statSync(sessionFile).size;
+    const length = Math.min(size, TAIL_BYTES);
+    const buffer = Buffer.alloc(length);
+    readSync(fd, buffer, 0, length, size - length);
+    const lines = buffer.toString("utf8").split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      let entry;
+      try {
+        entry = JSON.parse(lines[i]);
+      } catch {
+        continue;
+      }
+      if (entry?.type !== "message" || entry.message === null || typeof entry.message !== "object") continue;
+      const { role, stopReason } = entry.message;
+      if (role === "assistant") return stopReason === "toolUse";
+      return role === "user" || role === "toolResult";
+    }
+    return false;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * Session files in `dir` forked from `sessionId` (their header's
+ * `parentSession`) and written since `since`: what a second writer leaves.
+ */
+export function forksOf(dir, sessionId, since) {
+  let names;
+  try {
+    names = readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
+  } catch {
+    return [];
+  }
+  const forks = [];
+  for (const name of names) {
+    const file = join(dir, name);
+    let fd;
+    try {
+      if (statSync(file).mtimeMs < since) continue;
+      fd = openSync(file, "r");
+      const buffer = Buffer.alloc(64 * 1024);
+      const head = buffer.toString("utf8", 0, readSync(fd, buffer, 0, buffer.length, 0));
+      for (const line of head.split("\n").slice(0, 3)) {
+        try {
+          const entry = JSON.parse(line);
+          if (entry?.type === "session" && entry.parentSession === sessionId) forks.push(file);
+        } catch {
+          // Not a header line.
+        }
+      }
+    } catch {
+      // Removed while looking.
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+  }
+  return forks;
+}
+
+/**
+ * Write a line to a terminal (`ttys007`) the owner ran in, after it left, so
+ * whoever looks at it sees why omp closed. Best effort.
+ */
+export function tellTerminal(tty, text) {
+  if (!/^tty[A-Za-z0-9]+$/.test(tty)) return false;
+  let fd;
+  try {
+    fd = openSync(`/dev/${tty}`, constants.O_WRONLY | constants.O_NOCTTY | constants.O_NONBLOCK);
+    writeSync(fd, `\r\n${text}\r\n`);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/** What the terminal is told once omp left it. */
+export function takeoverFarewell(device) {
+  return `omp-mobile: this session continues on ${device}. omp closed here so the phone could take it over.`;
+}
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+/** Wait until `done()` or `ms` passed; whether it became true. */
+async function waitFor(done, ms, poll) {
+  const deadline = Date.now() + ms;
+  while (!done()) {
+    if (Date.now() >= deadline) return false;
+    await sleep(poll);
+  }
+  return true;
+}
+
+function exists(path) {
+  try {
+    statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ask the owner of a session to leave, escalating until it exited.
+ * Resolves how it left; rejects (status 504) when it is still running after
+ * `SIGTERM`, in which case it still has the session.
+ * @param {{pid: number, sessionId: string, sessionFile: string, device: string, timings?: Partial<typeof TAKEOVER_TIMINGS>, kill?: (pid: number, signal: string) => void, isAlive?: (pid: number) => boolean}} options
+ * @returns {Promise<{via: "extension" | "SIGINT" | "SIGTERM" | "exited", waitedMs: number}>}
+ */
+export async function askOwnerToLeave({ pid, sessionId, sessionFile, device, timings = {}, kill = process.kill.bind(process), isAlive = alive }) {
+  const t = { ...TAKEOVER_TIMINGS, ...timings };
+  const started = Date.now();
+  const gone = () => !isAlive(pid);
+  const result = (via) => ({ via, waitedMs: Date.now() - started });
+  if (gone()) return result("exited");
+
+  const request = requestPath(sessionFile);
+  const staging = `${request}.${process.pid}.tmp`;
+  let written = false;
+  try {
+    writeFileSync(staging, `${JSON.stringify({ pid, sessionId, device, at: Date.now() })}\n`, { mode: 0o600 });
+    renameSync(staging, request);
+    written = true;
+  } catch {
+    rmSync(staging, { force: true });
+  }
+  try {
+    // The extension removes the request when it takes it, then shuts omp down.
+    if (written && (await waitFor(() => gone() || !exists(request), t.ack, t.poll))) {
+      const taken = !exists(request);
+      if (await waitFor(gone, taken ? t.extensionExit : 0, t.poll)) return result(taken ? "extension" : "exited");
+    }
+  } finally {
+    rmSync(request, { force: true });
+  }
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    try {
+      kill(pid, signal);
+    } catch (error) {
+      if (error?.code === "ESRCH") return result("exited");
+      throw error;
+    }
+    if (await waitFor(gone, signal === "SIGINT" ? t.sigint : t.sigterm, t.poll)) return result(signal);
+  }
+  throw Object.assign(new Error(`The omp process (pid ${pid}) did not exit after SIGINT and SIGTERM; it still has this session.`), {
+    status: 504,
+  });
+}