@opencode-cockpit/shell 0.1.4 → 0.2.0

package/dist/agent/tools/shared.js

@@ -0,0 +1,94 @@
+import { RpcError } from "@opencode-cockpit/protocol";
+import { commandOf, matchByName } from "../../core/find.js";
+import { formatRead } from "../../core/format.js";
+
+/** What every tool shares: the client, name resolution, permission prompts and abort handling. */
+
+export function createToolKit(deps) {
+  const {
+    client
+  } = deps;
+  const peek = async (info, tail = 30) => {
+    const current = await client.call("shell.get", {
+      id: info.id
+    });
+    const page = await client.call("shell.read", {
+      id: info.id,
+      tail
+    });
+    return formatRead(current, page);
+  };
+  const sessionLabel = async (s, ctx) => {
+    const session = s.owner.session;
+    if (!session) return "started by the user";
+    if (session === ctx.sessionID) return "this session";
+    const title = await deps.sessionTitle?.(session).catch(() => undefined);
+    return title ? `session "${title}"` : `another session (${session})`;
+  };
+
+  /** Turns `{ id }` or `{ name }` into a shell id, or explains why it cannot. */
+  const resolve = async (args, ctx) => {
+    if (args.id) return {
+      id: args.id,
+      note: ""
+    };
+    if (!args.name) throw new Error("pass the shell's id or name");
+    const shells = await client.call("shell.list", {
+      owner: {
+        project: ctx.directory
+      }
+    });
+    const match = matchByName(shells, args.name);
+    const describe = async list => (await Promise.all(list.map(async s => `- ${s.id} "${s.title}" · ${s.status} · ${await sessionLabel(s, ctx)} · $ ${commandOf(s).slice(0, 80)}`))).join("\n");
+    if (match.kind === "found") {
+      const note = match.alsoMatched.length > 0 ? `(name "${args.name}" also matched ${match.alsoMatched.length} finished shell${match.alsoMatched.length === 1 ? "" : "s"}; using the running one, ${match.shell.id})\n` : "";
+      return {
+        id: match.shell.id,
+        note
+      };
+    }
+    if (match.kind === "ambiguous") {
+      throw new Error(`"${args.name}" matches several shells; pass one of these ids:\n${await describe(match.candidates)}`);
+    }
+    throw new Error(match.available.length === 0 ? `no shell matches "${args.name}": there are no shells in this project` : `no shell matches "${args.name}". Shells in this project:\n${await describe(match.available.slice(0, 15))}`);
+  };
+  return {
+    deps,
+    config: deps.config ?? {},
+    client,
+    peek,
+    sessionLabel,
+    resolve
+  };
+}
+export async function askPermission(ctx, command) {
+  const words = command.trim().split(/\s+/);
+  const prefix = words.slice(0, Math.min(2, words.length)).join(" ");
+  await ctx.ask({
+    permission: "bash",
+    patterns: [command],
+    always: [`${prefix} *`],
+    metadata: {
+      command,
+      description: "background shell"
+    }
+  });
+}
+
+/** Resolves undefined when the tool call is aborted; the daemon keeps running the shell. */
+export function abortable(ctx, promise) {
+  if (ctx.abort.aborted) return Promise.resolve(undefined);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => resolve(undefined);
+    ctx.abort.addEventListener("abort", onAbort, {
+      once: true
+    });
+    promise.then(v => {
+      ctx.abort.removeEventListener("abort", onAbort);
+      resolve(v);
+    }, err => {
+      ctx.abort.removeEventListener("abort", onAbort);
+      reject(err instanceof RpcError ? new Error(err.message) : err);
+    });
+  });
+}

package/dist/agent/tools/start.js

@@ -0,0 +1,140 @@
+import { tool } from "@opencode-ai/plugin";
+import { describeStatus, formatWait, header } from "../../core/format.js";
+import { abortable, askPermission } from "./shared.js";
+import { watchArgs } from "./watch-args.js";
+const START = `Start a command in a background terminal (PTY) that keeps running while you continue working.
+
+Use this instead of bash for anything long-running or interactive:
+- dev servers, watchers (tsc --watch, vitest), local APIs, databases, tunnels
+- builds or test suites that take more than ~30 seconds
+- REPLs and prompts that need input later (use shell_send)
+
+Do not append "&" or use nohup; the shell already runs in the background.
+
+Readiness: pass waitFor to block until the process is actually ready, for example
+waitFor={ port: 3000 } for a dev server or waitFor={ pattern: "compiled successfully" }.
+Without waitFor the call returns after the first moment of quiet with the initial output.
+
+You are notified automatically when the process exits (disable with notifyOnExit=false). Never
+sleep and poll: use shell_wait to block on a condition, and shell_read(after=cursor) for new output.`;
+const z = tool.schema;
+/**
+ * Every per-shell tool takes an id or a name. Declared per tool file because exported zod schemas
+ * cannot be named portably in generated declarations.
+ */
+const _TARGET = {
+  id: z.string().optional().describe("Shell id from shell_start or shell_list, e.g. sh_ab12cd34"),
+  name: z.string().optional().describe('Instead of id: the shell\'s name (the description it was started with), e.g. "DB Monitoring". Partial names and command text also match.')
+};
+export function shellStart(kit) {
+  const {
+    client,
+    config,
+    deps,
+    peek
+  } = kit;
+  return tool({
+    description: START,
+    args: {
+      command: z.string().min(1).describe("Command line, run by your shell (pipes, && and env vars work)"),
+      description: z.string().min(3).describe("What this shell is for, 3-8 words, e.g. 'Next.js dev server'"),
+      workdir: z.string().optional().describe("Working directory; defaults to the project directory"),
+      env: z.record(z.string(), z.string()).optional().describe("Extra environment variables"),
+      waitFor: z.object({
+        pattern: z.string().optional(),
+        port: z.number().int().min(1).max(65535).optional(),
+        idleSeconds: z.number().positive().optional(),
+        exit: z.boolean().optional(),
+        timeoutSeconds: z.number().positive().max(3600).default(120)
+      }).optional().describe("Block until ready. Same conditions as shell_wait."),
+      notifyOnExit: z.boolean().default(true).describe("Message you when the process exits"),
+      watch: z.union([z.boolean(), z.string()]).optional().describe('Watch this shell\'s health and message you only when it changes: true or "auto" picks a preset from the command, or name one (tsc, vitest, cargo…). For processes that never exit.'),
+      timeoutSeconds: z.number().int().positive().optional().describe("Stop the process after this long, busy or not. Good for bounded jobs and probes."),
+      idleTimeoutSeconds: z.number().int().positive().optional().describe("Stop the process after this much silence. Never use it for dev servers, which are idle when healthy."),
+      logFile: z.boolean().default(false).describe("Also write the clean log to a file, so old lines survive the in-memory buffer")
+    },
+    async execute(args, ctx) {
+      await askPermission(ctx, args.command);
+      // Config supplies what the call left out; an explicit argument always wins.
+      const defaults = config.defaults ?? {};
+      const logFile = args.logFile ?? defaults.logFile ?? false;
+      const notifyOnExit = args.notifyOnExit ?? defaults.notifyOnExit ?? true;
+      const watch = args.watch ?? defaults.watch ?? (config.watch?.auto ? "auto" : undefined);
+      const shell = deps.shellCommand(args.command);
+      const info = await client.call("shell.start", {
+        command: shell.command,
+        args: shell.args,
+        cwd: args.workdir || ctx.directory,
+        env: {
+          ...deps.env(),
+          ...args.env
+        },
+        title: args.description,
+        owner: {
+          project: ctx.directory,
+          session: ctx.sessionID,
+          instance: deps.instance
+        },
+        timeoutMs: seconds(args.timeoutSeconds ?? defaults.timeoutSeconds),
+        idleTimeoutMs: seconds(args.idleTimeoutSeconds ?? defaults.idleTimeoutSeconds),
+        logFile: logFile === true,
+        reuse: true
+      });
+      if (notifyOnExit === false) deps.quiet.add(info.id);else deps.quiet.delete(info.id);
+      ctx.metadata({
+        title: args.description,
+        metadata: {
+          shellId: info.id,
+          command: args.command
+        }
+      });
+      if (info.status === "failed") return `${header(info)}\n${describeStatus(info)}\n</shell>`;
+      const lines = [info.run > 1 ? `Restarted ${info.id} (run ${info.run}): same command as an earlier finished shell in this session. Earlier output is above line ${info.lines.last}.` : `Started ${info.id}: ${args.command}`];
+      if (watch) {
+        const preset = typeof watch === "string" ? watch : "auto";
+        await client.call("shell.watch", {
+          id: info.id,
+          ...watchArgs(preset, config)
+        }).then(watched => lines.push(`watching health (${watched.watch?.preset ?? "custom rule"}); changes will be messaged to you`)).catch(err => lines.push(`could not watch: ${err instanceof Error ? err.message : String(err)}`));
+      }
+      if (args.waitFor) {
+        const {
+          timeoutSeconds,
+          idleSeconds,
+          ...rest
+        } = args.waitFor;
+        const result = await abortable(ctx, client.call("shell.wait", {
+          id: info.id,
+          until: {
+            pattern: rest.pattern ?? undefined,
+            port: rest.port ?? undefined,
+            exit: rest.exit ?? undefined,
+            idleMs: idleSeconds ? Math.round(idleSeconds * 1000) : undefined
+          },
+          timeoutMs: Math.round((timeoutSeconds ?? 120) * 1000)
+        })).catch(err => {
+          lines.push(`wait failed: ${err instanceof Error ? err.message : String(err)} (the shell is still running)`);
+          return undefined;
+        });
+        if (result) lines.push(formatWait(result, timeoutSeconds ?? 120));
+      } else {
+        await abortable(ctx, client.call("shell.wait", {
+          id: info.id,
+          until: {
+            idleMs: 700,
+            exit: true
+          },
+          timeoutMs: 2500
+        }));
+      }
+      if (info.logFile) lines.push(`log file: ${info.logFile}`);
+      lines.push(await peek(info));
+      return lines.join("\n");
+    }
+  });
+}
+
+/** Milliseconds from an option in seconds, or undefined when unset. */
+function seconds(value) {
+  return value ? Math.round(value * 1000) : undefined;
+}

package/dist/agent/tools/stop.js

@@ -0,0 +1,42 @@
+import { tool } from "@opencode-ai/plugin";
+import { describeStatus } from "../../core/format.js";
+const z = tool.schema;
+/**
+ * Every per-shell tool takes an id or a name. Declared per tool file because exported zod schemas
+ * cannot be named portably in generated declarations.
+ */
+const TARGET = {
+  id: z.string().optional().describe("Shell id from shell_start or shell_list, e.g. sh_ab12cd34"),
+  name: z.string().optional().describe('Instead of id: the shell\'s name (the description it was started with), e.g. "DB Monitoring". Partial names and command text also match.')
+};
+export function shellStop(kit) {
+  const {
+    client,
+    deps,
+    resolve
+  } = kit;
+  return tool({
+    description: "Stop a background shell (SIGTERM to its whole process group, then SIGKILL after a grace period). Set remove=true to also forget it.",
+    args: {
+      ...TARGET,
+      remove: z.boolean().default(false),
+      force: z.boolean().default(false).describe("Send SIGKILL immediately")
+    },
+    async execute(args, ctx) {
+      const {
+        id,
+        note
+      } = await resolve(args, ctx);
+      deps.quiet.add(id);
+      const info = await client.call("shell.stop", {
+        id,
+        signal: args.force === true ? "SIGKILL" : "SIGTERM",
+        graceMs: 3000
+      });
+      if (args.remove === true) await client.call("shell.remove", {
+        id
+      });
+      return `${note}${info.id} ${describeStatus(info)}${args.remove === true ? " and removed" : ""}`;
+    }
+  });
+}

package/dist/agent/tools/wait.js

@@ -0,0 +1,79 @@
+import { tool } from "@opencode-ai/plugin";
+import { formatLines, formatWait, header } from "../../core/format.js";
+import { abortable } from "./shared.js";
+const WAIT = `Block until a condition holds in a background shell. This is the only correct way to wait:
+never sleep and poll.
+
+Conditions (combine freely; the first to happen wins, and the process exiting always ends the wait):
+- pattern: regex matched against output lines (also matches an unfinished prompt line)
+- port: something accepts TCP connections on this port
+- idleSeconds: no output for this long (often means waiting for input or finished a step)
+- exit: the process ends
+
+Pattern matching includes output produced before this call in the current run, so "wait until ready"
+succeeds immediately if it is already ready.`;
+const z = tool.schema;
+/**
+ * Every per-shell tool takes an id or a name. Declared per tool file because exported zod schemas
+ * cannot be named portably in generated declarations.
+ */
+const TARGET = {
+  id: z.string().optional().describe("Shell id from shell_start or shell_list, e.g. sh_ab12cd34"),
+  name: z.string().optional().describe('Instead of id: the shell\'s name (the description it was started with), e.g. "DB Monitoring". Partial names and command text also match.')
+};
+export function shellWait(kit) {
+  const {
+    client,
+    resolve
+  } = kit;
+  return tool({
+    description: WAIT,
+    args: {
+      ...TARGET,
+      pattern: z.string().optional(),
+      ignoreCase: z.boolean().optional(),
+      port: z.number().int().min(1).max(65535).optional(),
+      host: z.string().optional(),
+      idleSeconds: z.number().positive().optional(),
+      exit: z.boolean().optional(),
+      timeoutSeconds: z.number().positive().max(3600).default(300)
+    },
+    async execute(args, ctx) {
+      const {
+        id,
+        note
+      } = await resolve(args, ctx);
+      const start = await client.call("shell.get", {
+        id
+      });
+      const result = await abortable(ctx, client.call("shell.wait", {
+        id,
+        until: {
+          pattern: args.pattern ?? undefined,
+          ignoreCase: args.ignoreCase ?? undefined,
+          port: args.port ?? undefined,
+          host: args.host ?? undefined,
+          exit: args.exit ?? undefined,
+          idleMs: args.idleSeconds ? Math.round(args.idleSeconds * 1000) : undefined
+        },
+        timeoutMs: Math.round((args.timeoutSeconds ?? 300) * 1000)
+      }));
+      if (!result) return "wait cancelled";
+      const newLines = result.info.lines.last - start.lines.last;
+      const page = newLines > 80 ? await client.call("shell.read", {
+        id,
+        tail: 80
+      }) : await client.call("shell.read", {
+        id,
+        after: start.lines.last,
+        limit: 80
+      });
+      const recent = page.lines;
+      if (newLines > 80) recent.unshift({
+        n: start.lines.last,
+        text: `… ${newLines - 80} earlier lines omitted (shell_read after=${start.lines.last})`
+      });
+      return [note + formatWait(result, args.timeoutSeconds ?? 300), header(result.info), recent.length > 0 ? formatLines(recent) : "(no new output during the wait)", "</shell>", `cursor: ${result.info.lines.last}`].join("\n");
+    }
+  });
+}

package/dist/agent/tools/watch-args.js

@@ -0,0 +1,12 @@
+/**
+ * Turns a preset name into what `shell.watch` needs. A preset defined in config is sent as an
+ * explicit rule, so users can add tools or correct a built-in without touching the daemon.
+ */
+export function watchArgs(preset, config) {
+  const custom = config.watch?.presets?.[preset];
+  return custom ? {
+    rule: custom
+  } : {
+    preset
+  };
+}

package/dist/agent/tools/watch.js

@@ -0,0 +1,74 @@
+import { tool } from "@opencode-ai/plugin";
+import { watchArgs } from "./watch-args.js";
+const WATCH = `Keep an eye on a long-running shell and be told only when its health changes.
+
+For processes that never exit (tsc --watch, vitest --watch, dev servers) this replaces re-reading
+the log: you get one message when it breaks, and one when it is fixed, and nothing while it repeats
+the same result.
+
+- preset: a named rule ("auto" picks one from the command). Presets exist for tsc, vitest, jest,
+  eslint, biome, cargo, go, gradle, pytest, vite, next, docker-compose and more.
+- rule: your own patterns when no preset fits: done (a run ended), fail, ok, idleSeconds.
+- off: stop watching.
+
+A watched process that dies is reported as a failure, so a crashed dev server no longer goes
+unnoticed.`;
+const z = tool.schema;
+/**
+ * Every per-shell tool takes an id or a name. Declared per tool file because exported zod schemas
+ * cannot be named portably in generated declarations.
+ */
+const TARGET = {
+  id: z.string().optional().describe("Shell id from shell_start or shell_list, e.g. sh_ab12cd34"),
+  name: z.string().optional().describe('Instead of id: the shell\'s name (the description it was started with), e.g. "DB Monitoring". Partial names and command text also match.')
+};
+export function shellWatch(kit) {
+  const {
+    client,
+    config,
+    resolve
+  } = kit;
+  // Presets from config are worth advertising: the agent cannot guess a name it has never seen.
+  const named = Object.keys(config.watch?.presets ?? {});
+  return tool({
+    description: named.length > 0 ? `${WATCH}\n\nPresets from this project: ${named.join(", ")}.` : WATCH,
+    args: {
+      ...TARGET,
+      preset: z.string().optional().describe('Preset name, or "auto" to pick one from the command'),
+      rule: z.object({
+        done: z.string().optional().describe("A run finished, e.g. 'Found \\d+ errors'"),
+        fail: z.string().optional(),
+        ok: z.string().optional(),
+        ignoreCase: z.boolean().optional(),
+        idleSeconds: z.number().positive().optional().describe("Without `done`: treat this much silence as the end of a run")
+      }).optional().describe("Custom patterns; use when no preset fits"),
+      off: z.boolean().default(false).describe("Stop watching this shell")
+    },
+    async execute(args, ctx) {
+      const {
+        id,
+        note
+      } = await resolve(args, ctx);
+      if (args.off === true) {
+        const stopped = await client.call("shell.unwatch", {
+          id
+        });
+        return `${note}stopped watching ${stopped.id}`;
+      }
+      // A preset defined in config travels as an explicit rule; the daemon knows only the built-ins.
+      const chosen = args.preset ? watchArgs(args.preset, config) : {};
+      const info = await client.call("shell.watch", {
+        id,
+        preset: chosen.preset,
+        rule: args.rule ? {
+          done: args.rule.done ?? undefined,
+          fail: args.rule.fail ?? undefined,
+          ok: args.rule.ok ?? undefined,
+          ignoreCase: args.rule.ignoreCase ?? undefined,
+          idleSeconds: args.rule.idleSeconds ?? undefined
+        } : chosen.rule
+      });
+      return `${note}watching ${info.id} (${info.watch?.preset ?? "custom rule"}). You will be messaged when its health changes; no need to poll.`;
+    }
+  });
+}

package/dist/connect.js

@@ -0,0 +1,31 @@
+import { fileURLToPath } from "node:url";
+import { CockpitClient } from "@opencode-cockpit/client";
+import daemonPkg from "@opencode-cockpit/daemon/package.json" with { type: "json" };
+import { daemonBuildId } from "@opencode-cockpit/protocol";
+import pkg from "../package.json" with { type: "json" };
+
+/** Resolves the daemon entry shipped with this package. */
+export function daemonEntry() {
+  return fileURLToPath(import.meta.resolve("@opencode-cockpit/daemon/main"));
+}
+
+/**
+ * Inside OpenCode `process.execPath` is the OpenCode binary; the client starts the daemon with
+ * BUN_BE_BUN=1 so it runs on OpenCode's embedded Bun (ADR 0001). The expected build lets the
+ * client replace a daemon left running from older plugin code.
+ */
+export function createClient(name) {
+  const entry = daemonEntry();
+  return new CockpitClient({
+    client: {
+      name,
+      version: pkg.version,
+      pid: process.pid
+    },
+    spawn: {
+      entry,
+      execPath: process.execPath
+    },
+    expectedBuild: daemonBuildId(entry, daemonPkg.version)
+  });
+}

package/dist/core/config.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Settings, read from one file so they are written once instead of twice (OpenCode keeps agent and
+ * TUI plugins in separate configs). Precedence, lowest first:
+ *
+ *   ~/.config/opencode-cockpit/config.json  →  <project>/.cockpit.json  →  plugin-entry options
+ *
+ * Everything is optional, and an unreadable or invalid file is ignored rather than fatal: a typo in
+ * a config should never stop shells from working.
+ */
+
+export const CONFIG_FILE = "config.json";
+export const PROJECT_FILE = ".cockpit.json";
+export function globalConfigPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME ?? join(env.HOME ?? homedir(), ".config");
+  return join(base, "opencode-cockpit", CONFIG_FILE);
+}
+
+/** Reads and merges every source. `options` is the plugin entry's own options object. */
+export function loadConfig(directory, options, env = process.env) {
+  return mergeConfig(mergeConfig(readConfigFile(globalConfigPath(env)), readConfigFile(join(directory, PROJECT_FILE))), asConfig(options));
+}
+export function readConfigFile(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return asConfig(JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return {}; // a broken config must not take shells down with it
+  }
+}
+
+/** Section-wise merge: later sources win key by key, and never lose a whole section. */
+export function mergeConfig(base, over) {
+  return {
+    ...base,
+    ...over,
+    watch: {
+      ...base.watch,
+      ...over.watch,
+      presets: {
+        ...base.watch?.presets,
+        ...over.watch?.presets
+      }
+    },
+    kinds: {
+      ...base.kinds,
+      ...over.kinds
+    },
+    defaults: {
+      ...base.defaults,
+      ...over.defaults
+    },
+    notify: {
+      ...base.notify,
+      ...over.notify
+    },
+    ui: {
+      ...base.ui,
+      ...over.ui,
+      keybinds: {
+        ...base.ui?.keybinds,
+        ...over.ui?.keybinds
+      }
+    }
+  };
+}
+
+/**
+ * Plugin-entry options were flat before the config file existed (`{ dockHeight: 16 }`), so those
+ * keys still work and are read as `ui`.
+ */
+function asConfig(input) {
+  if (!input || typeof input !== "object") return {};
+  const raw = input;
+  const config = {};
+  for (const key of ["watch", "kinds", "defaults", "notify", "ui"]) {
+    const value = raw[key];
+    if (value && typeof value === "object") Object.assign(config, {
+      [key]: value
+    });
+  }
+  if (typeof raw.guidance === "boolean") config.guidance = raw.guidance;
+  if (typeof raw.listRunningShells === "number") config.listRunningShells = raw.listRunningShells;
+  const legacy = {};
+  for (const key of ["dockHeight", "dockOpen", "sidebarRows", "historyMinutes", "updateCheck"]) {
+    if (raw[key] !== undefined) Object.assign(legacy, {
+      [key]: raw[key]
+    });
+  }
+  if (raw.keybinds && typeof raw.keybinds === "object") legacy.keybinds = raw.keybinds;
+  return Object.keys(legacy).length > 0 ? mergeConfig(config, {
+    ui: legacy
+  }) : config;
+}

package/dist/core/find.js

@@ -0,0 +1,69 @@
+import { kindOfShell } from "./kind.js";
+
+/** The command as written, without the `$SHELL -c` wrapper. */
+export function commandOf(s) {
+  return s.args.length === 2 && s.args[0] === "-c" ? s.args[1] : [s.command, ...s.args].join(" ");
+}
+export function isFailed(s) {
+  return s.status === "failed" || s.status === "exited" && s.exitCode !== 0;
+}
+export function filterShells(list, filter) {
+  const query = filter.query?.trim().toLowerCase();
+  return list.filter(s => {
+    if (filter.kind && filter.kind !== "any" && kindOfShell(s, filter.kinds) !== filter.kind) return false;
+    if (query && !s.title.toLowerCase().includes(query) && !commandOf(s).toLowerCase().includes(query)) {
+      return false;
+    }
+    switch (filter.status ?? "any") {
+      case "running":
+        if (s.status !== "running") return false;
+        break;
+      case "failed":
+        if (!isFailed(s)) return false;
+        break;
+      case "finished":
+        if (s.status === "running") return false;
+        break;
+    }
+    switch (filter.session ?? "any") {
+      case "this":
+        return s.owner.session === filter.currentSession;
+      case "others":
+        return s.owner.session !== filter.currentSession;
+      default:
+        return true;
+    }
+  });
+}
+/**
+ * Finds the shell a name refers to. Exact names (ignoring case) beat partial matches on name or
+ * command. When several match, a single running shell is the obvious intent (earlier finished
+ * shells with the same name are history); otherwise the caller must choose.
+ */
+export function matchByName(list, name) {
+  const wanted = name.trim().toLowerCase();
+  const exact = list.filter(s => s.title.trim().toLowerCase() === wanted);
+  const matches = exact.length > 0 ? exact : list.filter(s => s.title.toLowerCase().includes(wanted) || commandOf(s).toLowerCase().includes(wanted));
+  if (matches.length === 0) return {
+    kind: "none",
+    available: [...list]
+  };
+  if (matches.length === 1) return {
+    kind: "found",
+    shell: matches[0],
+    alsoMatched: []
+  };
+  const running = matches.filter(s => s.status === "running");
+  if (running.length === 1) {
+    const shell = running[0];
+    return {
+      kind: "found",
+      shell,
+      alsoMatched: matches.filter(s => s !== shell)
+    };
+  }
+  return {
+    kind: "ambiguous",
+    candidates: matches
+  };
+}