omo-ai 5.0.0-0.beta.9 → 5.0.0

package/bin/lib/auth-store.js

@@ -0,0 +1,57 @@
+/**
+ * Read and write the engine's `<agentDir>/auth.json`: every setup stage that imports a key goes
+ * through here, so they all escape, back up and write it the same way.
+ */
+
+import { chmodSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+// opencode keeps a pasted key verbatim and never interprets it, but the engine resolves every stored
+// key as a config value: a leading `!` runs a shell command and `$NAME` / `${NAME}` interpolate the
+// environment. `$$` and `$!` are the engine's literal escapes, so the engine reads back the exact
+// bytes opencode held.
+export function literalConfigValue(value) {
+  return value.replace(/[$!]/g, "$$$&")
+}
+
+export function readAuthStore(path) {
+  if (!existsSync(path)) return { entries: {}, bytes: undefined }
+  const bytes = readFileSync(path, "utf8")
+  try {
+    const entries = JSON.parse(bytes)
+    if (entries === null || typeof entries !== "object" || Array.isArray(entries)) throw new Error("expected object")
+    return { entries, bytes }
+  } catch {
+    return { malformed: true, bytes }
+  }
+}
+
+export function timestamp() {
+  return new Date().toISOString().replace(/[-:]/g, "")
+}
+
+// The credential and custom-provider stages of one run can both rewrite auth.json within the same
+// millisecond. The first backup holds the older bytes, so a later one never replaces it.
+function backup(path) {
+  try {
+    copyFileSync(path, `${path}.bak-${timestamp()}`, constants.COPYFILE_EXCL)
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error
+  }
+}
+
+export function writeAuthStore(path, current, additions) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  if (current.bytes !== undefined) backup(path)
+  const next = { ...current.entries }
+  for (const item of additions) next[item.provider] = { type: "api_key", key: item.key }
+  const temporary = `${path}.tmp-${process.pid}`
+  try {
+    writeFileSync(temporary, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 })
+    chmodSync(temporary, 0o600)
+    renameSync(temporary, path)
+    chmodSync(path, 0o600)
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary)
+  }
+}

package/bin/lib/bun-bin-shim.js

@@ -0,0 +1,128 @@
+import { chmodSync, lstatSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs"
+import { homedir as osHomedir } from "node:os"
+import { join } from "node:path"
+import { bunRoot, findBunBinary, isUnderBunGlobalTree } from "./bun-runtime.js"
+
+// Bumping this rewrites every generated shim on its next node boot; the value is embedded so a
+// stale shim is recognizable by content comparison alone.
+const SHIM_VERSION = 1
+const SHIM_MARKER = "omo-ai bun launcher shim"
+
+// The two bins a POSIX bun-global install exposes for the same launcher. `bun add -g` links the
+// package bin into BOTH, and a bun layout that puts the global node_modules/.bin on PATH first
+// makes the second one the entry a typed `omo` actually reaches - so repairing only the first
+// leaves those machines paying for a node boot on every launch. Each entry is judged on its own.
+const BIN_ENTRIES = [
+  { label: "bin", segments: ["bin", "omo"] },
+  { label: "node-modules-bin", segments: ["install", "global", "node_modules", ".bin", "omo"] },
+]
+
+function quoteForShell(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+/**
+ * The wrapper a bun-global install deserves: a two-branch sh script that execs bun on the real
+ * entrypoint so the launch never pays for a node boot. Both fallbacks land on the entrypoint's
+ * own `#!/usr/bin/env node` shebang, which is byte-identical to what the stock symlink did:
+ *   - OMO_RUNTIME=node asks for node end to end, so bun is skipped on purpose;
+ *   - a bun that moved or vanished falls back to the node path, and the next node boot rewrites
+ *     the shim with the freshly discovered bun path.
+ */
+export function bunBinShimScript(entryPath, bunPath) {
+  return [
+    "#!/bin/sh",
+    `# ${SHIM_MARKER} v${SHIM_VERSION} - generated by omo-ai; safe to delete, the next launch recreates it`,
+    `# entry: ${entryPath}`,
+    `if [ "$OMO_RUNTIME" != "node" ] && [ -x ${quoteForShell(bunPath)} ]; then exec ${quoteForShell(bunPath)} ${quoteForShell(entryPath)} "$@"; fi`,
+    `exec ${quoteForShell(entryPath)} "$@"`,
+    "",
+  ].join("\n")
+}
+
+/**
+ * Brings ONE bin entry to the shim, or explains why it was left as it was. Only bun's own link to
+ * THIS install, or a file already carrying the marker, is ever replaced; anything else - a link
+ * into another install, a hand-written file, a directory, a socket - is not ours to touch.
+ * Returns the labelled action; the caller owns the try/catch, so a broken entry cannot take the
+ * other one down with it.
+ */
+function applyShim(binPath, script, io) {
+  let stats
+  try {
+    stats = io.lstat(binPath)
+  } catch {
+    return "absent-bin"
+  }
+  if (stats.isSymbolicLink()) {
+    if (io.realpath(binPath) !== io.scriptPath) return "foreign-link"
+  } else if (stats.isFile()) {
+    const current = io.readFile(binPath, "utf8")
+    if (current === script) return "current"
+    if (!current.includes(SHIM_MARKER)) return "foreign-file"
+  } else {
+    return "foreign-entry"
+  }
+
+  const temporary = `${binPath}.${io.pid}.tmp`
+  io.write(temporary, script, { mode: 0o755 })
+  // writeFileSync applies umask, and a 077 umask would ship a non-executable shim; chmod is exact.
+  io.chmod(temporary, 0o755)
+  io.rename(temporary, binPath)
+  return "repaired"
+}
+
+function repairBinEntry(entry, root, script, io) {
+  const path = join(root, ...entry.segments)
+  try {
+    return { label: entry.label, path, action: applyShim(path, script, io), error: undefined }
+  } catch (error) {
+    if (io.env.OMO_DEBUG) io.warn(`omo: bun launcher shim left untouched at ${path}: ${error.message}`)
+    return { label: entry.label, path, action: "failed", error: error.message }
+  }
+}
+
+/**
+ * Keeps the user-facing bins of a POSIX bun-global install pointed at bun without a node boot.
+ * Called on every launcher start; it must stay cheap on the happy path (one lstat per entry plus,
+ * when an entry is already a regular file, reading a few hundred bytes) and must never break a
+ * launch: every failure path - foreign file, missing bin, unwritable bin dir - returns quietly,
+ * one entry's failure never stops the other from being repaired, and only OMO_DEBUG narrates.
+ * Repairs run under node only, because a bun process either arrived through a shim already or has
+ * no node boot to save.
+ *
+ * The answer is per entry (`entries`), with the primary `<bunRoot>/bin/omo` entry's action and
+ * error mirrored at the top level for callers that only ever cared about that one.
+ */
+export function ensureBunBinShim(input) {
+  const env = input.env ?? process.env
+  const homedir = input.homedir ?? osHomedir
+  const platform = input.platform ?? process.platform
+  const versions = input.versions ?? process.versions
+  const io = {
+    env,
+    scriptPath: input.scriptPath,
+    lstat: input.lstat ?? lstatSync,
+    realpath: input.realpath ?? realpathSync,
+    readFile: input.readFile ?? readFileSync,
+    write: input.write ?? writeFileSync,
+    rename: input.rename ?? renameSync,
+    chmod: input.chmod ?? chmodSync,
+    pid: input.pid ?? process.pid,
+    warn: input.warn ?? ((message) => console.error(message)),
+  }
+
+  if (platform !== "darwin" && platform !== "linux") return { action: "skipped-platform", error: undefined, entries: [] }
+  if (versions.bun) return { action: "skipped-runtime", error: undefined, entries: [] }
+  if (!isUnderBunGlobalTree(input.scriptPath, { env, homedir, platform, realpath: io.realpath })) {
+    return { action: "skipped-install", error: undefined, entries: [] }
+  }
+  const bunPath = findBunBinary({ env, homedir, platform, exists: input.exists, realpath: io.realpath })
+  if (!bunPath) return { action: "skipped-no-bun", error: undefined, entries: [] }
+
+  const root = bunRoot(env, homedir, platform)
+  const script = bunBinShimScript(input.scriptPath, bunPath)
+  const entries = BIN_ENTRIES.map((entry) => repairBinEntry(entry, root, script, io))
+  const primary = entries[0]
+  return { action: primary.action, error: primary.error, entries }
+}

package/bin/lib/bun-runtime.js

@@ -0,0 +1,227 @@
+import { execFile as nodeExecFile } from "node:child_process"
+import { existsSync, realpathSync } from "node:fs"
+import { homedir as osHomedir } from "node:os"
+import { posix, win32 } from "node:path"
+import { propagateResult, runChild } from "./child-process.js"
+
+// A bun global install lives under <BUN_ROOT>/install/global/, and `bun add -g` links the launcher
+// into <BUN_ROOT>/bin. The link TARGET is what identifies the install, so every comparison below
+// runs on a real path.
+const GLOBAL_TREE_MARKER = "/install/global/"
+
+// The oldest bun the engine is known to run on: node:sqlite parity and the worker_threads compat the
+// JS eval kernel relies on both landed in 1.4. A bun found lying around on an npm-installed machine
+// is only trusted from here up; anything older leaves the launch on node, which always works.
+export const BUN_MIN_VERSION = "1.4.0"
+
+// `bun --version` answers in a few milliseconds; a probe that has not answered by now is a broken
+// binary, and the launch simply proceeds on node.
+const VERSION_PROBE_TIMEOUT_MS = 3_000
+
+// Both sides of the tree comparison are reduced to one spelling: backslashes become forward
+// slashes so Windows paths match, and repeated separators collapse because BUN_INSTALL is
+// user-supplied and a value like `/tmp//bunroot` would otherwise never prefix-match a real path.
+function normalize(path) {
+  return path.replaceAll("\\", "/").replaceAll(/\/{2,}/g, "/")
+}
+
+function pathApi(platform) {
+  return platform === "win32" ? win32 : posix
+}
+
+export function bunRoot(env, homedir, platform) {
+  return env.BUN_INSTALL ? env.BUN_INSTALL : pathApi(platform).join(homedir(), ".bun")
+}
+
+/**
+ * Node resolves the main module to its real path, so the script side of the comparison is already
+ * canonical. The root has to be canonicalized too or the two sides can name the same directory in
+ * different spellings - `/tmp` against `/private/tmp` on macOS, or any symlinked home - and a real
+ * bun install would silently fail to be recognized. A root that does not exist is used verbatim.
+ */
+function canonicalRoot(env, homedir, platform, realpath) {
+  const root = bunRoot(env, homedir, platform)
+  try {
+    return realpath(root)
+  } catch {
+    return root
+  }
+}
+
+function binaryName(platform) {
+  return platform === "win32" ? "bun.exe" : "bun"
+}
+
+function pathDelimiter(platform) {
+  return platform === "win32" ? ";" : ":"
+}
+
+/**
+ * True when the executed script belongs to a Bun global install. The caller passes the script's
+ * REAL path: the launcher is reached through a symlink under the bun root's bin directory, and
+ * that link lives outside the global tree, so the link path itself never matches.
+ */
+export function isUnderBunGlobalTree(scriptRealPath, options = {}) {
+  const env = options.env ?? process.env
+  const homedir = options.homedir ?? osHomedir
+  const platform = options.platform ?? process.platform
+  const realpath = options.realpath ?? realpathSync
+  const root = normalize(canonicalRoot(env, homedir, platform, realpath)).replace(/\/+$/, "")
+  return normalize(scriptRealPath).startsWith(`${root}${GLOBAL_TREE_MARKER}`)
+}
+
+// Only real executables qualify on win32. npm installs bun as a `bun.cmd` shim next to the real
+// binary, and Node refuses to spawn .cmd/.bat files without a shell (spawn EINVAL, CVE-2024-27980),
+// so a shim can neither answer the version probe nor host the re-exec. PATHEXT still decides which
+// executable spellings exist; batch-file spellings are dropped. Lower-case first, so the path
+// returned matches how the file is spelled on disk.
+const WIN32_EXECUTABLE_EXTENSIONS = new Set([".exe", ".com"])
+
+function pathExtensions(env, platform) {
+  if (platform !== "win32") return [""]
+  const configured = env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD"
+  const spellings = []
+  for (const raw of configured.split(";")) {
+    const extension = raw.trim()
+    if (!WIN32_EXECUTABLE_EXTENSIONS.has(extension.toLowerCase())) continue
+    for (const spelling of [extension.toLowerCase(), extension]) {
+      if (!spellings.includes(spelling)) spellings.push(spelling)
+    }
+  }
+  return spellings.length > 0 ? spellings : [...WIN32_EXECUTABLE_EXTENSIONS]
+}
+
+/**
+ * Locates the bun binary this machine would run. Absence is a normal answer - a machine without bun
+ * simply keeps the launcher on node.
+ */
+export function findBunBinary(options = {}) {
+  const env = options.env ?? process.env
+  const homedir = options.homedir ?? osHomedir
+  const platform = options.platform ?? process.platform
+  const exists = options.exists ?? existsSync
+  const paths = pathApi(platform)
+  const name = binaryName(platform)
+
+  const candidates = [
+    paths.join(bunRoot(env, homedir, platform), "bin", name),
+    paths.join(homedir(), ".bun", "bin", name),
+  ]
+  for (const candidate of candidates) {
+    if (exists(candidate)) return candidate
+  }
+
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path")
+  const entries = pathKey ? (env[pathKey] ?? "").split(pathDelimiter(platform)).filter(Boolean) : []
+  for (const entry of entries) {
+    for (const extension of pathExtensions(env, platform)) {
+      // On win32 the name already carries .exe; PATHEXT decides which other spellings are runnable.
+      const candidate = paths.join(entry, platform === "win32" ? `bun${extension}` : name)
+      if (exists(candidate)) return candidate
+    }
+  }
+  return undefined
+}
+
+/** True when a `bun --version` answer is at least BUN_MIN_VERSION; missing or unparseable never is. */
+export function bunVersionSatisfies(version) {
+  if (typeof version !== "string") return false
+  const match = /^(\d+)\.(\d+)/.exec(version)
+  if (match === null) return false
+  const [floorMajor, floorMinor] = BUN_MIN_VERSION.split(".").map(Number)
+  const major = Number(match[1])
+  const minor = Number(match[2])
+  return major > floorMajor || (major === floorMajor && minor >= floorMinor)
+}
+
+/**
+ * Asks a bun binary for its version. Every failure - a binary that cannot start, prints nothing, or
+ * hangs past the bounded timeout - resolves to undefined, which the decision reads as "not a bun we
+ * can trust". Asynchronous like every other spawn in this launcher: nothing here may block the
+ * event loop, so a signal arriving mid-probe is still handled.
+ */
+export function probeBunVersion(bunPath, options = {}) {
+  const execFile = options.execFile ?? nodeExecFile
+  const env = options.env ?? process.env
+  return new Promise((resolve) => {
+    try {
+      execFile(
+        bunPath,
+        ["--version"],
+        { encoding: "utf8", env, timeout: VERSION_PROBE_TIMEOUT_MS, windowsHide: true },
+        (error, stdout) => {
+          if (error) {
+            resolve(undefined)
+            return
+          }
+          const version = String(stdout).trim()
+          resolve(version === "" ? undefined : version)
+        },
+      )
+    } catch {
+      // Node throws synchronously for a batch file spawned without a shell (spawn EINVAL); that is
+      // "not a bun we can trust", never a launcher crash.
+      resolve(undefined)
+    }
+  })
+}
+
+/**
+ * The whole policy in one place, first match wins:
+ *   1. already on bun                  -> stay (the loop guard; without it a re-exec would recurse)
+ *   2. OMO_RUNTIME=node                -> stay (explicit user override beats detection)
+ *   3. no bun binary anywhere          -> stay (npm-only machines never notice this module)
+ *   4. OMO_RUNTIME=bun                 -> re-exec (explicit opt-in, no version floor)
+ *   5. bun global install              -> re-exec (the bun that installed omo is the bun to run it)
+ *   6. any other install, bun >= 1.4   -> re-exec (a machine that has bun runs omo on bun)
+ *   7. an older bun                    -> stay
+ *
+ * Rules 5 and 6 differ only in cost: a bun-global install already proved its bun, so it never pays
+ * for the version probe, while an npm, project-local or bunx install probes the discovered binary
+ * once per node boot before trusting it.
+ */
+export async function resolveBunReexec(input) {
+  const env = input.env ?? process.env
+  const versions = input.versions ?? process.versions
+  if (versions.bun) return { reexec: false }
+  const requested = env.OMO_RUNTIME
+  if (requested === "node") return { reexec: false }
+  const bunPath = findBunBinary(input)
+  if (!bunPath) return { reexec: false }
+  if (requested === "bun" || isUnderBunGlobalTree(input.scriptPath, input)) return { reexec: true, bunPath }
+  const probe = input.bunVersion ?? probeBunVersion
+  const version = await probe(bunPath, { env })
+  if (!bunVersionSatisfies(version)) return { reexec: false }
+  return { reexec: true, bunPath }
+}
+
+/**
+ * Runs the decision. Resolves true when bun took over the process, in which case the caller must
+ * return immediately. POSIX replaces the current image; unsupported or failed execve uses the
+ * asynchronous child path so signals still reach the engine and its exit status is propagated.
+ *
+ * Node's execArgv is deliberately dropped - node flags are not bun flags, and forwarding them
+ * would fail the very launch this re-exec is meant to make work.
+ */
+export async function maybeReexecUnderBun(input) {
+  const decision = await resolveBunReexec(input)
+  if (!decision.reexec) return false
+  const run = input.spawn ?? runChild
+  const propagate = input.propagate ?? propagateResult
+  const argv = input.argv ?? process.argv
+  const execve = input.execve === undefined ? process.execve : input.execve
+  if ((input.platform ?? process.platform) !== "win32" && typeof execve === "function") {
+    try {
+      execve(decision.bunPath, [decision.bunPath, input.scriptPath, ...argv.slice(2)], process.env)
+      return true
+    } catch {
+      // Keep the same inherited environment and signal forwarding if replacement fails.
+    }
+  }
+  const result = await run(decision.bunPath, [input.scriptPath, ...argv.slice(2)], {
+    stdio: "inherit",
+    windowsHide: true,
+  })
+  propagate(result)
+  return true
+}

package/bin/lib/category-coverage.js

@@ -0,0 +1,212 @@
+/**
+ * Which task categories the user's providers serve, for `omo doctor` and the `omo setup` summary.
+ *
+ * The model list is the pinned engine's own: its ModelRuntime, built the way the engine's
+ * `auth-check --no-refresh` builds it (read-only credentials, in-memory model cache, no network),
+ * so auth.json, models.json custom providers and provider env keys count exactly as a session
+ * counts them, and nothing is written. The classification is the spawn path's resolver, reached
+ * through the bundled `plugin/runtime/category-coverage/index.js` (category-coverage-entry.ts).
+ * Both are fail-open: any error yields no coverage, never a failed command.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { packageRoot, resolveSenpi } from "./package-paths.js"
+
+export const COVERAGE_RUNTIME = join("plugin", "runtime", "category-coverage", "index.js")
+
+async function loadEngine() {
+  const core = join(resolveSenpi().packageRoot, "dist", "core")
+  const load = (name) => import(pathToFileURL(join(core, name)).href)
+  const subscriptionDir = join("extensions", "builtin", "anthropic-subscription")
+  const [runtime, auth, store, settings, subscription, subscriptionSettings] = await Promise.all([
+    load("model-runtime.js"),
+    load("auth-storage.js"),
+    load("models-store.js"),
+    load("settings-manager.js"),
+    load(join(subscriptionDir, "index.js")),
+    load(join(subscriptionDir, "settings.js")),
+  ])
+  return {
+    ModelRuntime: runtime.ModelRuntime,
+    AuthStorage: auth.AuthStorage,
+    ReadOnlyAuthStorage: auth.ReadOnlyAuthStorage,
+    InMemoryCodingAgentModelsStore: store.InMemoryCodingAgentModelsStore,
+    SettingsManager: settings.SettingsManager,
+    registerAnthropicSubscription: subscription.registerAnthropicSubscriptionExtension,
+    loadAnthropicSubscriptionSettings: subscriptionSettings.loadAnthropicSubscriptionProviderSettings,
+  }
+}
+
+// anthropic-subscription is the one chain provider a builtin extension registers instead of the
+// catalog. Its registration carries its own availability check (stored accounts,
+// CLAUDE_CODE_OAUTH_TOKEN* env tokens, an opted-in ambient Claude login), so the provider config
+// is captured from the extension itself and registered on the runtime, as a session does. The
+// extension's commands and session hooks are not needed here and are dropped. Its settings are
+// read from the inspected agent dir (the extension's default reads the engine's own default dir).
+function extensionProviders(register) {
+  const providers = []
+  const capture = (name, config) => { providers.push([name, config]) }
+  register(new Proxy({}, { get: (_, key) => key === "registerProvider" ? capture : () => undefined }))
+  return providers
+}
+
+async function loadRuntime() {
+  return import(pathToFileURL(join(packageRoot, COVERAGE_RUNTIME)).href)
+}
+
+/**
+ * @typedef {{ provider: string, id: string }} EngineModel
+ * @typedef {{
+ *   agentDir: string,
+ *   authEntries?: Record<string, unknown>,
+ *   modelsDocument?: Record<string, unknown>,
+ *   cwd?: string,
+ *   loadEngine?: () => Promise<any>,
+ * }} EngineModelsInput
+ * @param {EngineModelsInput} input `authEntries` / `modelsDocument` stand in for auth.json /
+ *   models.json (a setup plan's post-import view); absent, the agent dir's files are read.
+ * @returns {Promise<EngineModel[]>}
+ */
+export async function engineAvailableModels(input) {
+  const engine = await (input.loadEngine ?? loadEngine)()
+  const credentials = input.authEntries === undefined
+    ? new engine.ReadOnlyAuthStorage(join(input.agentDir, "auth.json"))
+    : engine.AuthStorage.inMemory(input.authEntries)
+  const scratch = input.modelsDocument === undefined ? undefined : mkdtempSync(join(tmpdir(), "omo-coverage-"))
+  try {
+    const modelsPath = scratch === undefined ? join(input.agentDir, "models.json") : join(scratch, "models.json")
+    if (scratch !== undefined) writeFileSync(modelsPath, JSON.stringify(input.modelsDocument), { mode: 0o600 })
+    const runtime = await engine.ModelRuntime.create({
+      credentials,
+      modelsPath,
+      modelsStore: new engine.InMemoryCodingAgentModelsStore(),
+      allowModelNetwork: false,
+    })
+    const cwd = input.cwd ?? process.cwd()
+    const readSettings = () => engine.loadAnthropicSubscriptionSettings(engine.SettingsManager.create(cwd, input.agentDir))
+    for (const [name, config] of extensionProviders((pi) => engine.registerAnthropicSubscription(pi, { readSettings }))) {
+      await runtime.registerProvider(name, config, { refresh: false })
+    }
+    return (await runtime.getAvailable()).map((model) => ({ provider: model.provider, id: model.id }))
+  } finally {
+    if (scratch !== undefined) rmSync(scratch, { recursive: true, force: true })
+  }
+}
+
+/**
+ * @typedef {{ name: string, providers: string[] }} UnusableCategory
+ * @typedef {{ usable: string[], unusable: UnusableCategory[] }} CategoryCoverage
+ * @typedef {{
+ *   models: EngineModel[],
+ *   cwd: string,
+ *   env: Record<string, string | undefined>,
+ *   pinnedCategories?: string[],
+ *   loadRuntime?: () => Promise<any>,
+ * }} CoverageInput
+ * @param {CoverageInput} input
+ * @returns {Promise<CategoryCoverage>}
+ */
+export async function categoryCoverage(input) {
+  const runtime = await (input.loadRuntime ?? loadRuntime)()
+  return runtime.categoryCoverage({ models: input.models, cwd: input.cwd, env: input.env, pinnedCategories: input.pinnedCategories ?? [] })
+}
+
+function total(coverage) {
+  return coverage.usable.length + coverage.unusable.length
+}
+
+// The category-unavailable notice's wording (omo-senpi components/task/category-unavailable-warning.ts).
+function gapLine(gap) {
+  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.`
+  }
+  return `Category "${gap.name}" has no usable model: none of its fallback-chain providers are connected (${gap.providers.join(", ")}). Connect one with /login <provider>, or pin categories.${gap.name}.model in omo.json.`
+}
+
+/** @param {CategoryCoverage} coverage */
+export function formatDoctorCoverageLines(coverage) {
+  if (coverage.unusable.length === 0) return [`PASS task categories: all ${total(coverage)} usable with your connected providers`]
+  const usable = coverage.usable.length > 0 ? ` (${coverage.usable.join(", ")})` : ""
+  return [
+    `WARN task categories: ${coverage.usable.length} of ${total(coverage)} usable with your connected providers${usable}`,
+    ...coverage.unusable.map((gap) => `WARN ${gapLine(gap)}`),
+  ]
+}
+
+/** The setup summary's `categories` row parts. @param {CategoryCoverage} coverage */
+export function coverageSummaryParts(coverage) {
+  if (coverage.unusable.length === 0) return [`all ${total(coverage)} usable with these providers`]
+  const usable = coverage.usable.length > 0 ? ` (${coverage.usable.join(", ")})` : ""
+  return [`${coverage.usable.length} of ${total(coverage)} usable with these providers${usable}`, ...coverage.unusable.map(gapLine)]
+}
+
+/**
+ * @typedef {{
+ *   agentDir: string,
+ *   cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ *   loadEngine?: () => Promise<any>,
+ *   loadRuntime?: () => Promise<any>,
+ * }} DoctorCoverageOptions
+ * @param {DoctorCoverageOptions} options
+ * @returns {Promise<string[]>}
+ */
+export async function doctorCoverageLines(options) {
+  try {
+    // The runtime first: a payload without it fails fast, before the engine import.
+    const runtime = await (options.loadRuntime ?? loadRuntime)()
+    const cwd = options.cwd ?? process.cwd()
+    const models = await engineAvailableModels({ agentDir: options.agentDir, cwd, loadEngine: options.loadEngine })
+    const coverage = await categoryCoverage({ models, cwd, env: options.env ?? process.env, loadRuntime: async () => runtime })
+    return formatDoctorCoverageLines(coverage)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Coverage for what setup's plan leaves behind: auth.json with the keys the credential and
+ * custom-provider stages add, models.json with the providers they add, omo.json with the category
+ * pins the model-choice stage writes. Undefined when that view cannot be composed or computed.
+ *
+ * @typedef {{
+ *   agentDir: string,
+ *   home: string,
+ *   env: Record<string, string | undefined>,
+ *   plans: any,
+ *   cwd?: string,
+ *   loadEngine?: () => Promise<any>,
+ *   loadRuntime?: () => Promise<any>,
+ * }} SetupCoverageInput
+ * @param {SetupCoverageInput} input
+ * @returns {Promise<CategoryCoverage | undefined>}
+ */
+export async function setupCoverage(input) {
+  try {
+    const { credentials, providers, modelChoices } = input.plans
+    if (credentials.malformed || providers.models.malformed) return undefined
+    const runtime = await (input.loadRuntime ?? loadRuntime)()
+    const authEntries = { ...credentials.current.entries }
+    for (const item of [...credentials.result.additions, ...providers.result.keys]) authEntries[item.provider] ??= { type: "api_key", key: item.key }
+    const added = providers.result.added
+    const modelsDocument = added.length === 0 ? undefined : {
+      ...providers.models.document,
+      providers: { ...providers.models.document.providers, ...Object.fromEntries(added.map((provider) => [provider.id, provider.config])) },
+    }
+    const cwd = input.cwd ?? process.cwd()
+    const models = await engineAvailableModels({ agentDir: input.agentDir, authEntries, modelsDocument, cwd, loadEngine: input.loadEngine })
+    const pinnedCategories = modelChoices.items.filter((item) => item.kind === "categories" && item.state === "pending").map((item) => item.name)
+    return await categoryCoverage({
+      models,
+      cwd,
+      env: { ...input.env, HOME: input.home },
+      pinnedCategories,
+      loadRuntime: async () => runtime,
+    })
+  } catch {
+    return undefined
+  }
+}