omp-mobile 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-mobile",
-  "version": "0.3.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-session.mjs

@@ -12,6 +12,8 @@ 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
@@ -403,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, MESSAGE_PAGE_LIMIT };
+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;
@@ -73,19 +74,29 @@ export function promptImages(value) {
 
 /**
  * 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`.
+ * 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"];
+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, waiting?: number}} 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) {
@@ -336,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;
@@ -472,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();
   }
 }
 
@@ -511,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));
@@ -624,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]);
@@ -648,7 +669,7 @@ class Daemon {
       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, { error: error instanceof Error ? error.message : String(error) });
+      sendJson(res, status, errorBody(error));
     }
   }
 
@@ -672,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"));
@@ -721,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,
@@ -750,6 +787,55 @@ class Daemon {
     }
   }
 
+  /**
+   * 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) {
     const rpc = new RpcSession({
       cwd,
@@ -808,7 +894,7 @@ class Daemon {
         // 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, error: error instanceof Error ? error.message : String(error) }));
+          ws.send(JSON.stringify({ type: "open_failed", status, ...errorBody(error) }));
           ws.close(OPEN_FAILED_CLOSE_CODE, "session did not open");
         });
       });
@@ -917,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,
+  });
+}