omp-mobile 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-mobile",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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 = 500;
+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
@@ -140,7 +142,15 @@ export class RpcSession extends EventEmitter {
       stdio: ["pipe", "pipe", "pipe"],
     });
     this.child = child;
-    child.on("error", (error) => this.#fail(error));
+    // A process that never started (missing binary, a cwd that was removed)
+    // emits `error` and no `exit`, so `closed` never comes: without its own
+    // signal the `ready` wait would sit out the whole start timeout.
+    child.on("error", (error) => {
+      this.closed = true;
+      this.lastError = error;
+      this.emit("start-error", error);
+      this.#fail(error);
+    });
     child.on("exit", (code, signal) => {
       this.closed = true;
       // Nothing can answer the dialogs of a process that is gone.
@@ -155,7 +165,10 @@ export class RpcSession extends EventEmitter {
     });
     const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
     const ready = new Promise((resolve, reject) => {
-      const timer = setTimeout(() => reject(new Error("omp RPC did not become ready")), START_TIMEOUT_MS);
+      const timer = setTimeout(
+        () => reject(new Error(`omp RPC did not become ready in ${Math.round(START_TIMEOUT_MS / 1000)}s: ${this.stderr.trim().slice(-500) || "no output"}`)),
+        START_TIMEOUT_MS,
+      );
       const onReady = (message) => {
         clearTimeout(timer);
         this.off("ready", onReady);
@@ -166,6 +179,14 @@ export class RpcSession extends EventEmitter {
         clearTimeout(timer);
         reject(new Error(`omp exited before ready: ${this.stderr.slice(-500)}`));
       });
+      // `start()` is called from the daemon's request path: the reason a process
+      // cannot start (no omp on PATH, the session's directory is gone) has to
+      // reach the phone instead of a generic timeout.
+      this.once("start-error", (error) => {
+        clearTimeout(timer);
+        this.off("ready", onReady);
+        reject(new Error(`omp could not start in ${this.cwd}: ${error?.message ?? String(error)}`));
+      });
     });
     lines.on("line", (line) => this.#onLine(line));
     const hello = await ready;
@@ -403,16 +424,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;
@@ -42,6 +43,18 @@ const STATE_EVENTS = new Set([
   "todo_auto_clear",
   "goal_updated",
 ]);
+/**
+ * How long OMP's session directory and owner locks are reused for, in ms.
+ * The phone probes every 15 s; without this every probe would rescan every
+ * session file (hundreds, often a gigabyte) and spawn `lsof` again.
+ */
+const SESSION_SCAN_TTL_MS = 3_000;
+const OWNERS_TTL_MS = 1_500;
+/** WebSocket keepalive: a protocol ping plus a `ping` frame, and a dead peer after one missed beat. */
+const HEARTBEAT_MS = 20_000;
+/** A live omp nobody has looked at for this long is closed; the next open resumes it. */
+const IDLE_SESSION_MS = 30 * 60_000;
+const REAP_INTERVAL_MS = 60_000;
 /** 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. */
@@ -73,19 +86,31 @@ 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;
+ * `heartbeat`: session sockets get a `ping` frame every 20 s, so the app can
+ * treat a silent link as gone.
  */
-const FEATURES = ["prompt-images"];
+const FEATURES = ["prompt-images", "takeover", "heartbeat"];
+/** 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) {
@@ -238,6 +263,27 @@ function saveRegistry(path, registry) {
   writeFileSync(path, `${JSON.stringify(Object.fromEntries(registry), null, 2)}\n`, { mode: 0o600 });
 }
 
+/**
+ * The directory an omp starts in, recreated when it has been removed (a
+ * session in /tmp outlives its directory). Answers a 410 the phone can show
+ * when it cannot be recreated (a parent that is a file, no permission).
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function ensureWorkingDirectory(cwd) {
+  try {
+    if (statSync(cwd).isDirectory()) return cwd;
+  } catch {
+    // Missing: recreate it below.
+  }
+  try {
+    mkdirSync(cwd, { recursive: true });
+    return cwd;
+  } catch {
+    throw httpError(410, `the session's working directory is gone and cannot be recreated: ${cwd}`);
+  }
+}
+
 function storedSummary(stored) {
   return {
     id: stored.id,
@@ -336,10 +382,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;
@@ -377,6 +423,8 @@ class SessionEntry {
      */
     this.onBroadcast = undefined;
     this.closed = false;
+    /** When the last phone left; undefined while one is connected. The reaper reads it. */
+    this.idleSince = undefined;
   }
 
   async hydrate() {
@@ -472,10 +520,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();
   }
 }
 
@@ -509,8 +558,18 @@ class Daemon {
     this.streams = new Set();
     /** OMP's own sessions as last listed, for resuming one the app picked. @type {Map<string, import("./omp-sessions.mjs").OmpSession>} */
     this.ompSessions = new Map();
+    /** The last full scan of OMP's session directory, reused within `SESSION_SCAN_TTL_MS`. */
+    this.sessionScan = { at: 0, list: /** @type {import("./omp-sessions.mjs").OmpSession[]} */ ([]), pending: undefined };
+    /** The last `lsof` of the owner locks, pending or settled, reused within `OWNERS_TTL_MS`. */
+    this.ownerLookup = { at: 0, owners: /** @type {Promise<Map<string, number> | undefined> | undefined} */ (undefined) };
+    /** @type {ReturnType<typeof setInterval> | undefined} */
+    this.heartbeat = undefined;
+    /** @type {ReturnType<typeof setInterval> | undefined} */
+    this.reaper = undefined;
     /** 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 +683,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]);
@@ -636,6 +702,7 @@ class Daemon {
           const live = this.sessions.get(id);
           if (live !== undefined) this.attention.forget(live);
           live?.close();
+          this.forgetOwners();
           this.sessions.delete(id);
           this.registry.delete(id);
           saveRegistry(this.options.registryFile, this.registry);
@@ -648,7 +715,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));
     }
   }
 
@@ -664,23 +731,65 @@ class Daemon {
       .filter((stored) => !known.has(stored.id))
       .map((stored) => storedSummary(stored));
     for (const session of dormant) known.add(session.id);
-    const [found, owners] = await Promise.all([
-      listOmpSessions(join(this.options.ompHome, "agent", "sessions"), { limit: OMP_SESSION_LIMIT }),
-      this.owners(),
-    ]);
+    const [found, owners] = await Promise.all([this.scanOmpSessions(), this.owners()]);
     this.ompSessions = new Map(found.map((session) => [session.id, session]));
     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];
   }
 
-  /** Which sessions some omp process holds open (`undefined`: cannot tell). */
+  /**
+   * 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 };
+  }
+
+  /**
+   * OMP's sessions, rescanned at most every `SESSION_SCAN_TTL_MS`: a phone's
+   * probes ask for the same list every few seconds, and reading the first
+   * 512 KB of up to 50 of hundreds of files is the daemon's most expensive read.
+   */
+  scanOmpSessions() {
+    const scan = this.sessionScan;
+    if (Date.now() - scan.at < SESSION_SCAN_TTL_MS) return Promise.resolve(scan.list);
+    if (scan.pending !== undefined) return scan.pending;
+    scan.pending = listOmpSessions(join(this.options.ompHome, "agent", "sessions"), { limit: OMP_SESSION_LIMIT }).then(
+      (list) => {
+        this.sessionScan = { at: Date.now(), list, pending: undefined };
+        return list;
+      },
+      (error) => {
+        scan.pending = undefined;
+        throw error;
+      },
+    );
+    return scan.pending;
+  }
+
+  /** Which sessions some omp process holds open (`undefined`: cannot tell). Cached for `OWNERS_TTL_MS`. */
   owners() {
-    return sessionOwners(join(this.options.ompHome, "run", "session-owners"));
+    const lookup = this.ownerLookup;
+    if (lookup.owners !== undefined && Date.now() - lookup.at < OWNERS_TTL_MS) return lookup.owners;
+    const owners = sessionOwners(join(this.options.ompHome, "run", "session-owners"));
+    this.ownerLookup = { at: Date.now(), owners };
+    return owners;
+  }
+
+  /** The owner locks changed (a takeover, an omp closing): the next look must not reuse the cache. */
+  forgetOwners() {
+    this.ownerLookup = { at: 0, owners: undefined };
   }
 
   remember(entry) {
@@ -719,12 +828,20 @@ class Daemon {
     if (!existsSync(stored.sessionFile)) throw httpError(410, "session file is gone");
     // A second omp on the same file would fork it into a new one; the session
     // stays with the process that has it (a terminal) until that one exits.
+    // This comes before the directory check: a held session is a takeover, not
+    // a broken one, and the phone's Take over button needs the 409.
     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),
+      });
     }
+    // OMP refuses to start in a directory that no longer exists (a session in
+    // /tmp whose directory was cleaned up). Recreate it here instead of letting
+    // the start wait out its timeout and answer with a bare 500.
+    const cwd = ensureWorkingDirectory(stored.cwd);
     const rpc = new RpcSession({
-      cwd: stored.cwd,
+      cwd,
       ompBin: this.options.omp,
       resume: stored.sessionFile,
       autoApprove: this.options.autoApprove,
@@ -750,6 +867,57 @@ 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 };
+    }
+    // The owner left: the cached lock map is stale and would refuse this open.
+    this.forgetOwners();
+    const entry = await this.ensureLive(id);
+    return { ...entry.snapshot(), takeover: outcome };
+  }
+
   async createSession(cwd) {
     const rpc = new RpcSession({
       cwd,
@@ -789,29 +957,62 @@ class Daemon {
       return;
     }
     this.noteClient(req);
-    void this.ensureLive(decodeURIComponent(match[1]))
-      .then((entry) => {
-        this.wsServer.handleUpgrade(req, socket, head, (ws) => {
-          entry.clients.add(ws);
-          ws.send(JSON.stringify({ type: "snapshot", ...entry.snapshot() }));
+    const id = decodeURIComponent(match[1]);
+    // Finish the handshake before the session is open: a slow omp can take
+    // tens of seconds, and a phone's WebSocket client gives up after ~10 s --
+    // then retries, starting another omp every time. The snapshot (or
+    // `open_failed`) follows on the open socket instead.
+    this.wsServer.handleUpgrade(req, socket, head, (ws) => {
+      ws.isAlive = true;
+      ws.on("pong", () => {
+        ws.isAlive = true;
+      });
+      /** @type {SessionEntry | undefined} */
+      let entry;
+      /** Frames the phone sent before the session was ready. */
+      const early = [];
+      ws.on("message", (data) => {
+        if (entry === undefined) {
+          early.push(data.toString());
+          return;
+        }
+        void this.handleClientMessage(entry, ws, data.toString());
+      });
+      ws.on("close", () => {
+        if (entry !== undefined) this.detach(entry, ws);
+      });
+      ws.on("error", () => {
+        if (entry !== undefined) this.detach(entry, ws);
+      });
+      void this.ensureLive(id).then(
+        (live) => {
+          entry = live;
+          if (ws.readyState !== 1) return;
+          live.clients.add(ws);
+          live.idleSince = undefined;
+          ws.send(JSON.stringify({ type: "snapshot", ...live.snapshot() }));
           // A dialog opened before this client connected (it may have come from a notification tap).
-          for (const request of entry.openRequests()) ws.send(JSON.stringify({ type: "approval", request }));
-          ws.on("message", (data) => void this.handleClientMessage(entry, ws, data.toString()));
-          ws.on("close", () => entry.clients.delete(ws));
-          ws.on("error", () => entry.clients.delete(ws));
-        });
-      })
-      .catch((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, error: error instanceof Error ? error.message : String(error) }));
+          for (const request of live.openRequests()) ws.send(JSON.stringify({ type: "approval", request }));
+          for (const data of early) void this.handleClientMessage(live, ws, data);
+          early.length = 0;
+        },
+        (error) => {
+          const status = typeof error?.status === "number" ? error.status : 500;
+          if (status >= 500) this.log(error);
+          if (ws.readyState !== 1) return;
+          // Say why the session cannot open and close: the app shows the reason
+          // and stops retrying what a retry cannot fix.
+          ws.send(JSON.stringify({ type: "open_failed", status, ...errorBody(error) }));
           ws.close(OPEN_FAILED_CLOSE_CODE, "session did not open");
-        });
-      });
+        },
+      );
+    });
+  }
+
+  /** A phone left a session: it counts as idle from now, for the reaper. */
+  detach(entry, ws) {
+    if (!entry.clients.delete(ws)) return;
+    if (entry.clients.size === 0) entry.idleSince = Date.now();
   }
 
   async handleClientMessage(entry, ws, text) {
@@ -910,15 +1111,65 @@ class Daemon {
 
   listen() {
     return new Promise((resolveListen) => {
-      this.server.listen(this.options.port, this.options.host, () => resolveListen());
+      this.server.listen(this.options.port, this.options.host, () => {
+        this.startTimers();
+        resolveListen();
+      });
     });
   }
 
+  /** Keepalive pings and the idle-session reaper, once the daemon listens. */
+  startTimers() {
+    this.heartbeat = setInterval(() => this.pingClients(), this.options.heartbeatMs ?? HEARTBEAT_MS);
+    this.heartbeat.unref?.();
+    this.reaper = setInterval(() => this.reapIdleSessions(), this.options.reapIntervalMs ?? REAP_INTERVAL_MS);
+    this.reaper.unref?.();
+  }
+
+  /**
+   * Ping every WebSocket and drop the ones that missed the previous beat. A
+   * protocol ping plus a small frame keeps NAT and phone radios from dropping
+   * an idle session silently; the app ignores the frame, older ones too.
+   */
+  pingClients() {
+    const beat = JSON.stringify({ type: "ping", at: Date.now() });
+    for (const ws of this.wsServer.clients) {
+      if (ws.isAlive === false) {
+        ws.terminate();
+        continue;
+      }
+      ws.isAlive = false;
+      try {
+        ws.ping();
+        ws.send(beat);
+      } catch {
+        // Closing; the close handler cleans up.
+      }
+    }
+  }
+
+  /** Close live sessions no phone has looked at for `IDLE_SESSION_MS` (never mid-turn). */
+  reapIdleSessions() {
+    const now = Date.now();
+    for (const [id, entry] of this.sessions) {
+      if (entry.clients.size > 0 || entry.state?.isStreaming === true) continue;
+      if (now - (entry.idleSince ?? entry.updatedAt) < (this.options.idleSessionMs ?? IDLE_SESSION_MS)) continue;
+      entry.close();
+      this.sessions.delete(id);
+    }
+  }
+
   async close() {
+    clearInterval(this.heartbeat);
+    clearInterval(this.reaper);
     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,249 @@
+/**
+ * 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. The extension
+ * path (a terminal with the plugin loaded) answers within a second or two;
+ * the signal path is the fallback for an omp that predates the extension, and
+ * OMP leaves on SIGINT promptly, so the waits are short rather than generous.
+ */
+export const TAKEOVER_TIMINGS = {
+  /** For the extension to pick up the request (it polls every 500 ms). */
+  ack: 1_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: 5_000,
+  sigterm: 5_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,
+  });
+}