omo-ai 5.0.1 → 5.1.1

package/bin/lib/category-coverage.js

@@ -97,7 +97,7 @@ export async function engineAvailableModels(input) {
 }
 
 /**
- * @typedef {{ name: string, providers: string[] }} UnusableCategory
+ * @typedef {{ name: string, providers: string[], unlistedProviderModel?: string }} UnusableCategory
  * @typedef {{ usable: string[], unusable: UnusableCategory[] }} CategoryCoverage
  * @typedef {{
  *   models: EngineModel[],
@@ -120,6 +120,10 @@ function total(coverage) {
 
 // The category-unavailable notice's wording (omo-senpi components/task/category-unavailable-warning.ts).
 function gapLine(gap) {
+  if (gap.unlistedProviderModel !== undefined) {
+    const gateway = gap.unlistedProviderModel.slice(0, gap.unlistedProviderModel.indexOf("/"))
+    return `Category "${gap.name}" is unavailable: only ${gateway}, which its chain does not list, serves its models, and omo never bills a builtin category to an unlisted provider. Connect one of its providers (${gap.providers.join(", ")}) with /login <provider>, or opt in with categories.${gap.name}.model = "${gap.unlistedProviderModel}" in omo.json.`
+  }
   if (gap.providers.length === 0) {
     return `Category "${gap.name}" has no usable model: your connected providers serve none of its fallback-chain models. Pin categories.${gap.name}.model in omo.json.`
   }

package/bin/lib/computer-use-doctor.js

@@ -0,0 +1,90 @@
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { packageManifest, packageRoot } from "./package-paths.js"
+
+export const COMPUTER_USE_RUNTIME = join("plugin", "runtime", "category-coverage", "index.js")
+
+async function loadRuntime() {
+  return import(pathToFileURL(join(packageRoot, COMPUTER_USE_RUNTIME)).href)
+}
+
+function baseLine(report) {
+  return `INFO computer use: enabled=${report.enabled} supported=${report.supported} host=${report.host}`
+}
+
+function readyLines(report) {
+  const capabilities = report.capabilities
+  const displayServer = capabilities.displayServer ? ` (${capabilities.displayServer})` : ""
+  const backendLevel = capabilities.backend === "unavailable" ? "WARN" : "PASS"
+  const permissionLevel = capabilities.capture && capabilities.input && capabilities.ax ? "PASS" : "WARN"
+  const displayLevel = capabilities.displayCount > 0 && !capabilities.screenLocked ? "PASS" : "WARN"
+  const stopLevel = capabilities.stopPath === "none" ? "WARN" : "PASS"
+  const stopReason = capabilities.stopReason ? ` reason=${capabilities.stopReason}` : ""
+  // The engine arms the stop chord only when a session starts input (`stopPath.start`), so a pre-session
+  // probe always sees `none` / `no-global-listener`; that is the normal idle state, not a failure.
+  const stopLine =
+    capabilities.stopPath === "none" && capabilities.stopReason === "no-global-listener"
+      ? "INFO computer use stop path: not armed until computer use starts input (checked when a session activates)"
+      : `${stopLevel} computer use stop path: ${capabilities.stopPath}${stopReason}`
+  return [
+    baseLine(report),
+    `PASS computer use engine: ${report.enginePath} (version ${report.hello.engineVersion}, ABI ${report.hello.abi}, protocol ${report.hello.protocolVersion})`,
+    `${backendLevel} computer use backend: ${capabilities.backend}${displayServer}`,
+    `${permissionLevel} computer use permissions: capture=${capabilities.capturePermission} input=${capabilities.inputPermission} accessibility=${capabilities.axPermission}`,
+    `${displayLevel} computer use display: count=${capabilities.displayCount} screenLocked=${capabilities.screenLocked}`,
+    stopLine,
+  ]
+}
+
+export function formatComputerUseDoctorLines(report) {
+  switch (report.kind) {
+    case "ready":
+      return readyLines(report)
+    case "skipped":
+      return [
+        baseLine(report),
+        report.reason === "disabled"
+          ? "INFO computer use probe: skipped because computer.enabled=false"
+          : `INFO computer use probe: skipped because ${report.host} is unsupported`,
+      ]
+    case "unavailable":
+      return [
+        baseLine(report),
+        `FAIL computer use engine: ${report.diagnostic.code}: ${report.diagnostic.message} ${report.diagnostic.cause}`.trimEnd(),
+        `INFO computer use engine paths tried: ${report.diagnostic.attemptedPaths.join(", ") || "<none>"}`,
+      ]
+    case "not-installed":
+      return [
+        baseLine(report),
+        "INFO computer use engine: not installed yet; it is downloaded the first time computer use starts",
+        `INFO computer use engine paths checked: ${report.attemptedPaths.join(", ") || "<none>"}`,
+      ]
+    case "failed":
+      return [
+        baseLine(report),
+        `FAIL computer use engine: ${report.code}: ${report.message}`,
+        `INFO computer use engine path: ${report.enginePath}`,
+      ]
+    default:
+      throw new TypeError(`unknown computer use doctor report kind: ${String(report.kind)}`)
+  }
+}
+
+export async function doctorComputerUseLines(options = {}) {
+  try {
+    const runtime = await (options.loadRuntime ?? loadRuntime)()
+    const report = await runtime.computerUseDoctorReport({
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      version: packageManifest().version,
+      packageRoot,
+      platform: options.platform ?? process.platform,
+      arch: options.arch ?? process.arch,
+      timeoutMs: options.timeoutMs,
+    })
+    return formatComputerUseDoctorLines(report)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return [`WARN computer use: diagnostics unavailable: ${message}`]
+  }
+}

package/bin/lib/daemon-args.js

@@ -0,0 +1,54 @@
+/**
+ * The `omo daemon` command-line contract: the flags this wrapper consumes, its exit codes, and the
+ * small argv helpers `runDaemonCommand` uses. Moved verbatim out of `daemon.js`.
+ */
+
+/** Flags this wrapper consumes itself; anything else after `attach` belongs to the launch. */
+const DAEMON_FLAGS = new Set([
+  "--json",
+  "--no-upgrade",
+  "--persistent",
+  "--foreground",
+  "--include-workers",
+  "--drain",
+  "--all",
+  "--wait",
+  "--dry-run",
+  "--allow-missing-index",
+  "--prune-store-index",
+])
+const DAEMON_VALUE_FLAGS = new Set(["--store", "--timeout"])
+
+/** A named code per outcome, so a script never has to parse the message to know what happened. */
+export const DAEMON_EXIT = {
+  ok: 0,
+  usage: 2,
+  notRunning: 3,
+  unsupported: 4,
+  engineRefused: 5,
+}
+
+export function readTimeoutSeconds(args) {
+  const index = args.indexOf("--timeout")
+  if (index === -1) return 600
+  const value = Number(args[index + 1])
+  return Number.isFinite(value) && value >= 0 ? value : 600
+}
+
+export function attachLaunchArgs(args) {
+  const launchArgs = []
+  for (let index = 1; index < args.length; index += 1) {
+    const argument = args[index]
+    if (DAEMON_FLAGS.has(argument)) continue
+    if (DAEMON_VALUE_FLAGS.has(argument)) {
+      index += 1
+      continue
+    }
+    launchArgs.push(argument)
+  }
+  return launchArgs
+}
+
+export function blockingPause(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds)
+}

package/bin/lib/daemon-doctor-report.js

@@ -0,0 +1,30 @@
+import { DAEMON_EXIT } from "./daemon-args.js"
+import { parseEngineLine, readAllEndpoints } from "./daemon-operations.js"
+import { formatDoctorLines } from "./daemon-status.js"
+
+/**
+ * The `omo doctor` view: one INFO line, never a FAIL - a machine without a daemon is healthy,
+ * it just has nothing shared to report. Returned as lines so doctor can place it with the rest.
+ */
+export function daemonReportLines({ engine, pluginRoot, agentDir, env, platform }) {
+  if (platform === "win32") return ["INFO Daemon: unavailable on win32 (no unix socket to share)"]
+  const all = readAllEndpoints(engine, agentDir, env)
+  if (all.kind === "all") {
+    if (all.endpoints.length === 0) return ["INFO Daemon: not running"]
+    return formatDoctorLines(all.endpoints)
+  }
+  const result = engine.run(["host", "status", "--json"], { env: { ...env, OMO_AGENT_DIR: agentDir } })
+  const parsed = parseEngineLine(result.stdout ?? "")
+  if (result.exitCode !== DAEMON_EXIT.ok || parsed === undefined) {
+    return ["INFO Daemon: not running", "INFO Hosts: engine too old to enumerate"]
+  }
+  const sessions = parsed.sessions?.total ?? parsed.sessions?.length ?? 0
+  const parts = [
+    `pid ${parsed.pid}`,
+    parsed.instanceId === undefined ? undefined : `instance ${parsed.instanceId}`,
+    parsed.engineVersion === undefined ? undefined : `engine ${parsed.engineVersion}`,
+    `${sessions} session(s)`,
+    `zombies ${parsed.zombies ?? 0}`,
+  ].filter(Boolean)
+  return [`INFO Daemon: running ${parts.join(" · ")}`, "INFO Hosts: engine too old to enumerate"]
+}

package/bin/lib/daemon-operations.js

@@ -0,0 +1,190 @@
+import { existsSync, rmSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+
+import { decorateEndpoints, formatEndpointLines, statusPayload } from "./daemon-status.js"
+
+export function parseEngineLine(stdout) {
+  const line = stdout.trim().split("\n").filter(Boolean).pop()
+  if (line === undefined) return undefined
+  try {
+    return JSON.parse(line)
+  } catch {
+    return undefined
+  }
+}
+
+export function readAllEndpoints(engine, agentDir, env) {
+  const result = engine.run(["host", "status", "--json", "--all", "--include-workers"], {
+    env: { ...env, OMO_AGENT_DIR: agentDir },
+  })
+  const parsed = parseEngineLine(result.stdout ?? "")
+  if (result.exitCode === 2 || !Array.isArray(parsed?.endpoints)) return { kind: "legacy", result }
+  const endpoints = decorateEndpoints(parsed.endpoints, agentDir)
+  return { kind: "all", result, endpoints }
+}
+
+export function runStatus({ engine, agentDir, env, json, stdout, stderr, _test }) {
+  const all = readAllEndpoints(engine, agentDir, env)
+  if (all.kind === "legacy") return { legacy: true, result: all.result }
+  if (all.result.stderr) stderr.write(all.result.stderr)
+  _test?.afterRead?.({ agentDir, endpoints: all.endpoints })
+  if (all.endpoints.length === 0 && all.result.exitCode !== 0) {
+    if (json) stdout.write(`${JSON.stringify(statusPayload([]))}\n`)
+    else stdout.write("daemon: not running\n")
+    return { legacy: false, exitCode: all.result.exitCode, endpoints: [] }
+  }
+  if (json) stdout.write(`${JSON.stringify(statusPayload(all.endpoints))}\n`)
+  else stdout.write(`${formatEndpointLines(all.endpoints).join("\n")}\n`)
+  return { legacy: false, exitCode: all.result.exitCode, endpoints: all.endpoints }
+}
+
+function liveEndpoints(endpoints) {
+  return endpoints.filter((endpoint) => endpoint.reachable && typeof endpoint.socket === "string")
+}
+
+function ownedEndpoints(endpoints) {
+  return endpoints.filter((endpoint) => {
+    if (typeof endpoint.socket !== "string") return false
+    return endpoint.reachable ||
+      (endpoint.generations ?? []).some((generation) => generation.alive) ||
+      (endpoint.claims_live ?? 0) > 0
+  })
+}
+
+function endpointCall(engine, args, agentDir, env) {
+  const result = engine.run(args, { env: { ...env, OMO_AGENT_DIR: agentDir } })
+  return { result, parsed: parseEngineLine(result.stdout ?? "") }
+}
+
+export function runGc({ engine, migration, agentDir, env, json, pruneStoreIndex, stdout, stderr }) {
+  const { result, parsed } = endpointCall(engine, ["host", "gc", "--json"], agentDir, env)
+  if (result.stderr) stderr.write(result.stderr)
+  const removed = Array.isArray(parsed?.removed) ? parsed.removed : []
+  const kept = Array.isArray(parsed?.kept) ? parsed.kept : []
+  const reapedMeta = []
+  for (const entry of removed) {
+    if (typeof entry.socket !== "string") continue
+    const meta = entry.socket.replace(/\.sock$/, ".meta.json")
+    if (!existsSync(meta)) continue
+    rmSync(meta, { force: true })
+    reapedMeta.push(meta)
+  }
+  const prunedStores = pruneStoreIndex
+    ? migration.run({ operation: "prune-store-index", indexPath: join(agentDir, "rpc", "task-stores.json") }).removed
+    : []
+  const payload = { removed, kept, reaped_meta: reapedMeta, pruned_stores: prunedStores }
+  if (json) stdout.write(`${JSON.stringify(payload)}\n`)
+  else stdout.write(`reaped: ${removed.length}\n`)
+  return result.exitCode
+}
+
+export function runHandoff({ engine, pluginRoot, agentDir, env, policy, config, stdout, stderr }) {
+  const all = readAllEndpoints(engine, agentDir, env)
+  if (all.kind === "legacy") {
+    const call = endpointCall(
+      engine,
+      buildEnsureArgs("handoff", undefined, pluginRoot, policy),
+      agentDir,
+      hostCommandEnvironment(env, agentDir, config),
+    )
+    if (call.result.stderr) stderr.write(call.result.stderr)
+    stdout.write(`daemon: ${call.parsed?.action ?? "handoff"}\n`)
+    return call.result.exitCode
+  }
+  let refused = false
+  const commandEnv = hostCommandEnvironment(env, agentDir, config)
+  for (const endpoint of liveEndpoints(all.endpoints)) {
+    const daemon = basename(endpoint.socket) === "rpc.sock"
+    const args = daemon
+      ? buildEnsureArgs("handoff", undefined, pluginRoot, policy)
+      : buildEnsureArgs("ensure", endpoint.socket, pluginRoot, policy)
+    const call = endpointCall(engine, args, agentDir, commandEnv)
+    if (call.result.stderr) stderr.write(call.result.stderr)
+    if (call.result.exitCode !== 0 || call.parsed?.action === "refuse") refused = true
+    stdout.write(`${endpoint.socket}: ${call.parsed?.action ?? "refuse"}\n`)
+  }
+  return refused ? 3 : 0
+}
+
+function buildEnsureArgs(command, socket, pluginRoot, policy) {
+  const args = ["host", command, "--json"]
+  if (socket !== undefined) args.push("--socket", socket)
+  args.push("--launch-spec", join(pluginRoot, "daemon-launch-spec.json"), "--policy", policy)
+  return args
+}
+
+export function hostCommandEnvironment(env, agentDir, config) {
+  const result = { ...env, OMO_AGENT_DIR: agentDir }
+  const idleExitMs = config?.task?.host_idle_exit_ms
+  if (typeof idleExitMs === "number" && Number.isFinite(idleExitMs) && idleExitMs > 0) {
+    result.SENPI_RPC_HOST_IDLE_EXIT_MS = String(Math.trunc(idleExitMs))
+  }
+  return result
+}
+
+export function runStopAll({ engine, agentDir, env, drain, wait, timeoutSeconds, stdout, stderr, now, pause }) {
+  const all = readAllEndpoints(engine, agentDir, env)
+  if (all.kind === "legacy") return undefined
+  let failed = false
+  for (const endpoint of ownedEndpoints(all.endpoints)) {
+    const args = ["host", "stop", "--json", "--socket", endpoint.socket]
+    if (drain) args.push("--drain")
+    const call = endpointCall(engine, args, agentDir, env)
+    if (call.result.stderr) stderr.write(call.result.stderr)
+    if (!wait) {
+      if (call.result.exitCode !== 0) failed = true
+      stdout.write(`${endpoint.socket}: requested (not awaited)\n`)
+      continue
+    }
+    const action = call.parsed?.action
+    const refusal = action === "refuse" ? call.parsed?.reason : action
+    const liveAtRequest = (endpoint.generations ?? []).some((generation) => generation.alive)
+    const claimsAtRequest = (endpoint.claims_live ?? 0) > 0
+    const ownedAtRequest = liveAtRequest || claimsAtRequest
+    if (
+      call.result.exitCode !== 0 &&
+      !(ownedAtRequest && (refusal === "drain_unsupported" || refusal === "unknown_owner"))
+    ) {
+      if (!ownedAtRequest) {
+        stdout.write(`${endpoint.socket}: already drained\n`)
+        continue
+      }
+      failed = true
+      stdout.write(`${endpoint.socket}: refused\n`)
+      continue
+    }
+    const result = waitForEndpoint(engine, endpoint.socket, agentDir, env, timeoutSeconds, now, pause)
+    if (result.done) stdout.write(`${endpoint.socket}: drained (${result.polls} polls)\n`)
+    else {
+      failed = true
+      stdout.write(`${endpoint.socket}: TIMEOUT: still live (${result.summary})\n`)
+    }
+  }
+  return failed ? 3 : 0
+}
+
+function waitForEndpoint(engine, socket, agentDir, env, timeoutSeconds, now, pause) {
+  const deadline = now() + timeoutSeconds * 1_000
+  let polls = 0
+  let latest
+  while (now() <= deadline) {
+    const call = endpointCall(engine, ["host", "status", "--json", "--socket", socket, "--include-workers"], agentDir, env)
+    latest = call.parsed
+    polls += 1
+    const alive = (latest?.generations ?? []).some((generation) => generation.alive)
+    if (!alive && (latest?.claims_live ?? 0) === 0) return { done: true, polls }
+    pause(250)
+  }
+  const pid = latest?.pid ?? "?"
+  const sessions = latest?.sessions?.total ?? 0
+  const claims = latest?.claims_live ?? 0
+  return { done: false, polls, summary: `pid ${pid}, ${sessions} sessions, ${claims} claims` }
+}
+
+export function parseStoreArgs(args) {
+  const stores = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--store" && args[index + 1] !== undefined) stores.push(resolve(args[index + 1]))
+  }
+  return stores
+}

package/bin/lib/daemon-rollback.js

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+
+import { parseEngineLine, readAllEndpoints } from "./daemon-operations.js"
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+function sidecarRoots(agentDir) {
+  const alt = createHash("sha256").update(agentDir, "utf8").digest("hex").slice(0, 8)
+  return [join(agentDir, "rpc", "shards"), `/tmp/omo-rpc-${alt}`]
+}
+
+function sidecars(agentDir) {
+  const rows = []
+  for (const root of sidecarRoots(agentDir)) {
+    let names
+    try {
+      names = readdirSync(root)
+    } catch {
+      continue
+    }
+    for (const name of names.filter((entry) => entry.endsWith(".meta.json")).toSorted()) {
+      const path = join(root, name)
+      const document = readJson(path)
+      if (document !== undefined) rows.push({ path, document })
+    }
+  }
+  return rows
+}
+
+function indexStores(agentDir) {
+  const path = join(agentDir, "rpc", "task-stores.json")
+  if (!existsSync(path)) return { present: false, stores: [] }
+  const document = readJson(path)
+  if (document?.version !== 1 || document.stores === null || typeof document.stores !== "object") {
+    return { present: false, stores: [] }
+  }
+  return { present: true, stores: Object.keys(document.stores).map((store) => resolve(store)) }
+}
+
+function collectStores(agentDir, explicitStores) {
+  const index = indexStores(agentDir)
+  const metadata = sidecars(agentDir)
+  const fromSidecars = metadata.flatMap(({ document }) => Array.isArray(document.stores) ? document.stores : [])
+  const stores = [
+    ...new Set([...index.stores, ...fromSidecars, ...explicitStores].map((store) => resolve(store))),
+  ].toSorted()
+  return {
+    index,
+    metadata,
+    fromSidecars: [...new Set(fromSidecars.map((store) => resolve(store)))],
+    stores,
+  }
+}
+
+function statusForSocket(engine, socket, agentDir, env) {
+  const result = engine.run(
+    ["host", "status", "--json", "--socket", socket, "--include-workers"],
+    { env: { ...env, OMO_AGENT_DIR: agentDir } },
+  )
+  const parsed = parseEngineLine(result.stdout ?? "")
+  if (
+    parsed === undefined ||
+    !Array.isArray(parsed.generations) ||
+    typeof parsed.claims_live !== "number"
+  ) {
+    return { readable: false }
+  }
+  return { readable: true, report: parsed }
+}
+
+export function runRollbackPrepare({
+  engine,
+  migration,
+  agentDir,
+  env,
+  explicitStores,
+  allowMissingIndex,
+  dryRun,
+  json,
+  stdout,
+  stderr,
+}) {
+  const discovered = collectStores(agentDir, explicitStores)
+  const endpointSweep = readAllEndpoints(engine, agentDir, env)
+  const endpointEvidence = endpointSweep.kind === "all" && endpointSweep.endpoints.some((endpoint) => {
+    if (typeof endpoint.socket !== "string") return true
+    return basename(endpoint.socket) !== "rpc.sock"
+  })
+  if (
+    !discovered.index.present &&
+    (discovered.metadata.length > 0 || endpointEvidence) &&
+    !allowMissingIndex &&
+    explicitStores.length === 0
+  ) {
+    stderr.write("store index missing: pass --store <dir> for every project that ran task children, or --allow-missing-index\n")
+    return 3
+  }
+
+  const missing = discovered.stores.filter((store) => !existsSync(store))
+  const present = discovered.stores.filter((store) => existsSync(store))
+  const plans = present.map((storeDir) => migration.run({ storeDir, to: join(agentDir, "rpc", "rpc.sock"), planOnly: true }))
+  const sockets = [...new Set(plans.flatMap((plan) => plan.sockets))].toSorted()
+  const deadEndpoints = []
+  for (const socket of sockets) {
+    const statusResult = statusForSocket(engine, socket, agentDir, env)
+    if (!statusResult.readable) {
+      stderr.write(`rollback refused: endpoint status unreadable ${socket}\n`)
+      return 3
+    }
+    const status = statusResult.report
+    const alive = (status?.generations ?? []).some((generation) => generation.alive)
+    if (alive || (status?.claims_live ?? 0) > 0) {
+      stderr.write(`rollback refused: endpoint still live ${socket}\n`)
+      return 3
+    }
+    deadEndpoints.push(socket)
+  }
+
+  const results = present.map((storeDir) => migration.run({
+    storeDir,
+    to: join(agentDir, "rpc", "rpc.sock"),
+    deadEndpoints,
+    dryRun,
+  }))
+  const storesWithoutMap = discovered.metadata
+    .filter(({ document }) => !Array.isArray(document.stores))
+    .map(({ document, path }) => document.socket ?? basename(path))
+  const payload = {
+    dry_run: dryRun,
+    stores: results,
+    coverage: {
+      discovered: discovered.stores.length,
+      from_index: discovered.index.stores.length,
+      from_sidecars: discovered.fromSidecars.length,
+      from_store: explicitStores.length,
+      missing,
+      endpoints_without_store_map: storesWithoutMap,
+    },
+  }
+  if (json) stdout.write(`${JSON.stringify(payload)}\n`)
+  else {
+    for (const result of results) {
+      stdout.write(`${result.store_dir}: migrated: ${dryRun ? result.migrate : result.migrated}, skipped: ${result.skipped}\n`)
+    }
+    stdout.write(
+      `stores: ${payload.coverage.discovered} discovered (${payload.coverage.from_sidecars} from sidecars, ${payload.coverage.from_store} from --store), ${missing.length} missing, endpoints without a store map: ${storesWithoutMap.join(", ") || "none"}\n`,
+    )
+  }
+  return 0
+}

package/bin/lib/daemon-status.js

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+
+function readJson(path) {
+  if (!existsSync(path)) return undefined
+  try {
+    return JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+function sidecarPath(endpoint, agentDir) {
+  if (endpoint.shard === null || endpoint.shard === undefined) return undefined
+  if (typeof endpoint.socket === "string") {
+    return join(dirname(endpoint.socket), `${endpoint.shard.kind}-${endpoint.shard.key}.meta.json`)
+  }
+  return join(agentDir, "rpc", "shards", `${endpoint.shard.kind}-${endpoint.shard.key}.meta.json`)
+}
+
+export function decorateEndpoints(endpoints, agentDir) {
+  return endpoints.map((endpoint) => {
+    const path = sidecarPath(endpoint, agentDir)
+    const owner = path === undefined ? undefined : readJson(path)
+    return owner === undefined ? endpoint : { ...endpoint, owner }
+  })
+}
+
+export function aggregateEndpoints(endpoints) {
+  const live = endpoints.filter((endpoint) => endpoint.reachable)
+  return {
+    live: live.length,
+    shards: live.filter((endpoint) => endpoint.shard?.kind === "p").length,
+    threads: live.filter((endpoint) => endpoint.shard?.kind === "i").length,
+    sessions: live.reduce((total, endpoint) => total + (endpoint.sessions?.total ?? 0), 0),
+    rss_mb: live.reduce((total, endpoint) => total + (endpoint.rss_mb ?? 0), 0),
+    host_rss_mb: live.reduce((total, endpoint) => total + (endpoint.host_rss_mb ?? 0), 0),
+    crashes: endpoints.reduce((total, endpoint) => total + (endpoint.crashes ?? 0), 0),
+  }
+}
+
+function endpointKind(endpoint) {
+  if (endpoint.shard?.kind === "p") return "shard"
+  if (endpoint.shard?.kind === "i") return "thread"
+  if (typeof endpoint.socket === "string" && basename(endpoint.socket) === "rpc.sock") return "daemon"
+  return "endpoint"
+}
+
+function endpointName(endpoint) {
+  const kind = endpointKind(endpoint)
+  if (kind === "daemon") return "daemon"
+  if (kind === "shard") {
+    const owner = endpoint.owner?.owner_session_id
+    const file = endpoint.owner?.owner_session_file
+    const suffix = [owner === undefined ? undefined : `parent ${owner.slice(0, 8)}`, file === undefined ? undefined : basename(file)]
+      .filter(Boolean)
+      .join(", ")
+    return `shard p-${endpoint.shard.key}${suffix === "" ? "" : ` (${suffix})`}`
+  }
+  if (kind === "thread") {
+    const owner = endpoint.owner?.owner_session_id
+    return `thread i-${endpoint.shard.key}${owner === undefined ? "" : ` (thread ${owner.slice(0, 8)})`}`
+  }
+  return `endpoint ${typeof endpoint.socket === "string" ? basename(endpoint.socket) : basename(endpoint.dir ?? "unknown")}`
+}
+
+function metric(value) {
+  return value === null || value === undefined ? "?" : String(value)
+}
+
+function runningDetails(endpoint, includeGeneration = true) {
+  const parts = [
+    `running pid ${metric(endpoint.pid)}`,
+    includeGeneration && endpoint.generation !== null && endpoint.generation !== undefined
+      ? `gen ${endpoint.generation}`
+      : undefined,
+    endpoint.engineVersion === null || endpoint.engineVersion === undefined ? undefined : `engine ${endpoint.engineVersion}`,
+    `${endpoint.sessions?.total ?? 0} session(s)`,
+    `rss ${metric(endpoint.rss_mb)} MB (host ${metric(endpoint.host_rss_mb)} MB)`,
+    `fds ${metric(endpoint.open_fds)}`,
+    `crashes ${endpoint.crashes ?? 0}`,
+  ].filter(Boolean)
+  return parts.join(" · ")
+}
+
+function generationLine(generation, endpoint) {
+  const state = generation.current ? "current" : "draining"
+  const sessions = generation.sessions ?? endpoint.sessions?.total ?? 0
+  return `  gen ${generation.generation} (${state}) pid ${metric(generation.pid)} · engine ${generation.engineVersion ?? "?"} · ${sessions} session(s) · rss ${metric(generation.rss_mb)} MB (host ${metric(generation.host_rss_mb)} MB)`
+}
+
+export function formatEndpointLines(endpoints) {
+  const lines = []
+  for (const endpoint of endpoints) {
+    const name = endpointName(endpoint)
+    if (!endpoint.reachable) {
+      lines.push(`${name}: not running (retained state kept; run omo daemon gc)`)
+      continue
+    }
+    lines.push(`${name}: ${runningDetails(endpoint, endpointKind(endpoint) !== "daemon")}`)
+    if ((endpoint.generations?.length ?? 0) > 1) {
+      for (const generation of endpoint.generations) lines.push(generationLine(generation, endpoint))
+    }
+  }
+  const aggregate = aggregateEndpoints(endpoints)
+  lines.push(
+    `hosts: ${aggregate.live} live (${aggregate.shards} shards, ${aggregate.threads} threads) · ${aggregate.sessions} session(s) · rss ${aggregate.rss_mb} MB (host ${aggregate.host_rss_mb} MB) · crashes ${aggregate.crashes} (recorded, newest 50 per endpoint)`,
+  )
+  return lines
+}
+
+export function formatDoctorLines(endpoints) {
+  return formatEndpointLines(endpoints).map((line) => {
+    const prefix = line.startsWith("hosts:")
+      ? "INFO Hosts:"
+      : line.includes(": not running")
+        ? "WARN "
+        : line.startsWith("  gen ")
+          ? "INFO "
+          : "INFO "
+    if (line.startsWith("hosts:")) return `${prefix}${line.slice("hosts:".length)}`
+    return `${prefix}${line[0]?.toUpperCase() ?? ""}${line.slice(1)}`
+  })
+}
+
+export function statusPayload(endpoints) {
+  return { endpoints, aggregate: aggregateEndpoints(endpoints) }
+}