omp-mobile 0.7.0 → 0.7.2

package/README.md

@@ -42,7 +42,7 @@ Install the plugin into OMP on every computer:
 omp plugin install omp-mobile
 ```
 
-Then in OMP, run `/mobile`. It starts the daemon in the background, bound to the computer's Tailscale address, and shows a pairing code above the composer until the phone connects. The daemon runs on the Bun inside OMP and outlives the terminal and OMP; `/mobile status` shows it and `/mobile stop` ends it. Phone sessions start in the directory where you ran `/mobile` the first time.
+Then in OMP, run `/mobile`. It starts the daemon in the background, bound to the computer's Tailscale address, and shows a pairing code above the composer until the phone connects. The daemon runs on the Bun inside OMP and outlives the terminal and OMP; `/mobile status` shows it and `/mobile stop` ends it. After `omp plugin upgrade omp-mobile`, `omp-mobile restart` puts the running daemon on the new version with the same settings, once no session is mid-turn (safe to run from a phone session). Phone sessions start in the directory where you ran `/mobile` the first time.
 
 Without the plugin, the same daemon runs from npm (Node.js 22.19 or newer) in the foreground: `npm install -g omp-mobile`, then `omp-mobile --host tailscale --cwd ~/project`. It prints the same code.
 

package/package.json

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

package/src/restart.mjs

@@ -0,0 +1,156 @@
+/**
+ * `omp-mobile restart`: replace the running daemon with the code installed
+ * now (after `omp plugin upgrade omp-mobile`), with the same arguments.
+ *
+ * The daemon runs every phone session's omp as its child, so whoever asks
+ * for a restart from such a session (an agent, a phone) would be cut off by
+ * the stop and could never start the new daemon. The work is therefore done
+ * by a detached worker in its own session: it waits until no session is
+ * running a turn (unless `--now`), stops the daemon, starts the new one and
+ * logs beside the state file (`~/.omp-mobile/daemon.log`). Phones reconnect; sessions resume on open.
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { closeSync, mkdirSync, openSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { STATE_FILE, alive, readState, tokenOf } from "./state.mjs";
+
+const SERVER = join(dirname(fileURLToPath(import.meta.url)), "server.mjs");
+/** How long a restart waits for running turns to end before it goes ahead anyway. */
+const IDLE_WAIT_MS = 10 * 60_000;
+/** How long the old daemon gets to close its omp processes, and the new one to come up. */
+const STOP_TIMEOUT_MS = 25_000;
+const START_TIMEOUT_MS = 30_000;
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+function log(line) {
+  console.log(`omp-mobile restart: ${line}`);
+}
+
+/**
+ * The arguments and directory the daemon was started with: recorded in its
+ * state since 0.7.2; for an older daemon, read from its process (an argument
+ * with a space in it cannot be told apart there).
+ * @returns {{argv: string[], cwd: string} | undefined}
+ */
+export function launchOf(state) {
+  if (Array.isArray(state.argv) && typeof state.cwd === "string") return { argv: state.argv, cwd: state.cwd };
+  try {
+    const command = execFileSync("ps", ["-o", "command=", "-p", String(state.pid)], { encoding: "utf8" }).trim();
+    const words = command.split(/\s+/);
+    const at = words.findIndex((word) => word.endsWith("server.mjs"));
+    if (at === -1) return undefined;
+    const cwd = execFileSync("lsof", ["-a", "-p", String(state.pid), "-d", "cwd", "-Fn"], { encoding: "utf8" })
+      .split("\n")
+      .find((line) => line.startsWith("n"))
+      ?.slice(1);
+    return { argv: words.slice(at + 1), cwd: cwd ?? homedir() };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A daemon that cannot say whether a turn runs (before 0.7.2) gets this long, so the turn asking can end. */
+const GRACE_MS = 60_000;
+
+/** Sessions running a turn; undefined when the daemon does not report it. */
+async function busySessions(state) {
+  try {
+    const response = await fetch(`${state.url}/status`, { headers: { authorization: `Bearer ${tokenOf(state.pair)}` }, signal: AbortSignal.timeout(5_000) });
+    const status = await response.json();
+    return typeof status.busySessions === "number" ? status.busySessions : undefined;
+  } catch {
+    return 0;
+  }
+}
+
+/** The worker: wait, stop, start. Runs detached; its output goes to the daemon log. */
+/** The log beside the state file: `~/.omp-mobile/daemon.log` for the default one, where /mobile logs too. */
+function logFileOf(stateFile) {
+  return join(dirname(stateFile), "daemon.log");
+}
+
+async function work(stateFile, now) {
+  const state = readState(stateFile);
+  if (state === undefined) {
+    log("no daemon is running; nothing to restart");
+    return 1;
+  }
+  const launch = launchOf(state);
+  if (launch === undefined) {
+    log(`cannot tell how daemon ${state.pid} was started; restart it by hand`);
+    return 1;
+  }
+  if (!now) {
+    const deadline = Date.now() + IDLE_WAIT_MS;
+    let busy = await busySessions(state);
+    if (busy === undefined) await sleep(GRACE_MS);
+    while (busy !== undefined && busy > 0 && Date.now() < deadline) {
+      await sleep(2_000);
+      busy = await busySessions(state);
+    }
+  }
+  log(`stopping daemon ${state.pid} (${state.version})`);
+  process.kill(state.pid, "SIGTERM");
+  const stopBy = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < stopBy && alive(state.pid)) await sleep(100);
+  if (alive(state.pid)) process.kill(state.pid, "SIGKILL");
+  const out = openSync(logFileOf(stateFile), "a", 0o600);
+  let child;
+  try {
+    child = spawn(process.execPath, [SERVER, ...launch.argv], { cwd: launch.cwd, detached: true, stdio: ["ignore", out, out], env: process.env });
+  } finally {
+    closeSync(out);
+  }
+  child.unref();
+  const startBy = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < startBy) {
+    const next = readState(stateFile);
+    if (next?.pid === child.pid) {
+      log(`daemon ${next.pid} (${next.version}) is running`);
+      return 0;
+    }
+    if (!alive(child.pid)) break;
+    await sleep(250);
+  }
+  log("the new daemon did not start; see the lines above");
+  return 1;
+}
+
+/**
+ * `omp-mobile restart [--now] [--state-file <path>]`: hand the restart to a
+ * detached worker and return at once, so this process may be one of the
+ * daemon's own sessions.
+ * @param {string[]} args
+ */
+export async function runRestartCli(args) {
+  const at = args.indexOf("--state-file");
+  const stateFile = at === -1 ? STATE_FILE : args[at + 1];
+  const now = args.includes("--now");
+  if (args.includes("--worker")) process.exit(await work(stateFile, now));
+  const state = readState(stateFile);
+  if (state === undefined) {
+    console.error("omp-mobile: the daemon is not running. Start it with /mobile in OMP, or omp-mobile --relay.");
+    process.exit(1);
+  }
+  if (launchOf(state) === undefined) {
+    console.error(`omp-mobile: cannot tell how daemon ${state.pid} was started; stop it and start it again by hand.`);
+    process.exit(1);
+  }
+  const logFile = logFileOf(stateFile);
+  mkdirSync(dirname(logFile), { recursive: true, mode: 0o700 });
+  const out = openSync(logFile, "a", 0o600);
+  const worker = spawn(process.execPath, [SERVER, "restart", "--worker", "--state-file", stateFile, ...(now ? ["--now"] : [])], {
+    detached: true,
+    stdio: ["ignore", out, out],
+  });
+  closeSync(out);
+  worker.unref();
+  console.log(
+    now
+      ? `Restarting daemon ${state.pid} now (log: ${logFile}).`
+      : `Daemon ${state.pid} restarts once no session is running a turn (log: ${logFile}). Phones reconnect by themselves.`,
+  );
+}

package/src/rpc-session.mjs

@@ -24,6 +24,8 @@ function withoutBunFlag(env) {
   return rest;
 }
 const REQUEST_TIMEOUT_MS = 60_000;
+/** `get_subagents` reads OMP's in-memory roster: a slow answer means a busy omp, and the files answer without it. */
+const SUBAGENTS_TIMEOUT_MS = 5_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. */
@@ -200,6 +202,9 @@ export class RpcSession extends EventEmitter {
       if (response.data?.protocolVersion !== 2) throw new Error("omp RPC protocol v2 negotiation failed");
       this.protocolVersion = 2;
     }
+    // Lifecycle frames say when a subagent starts and ends (the daemon forwards
+    // them); an omp without the command answers with an error, which is fine.
+    this.request("set_subagent_subscription", { level: "progress" }).catch(() => undefined);
     this.started = true;
     return this;
   }
@@ -312,6 +317,17 @@ export class RpcSession extends EventEmitter {
     });
   }
 
+  /**
+   * The subagents this omp runs now, as OMP's `get_subagents` lists them
+   * (pending and running only; one leaves the list as it ends).
+   * @returns {Promise<object[]>}
+   */
+  async subagents() {
+    const response = await this.request("get_subagents", {}, SUBAGENTS_TIMEOUT_MS);
+    const list = response.data?.subagents;
+    return Array.isArray(list) ? list : [];
+  }
+
   /** @returns {Promise<object>} */
   async getState() {
     const response = await this.request("get_state");

package/src/server.mjs

@@ -11,7 +11,7 @@ import { STATUS_CODES, createServer } from "node:http";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir, hostname, platform } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
 import { renderQr } from "./qr.mjs";
@@ -25,6 +25,8 @@ import { SessionSearchIndex, matchOf, rankRecords, searchTokens, sessionFilesUnd
 import { copyArtifacts, isForkPoint, writeCut } from "./fork.mjs";
 import { RELAY_HEADER, RelayHost } from "./relay.mjs";
 import { DEFAULT_RELAY, runRelayCli } from "./relay-control.mjs";
+import { listSubagents, subagentDir, subagentTranscript } from "./subagents.mjs";
+import { runRestartCli } from "./restart.mjs";
 
 const { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const PROTOCOL = 1;
@@ -112,9 +114,13 @@ export function promptImages(value) {
  * ask for a delta snapshot (`from`, `total`), and `GET /sessions/:id/transcript`
  * answers the same without starting an omp; `session-search`: `GET /sessions/search?q=`
  * finds sessions by title and message text; `fork`: `POST /sessions/:id/fork`
- * starts a new session from a whole session or from one of its messages.
+ * starts a new session from a whole session or from one of its messages;
+ * `subagents`: `GET /sessions/:id/subagents` lists the subagents a session
+ * delegated to and `GET /sessions/:id/subagents/:agent` reads one's transcript
+ * (`since`/`last` as `/transcript`); a live session's socket sends a `subagent`
+ * frame as one starts or ends.
  */
-const FEATURES = ["prompt-images", "takeover", "heartbeat", "transcript-sync", "session-search", "fork"];
+const FEATURES = ["prompt-images", "takeover", "heartbeat", "transcript-sync", "session-search", "fork", "subagents"];
 /** Search results a phone is sent at most. */
 const SEARCH_LIMIT = 50;
 /** Who a phone continues a session on, as the terminal it leaves is told. */
@@ -297,6 +303,11 @@ user (403 otherwise), before the token is checked. Loopback hosts skip admission
                          end-to-end encrypted; pair with \`omp-mobile relay pair\` or /mobile relay
   --relay-dir <dir>      Relay identity and device tokens (default ~/.omp-mobile/relay)
 
+Restart (after \`omp plugin upgrade omp-mobile\`; same --state-file):
+  omp-mobile restart          Restart the running daemon on the installed code, with its arguments, once no
+                              session is running a turn; it is done by a detached process, so this is safe to
+                              run from one of the daemon's own sessions. --now: do not wait.
+
 Relay commands (talk to the running daemon; same --state-file):
   omp-mobile relay pair       Show a pairing QR code, then confirm the phone's 8-digit code
   omp-mobile relay status     Relay server, connection and paired phones
@@ -692,8 +703,32 @@ class SessionEntry {
     }
   }
 
+  /**
+   * A subagent started or ended, as a `subagent` frame: its id as the
+   * `/subagents` routes name it (the path of its transcript under the
+   * session's directory) and how it stands.
+   * @param {any} payload OMP's `subagent_lifecycle` payload
+   */
+  subagentFrame(payload) {
+    const dir = subagentDir(this.state?.sessionFile);
+    const file = typeof payload?.sessionFile === "string" ? payload.sessionFile : undefined;
+    const path = dir !== undefined && file?.endsWith(".jsonl") ? relative(dir, file.slice(0, -6)) : "";
+    const id = path !== "" && !path.startsWith("..") && !isAbsolute(path) ? path.split(sep).join("/") : String(payload?.id ?? "");
+    const status = payload?.status === "started" ? "running" : payload?.status;
+    return {
+      type: "subagent",
+      subagent: { id, agentId: payload?.id, agent: payload?.agent, description: payload?.description, status, parentToolCallId: payload?.parentToolCallId },
+    };
+  }
+
   bind() {
     this.rpc.on("event", (event) => {
+      if (event.type === "subagent_lifecycle") {
+        this.broadcast(this.subagentFrame(event.payload));
+        return;
+      }
+      // Progress ticks (and raw events, at OMP's "events" level) would flood a phone: the transcript route has them.
+      if (event.type === "subagent_progress" || event.type === "subagent_event") return;
       if (event.type === "message_end" && event.message) {
         // A new message is what makes a session the most recent one; opening it,
         // a lifecycle event from a resumed omp, or a state echo are not.
@@ -916,6 +951,8 @@ class Daemon {
         startedAt: this.startedAt,
         url: this.baseUrl(),
         liveSessions: this.sessions.size,
+        // Sessions running a turn: `omp-mobile restart` waits for none.
+        busySessions: [...this.sessions.values()].filter((entry) => entry.state?.isStreaming === true).length,
         eventStreams: this.streams.size,
         lastPhone: this.lastPhone,
         relay: this.relay === undefined ? null : await this.relay.status(),
@@ -980,6 +1017,22 @@ class Daemon {
         sendJson(res, 200, this.transcript(decodeURIComponent(transcript[1]), deltaQuery(url.searchParams)));
         return;
       }
+      const subagents = /^\/sessions\/([^/]+)\/subagents$/.exec(url.pathname);
+      if (subagents !== null && req.method === "GET") {
+        const { sessionFile, running } = await this.subagentSource(decodeURIComponent(subagents[1]));
+        sendJson(res, 200, { subagents: listSubagents(sessionFile, running) });
+        return;
+      }
+      const subagent = /^\/sessions\/([^/]+)\/subagents\/([^/]+)$/.exec(url.pathname);
+      if (subagent !== null && req.method === "GET") {
+        const { sessionFile, running } = await this.subagentSource(decodeURIComponent(subagent[1]));
+        const body = subagentTranscript(sessionFile, decodeURIComponent(subagent[2]), running, deltaQuery(url.searchParams), (message) =>
+          phoneMessage(message, this.blobDir),
+        );
+        if (body === undefined) throw httpError(404, "unknown subagent");
+        sendJson(res, 200, body);
+        return;
+      }
       const answer = /^\/sessions\/([^/]+)\/answer$/.exec(url.pathname);
       if (answer !== null && req.method === "POST") {
         const body = await readBody(req);
@@ -1119,6 +1172,28 @@ class Daemon {
     return deltaBody(saved, held);
   }
 
+  /**
+   * Where a session's subagent transcripts are, without starting an omp, and
+   * which subagents its live omp runs now: null when that omp did not say (an
+   * older OMP), undefined when none runs.
+   * @param {string} id
+   */
+  async subagentSource(id) {
+    const live = this.sessions.get(id);
+    if (live !== undefined && !live.closed && typeof live.state?.sessionFile === "string") {
+      let running = null;
+      try {
+        running = await live.rpc.subagents();
+      } catch {
+        // The files still tell the story; only "still running" is a guess (see `statusOf`).
+      }
+      return { sessionFile: live.state.sessionFile, running };
+    }
+    const sessionFile = this.known(id)?.sessionFile;
+    if (typeof sessionFile !== "string") throw httpError(404, "unknown session");
+    return { sessionFile, running: undefined };
+  }
+
   /** The omp of a session exited: save its transcript and when it was last active. */
   sessionClosed(entry) {
     if (entry.id === "") return;
@@ -1737,6 +1812,10 @@ async function main() {
     await runRelayCli(process.argv.slice(3));
     return;
   }
+  if (process.argv[2] === "restart") {
+    await runRestartCli(process.argv.slice(3));
+    return;
+  }
   const options = parseArgs(process.argv.slice(2));
   if (options.host === "tailscale") options.host = await tailscaleHost(options);
   const token = loadToken(options);
@@ -1745,7 +1824,8 @@ async function main() {
   await daemon.listen();
   const url = daemon.baseUrl();
   const pair = `omp-mobile://pair?url=${encodeURIComponent(url)}&token=${encodeURIComponent(token)}`;
-  writeState(options.stateFile, { pid: process.pid, version: VERSION, url, pair, relay: options.relay || null, startedAt: daemon.startedAt });
+  // `argv` and `cwd`: how to start it again (`omp-mobile restart`).
+  writeState(options.stateFile, { pid: process.pid, version: VERSION, url, pair, relay: options.relay || null, startedAt: daemon.startedAt, argv: process.argv.slice(2), cwd: process.cwd() });
   console.log(`omp-mobile daemon ${VERSION}`);
   console.log(`  listening  ${url}`);
   console.log(`  cwd        ${options.cwd}`);

package/src/subagents.mjs

@@ -0,0 +1,218 @@
+/**
+ * A session's subagents, read where OMP keeps them (`session/sub-sessions.ts`):
+ * a session at `<dir>/<name>.jsonl` stores each subagent's own session at
+ * `<dir>/<name>/<AgentId>.jsonl`, and a subagent's children nest the same way
+ * under `<dir>/<name>/<AgentId>/`. Reading the files serves sessions whose omp
+ * has exited too; a live omp only adds which subagents still run (its RPC
+ * `get_subagents` lists running ones only and forgets them once they end).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { deltaFrom } from "./transcripts.mjs";
+
+/** One agent id as OMP allocates it (a name, `-2` on a repeat, `.` before a nested child's own). */
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,159}$/;
+/** The stem of OMP's advisor transcripts (`advisor/transcript-recorder.ts`). */
+const ADVISOR = "__advisor";
+/** Deep enough for any real delegation chain; a symlink loop cannot recurse past it. */
+const MAX_DEPTH = 6;
+/** The assignment shown in a list: its start, the rest is in the transcript. */
+const TASK_EXCERPT = 300;
+/** Parsed files kept while their size and mtime hold: the app polls a running subagent's transcript. */
+const CACHE_LIMIT = 32;
+/** @type {Map<string, {mtimeMs: number, size: number, parsed: Parsed}>} */
+const cache = new Map();
+
+/**
+ * @typedef {{agent?: string, task?: string, messages: any[]}} Parsed
+ * @typedef {{id: string, agentId: string, parent: string | null, file: string, aborted: boolean}} Found
+ * @typedef {{id?: string, status?: string, description?: string, parentToolCallId?: string, sessionFile?: string}} LiveSnapshot
+ */
+
+/** Where a session's subagent transcripts live; undefined for a file that is not a session. */
+export function subagentDir(sessionFile) {
+  return typeof sessionFile === "string" && sessionFile.endsWith(".jsonl") ? sessionFile.slice(0, -6) : undefined;
+}
+
+/**
+ * Every subagent transcript under a session, parents before their children.
+ * `id` is the slash-joined path of agent ids from the session ("Scout", "Scout/Helper").
+ * @param {string} sessionFile
+ * @returns {Found[]}
+ */
+export function findSubagents(sessionFile) {
+  const dir = subagentDir(sessionFile);
+  /** @type {Found[]} */
+  const found = [];
+  if (dir !== undefined) walk(dir, null, 0, found);
+  return found;
+}
+
+/** @param {string} dir @param {string | null} parent @param {number} depth @param {Found[]} out */
+function walk(dir, parent, depth, out) {
+  let dirents;
+  try {
+    dirents = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const files = new Set();
+  const dirs = new Set();
+  for (const dirent of dirents) {
+    if (dirent.isFile()) files.add(dirent.name);
+    else if (dirent.isDirectory()) dirs.add(dirent.name);
+  }
+  for (const name of [...files].sort()) {
+    if (!name.endsWith(".jsonl")) continue;
+    const agentId = name.slice(0, -6);
+    // `__advisor.jsonl` and `__advisor.<slug>.jsonl` share the directory and are not subagents; backups are not either.
+    if (!SEGMENT.test(agentId) || agentId === ADVISOR || agentId.startsWith(`${ADVISOR}.`) || name.includes(".bak")) continue;
+    const id = parent === null ? agentId : `${parent}/${agentId}`;
+    out.push({ id, agentId, parent, file: join(dir, name), aborted: files.has(`${name}.tombstone`) });
+    // Only real directories: a symlinked one could loop back up the tree.
+    if (depth + 1 < MAX_DEPTH && dirs.has(agentId)) walk(join(dir, agentId), id, depth + 1, out);
+  }
+}
+
+/**
+ * The transcript at `id` under a session; undefined for an id that is malformed
+ * or names no transcript. Segments are checked, so no id leaves the session's directory.
+ * @param {string} sessionFile
+ * @param {string} id
+ */
+export function subagentFile(sessionFile, id) {
+  const dir = subagentDir(sessionFile);
+  const segments = id.split("/");
+  if (dir === undefined || segments.length > MAX_DEPTH || !segments.every((segment) => SEGMENT.test(segment))) return undefined;
+  const file = join(dir, ...segments.slice(0, -1), `${segments.at(-1)}.jsonl`);
+  return existsSync(file) ? file : undefined;
+}
+
+/**
+ * A subagent session file's messages in order, its agent type and assignment
+ * (OMP's `session_init` entry). Lines that do not parse (a write in progress) are skipped.
+ * @param {string} file
+ * @returns {Parsed | undefined}
+ */
+export function readSubagent(file) {
+  let info;
+  try {
+    info = statSync(file);
+  } catch {
+    return undefined;
+  }
+  const hit = cache.get(file);
+  if (hit !== undefined && hit.mtimeMs === info.mtimeMs && hit.size === info.size) return hit.parsed;
+  /** @type {Parsed} */
+  const parsed = { messages: [] };
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (line === "") continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.type === "message" && entry.message !== null && typeof entry.message === "object") parsed.messages.push(entry.message);
+    else if (entry?.type === "session_init") {
+      if (typeof entry.agent === "string") parsed.agent = entry.agent;
+      if (typeof entry.task === "string") parsed.task = entry.task;
+    }
+  }
+  cache.delete(file);
+  cache.set(file, { mtimeMs: info.mtimeMs, size: info.size, parsed });
+  while (cache.size > CACHE_LIMIT) cache.delete(cache.keys().next().value);
+  return parsed;
+}
+
+/**
+ * How a subagent stands: running while the live omp lists it; else from its
+ * transcript: killed (a tombstone, or a last reply that was aborted), failed
+ * (a last reply that errored), or completed. One that stopped mid-step
+ * without a final reply is running when its omp is live but could not say
+ * (`unsure`: an omp without `get_subagents`), aborted otherwise (its omp exited).
+ * @param {{aborted: boolean, live?: LiveSnapshot, unsure?: boolean, messages: any[]}} subagent
+ * @returns {"running" | "completed" | "failed" | "aborted"}
+ */
+export function statusOf({ aborted, live, unsure = false, messages }) {
+  if (live !== undefined) return "running";
+  if (aborted) return "aborted";
+  const last = messages.at(-1);
+  if (last?.role === "assistant" && last.stopReason === "error") return "failed";
+  if (last?.role === "assistant" && last.stopReason === "aborted") return "aborted";
+  if (last?.role === "assistant" && last.stopReason !== "toolUse") return "completed";
+  return unsure ? "running" : "aborted";
+}
+
+/**
+ * The phone's list entry for one subagent. `running`: the live omp's
+ * `get_subagents`; null when it is live but could not answer; undefined when no omp runs.
+ * @param {Found} found
+ * @param {Parsed} parsed
+ * @param {readonly LiveSnapshot[] | null | undefined} running
+ */
+function summaryOf(found, parsed, running) {
+  let updatedAt = 0;
+  try {
+    updatedAt = statSync(found.file).mtimeMs;
+  } catch {
+    // Removed between the walk and now: it is listed as it was read.
+  }
+  // OMP lists pending and running subagents only, and drops one as it ends.
+  const live = running?.find((snapshot) => snapshot?.sessionFile === found.file);
+  // OMP opens every assignment with the same line; the list shows what the task actually is.
+  const task = parsed.task?.replace(/^\s*Complete assignment thoroughly:\s*/i, "").trim();
+  return {
+    id: found.id,
+    agentId: found.agentId,
+    parent: found.parent,
+    agent: parsed.agent,
+    description: live?.description,
+    task: task === undefined || task === "" ? undefined : task.length > TASK_EXCERPT ? `${task.slice(0, TASK_EXCERPT)}…` : task,
+    status: statusOf({ aborted: found.aborted, live, unsure: running === null, messages: parsed.messages }),
+    messageCount: parsed.messages.length,
+    updatedAt: Math.round(updatedAt),
+    parentToolCallId: live?.parentToolCallId,
+  };
+}
+
+/**
+ * Every subagent of a session, parents before their children.
+ * @param {string} sessionFile
+ * @param {readonly LiveSnapshot[] | null} [running] see `summaryOf`
+ */
+export function listSubagents(sessionFile, running) {
+  const list = [];
+  for (const found of findSubagents(sessionFile)) {
+    const parsed = readSubagent(found.file);
+    if (parsed !== undefined) list.push(summaryOf(found, parsed, running));
+  }
+  return list;
+}
+
+/**
+ * One subagent and its messages: those after what the phone holds when its
+ * copy lines up (`since`/`last`, as `/transcript`), else all of them.
+ * @param {string} sessionFile
+ * @param {string} id
+ * @param {readonly LiveSnapshot[] | null | undefined} running see `summaryOf`
+ * @param {{since: number, last: string}} held
+ * @param {(message: any) => any} toPhone
+ */
+export function subagentTranscript(sessionFile, id, running, held, toPhone) {
+  const file = subagentFile(sessionFile, id);
+  const parsed = file === undefined ? undefined : readSubagent(file);
+  if (file === undefined || parsed === undefined) return undefined;
+  const segments = id.split("/");
+  const found = {
+    id,
+    agentId: segments.at(-1) ?? id,
+    parent: segments.length > 1 ? segments.slice(0, -1).join("/") : null,
+    file,
+    aborted: existsSync(`${file}.tombstone`),
+  };
+  const subagent = summaryOf(found, parsed, running);
+  const { messages } = parsed;
+  const from = deltaFrom(messages, held.since, held.last);
+  return { subagent, from, total: messages.length, messages: messages.slice(from).map(toPhone) };
+}