@heretek-ai/epistemic-swarm 1.6.0 → 2.5.0

package/dist/tui.js

@@ -22,16 +22,29 @@ var TERMINAL_FALLBACK = (stage) => `Run \`es approve ${stage}\` at a terminal wi
 var APPROVAL_PREVIEW_TTL_MS = 120000;
 async function approveInTui(input) {
   const dir = input.stateDir ?? defaultStateDir();
+  const clock = input.now ?? Date.now;
+  const locked = (retryAfterSec) => ({
+    ok: false,
+    locked: true,
+    retryAfterSec,
+    retryAt: new Date(clock() + retryAfterSec * 1000).toISOString()
+  });
   if (!await exists(factoryLayout(input.root).dir) || !await hasHumanKey(dir))
     return { ok: false, fallback: true, reason: TERMINAL_FALLBACK(input.stage) };
   const gate = await checkApprovalAttempts(dir);
   if (!gate.allowed)
-    return { ok: false, locked: true, retryAfterSec: gate.retryAfterSec ?? 0 };
-  const title = `Approve ${input.stage} as ${input.approvedBy ?? userInfo().username}`;
+    return locked(gate.retryAfterSec ?? 0);
+  const base = `Approve ${input.stage} as ${input.approvedBy ?? userInfo().username}`;
+  let feedback;
   for (;; ) {
+    const title = feedback ? `${base} \u2014 ${feedback}` : base;
     const codepoints = await input.readPassphrase(title);
     if (codepoints === undefined)
       return { ok: false, cancelled: true };
+    if (codepoints.length === 0) {
+      zeroCodepoints(codepoints);
+      return { ok: false, cancelled: true };
+    }
     const passphrase = codepoints.join("");
     zeroCodepoints(codepoints);
     try {
@@ -59,7 +72,8 @@ async function approveInTui(input) {
       if (error instanceof HumanKeyError && error.message === "wrong passphrase") {
         const check = await noteWrongPassphrase({ dir, root: input.root, stage: input.stage, channel: "tui" });
         if (!check.allowed)
-          return { ok: false, locked: true, retryAfterSec: check.retryAfterSec ?? 0 };
+          return locked(check.retryAfterSec ?? 0);
+        feedback = `Wrong passphrase. ${check.remaining ?? 0} attempts left.`;
         continue;
       }
       throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "1.6.0",
+  "version": "2.5.0",
   "esRelease": {
     "order": 3
   },
@@ -44,7 +44,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@heretek-ai/es-core": "1.6.0",
+    "@heretek-ai/es-core": "2.5.0",
     "@opencode/plugin": "2.0.24"
   },
   "devDependencies": {

package/src/agents.ts

@@ -48,11 +48,32 @@ export function permissionRules(spec: AgentSpec, mcpServers: readonly string[]):
 }
 
 export function modelFor(spec: AgentSpec, options: PluginOptions) {
-  const ref = options.models?.agents?.[spec.id] ?? options.models?.[spec.tier]
+  const ref = options.models?.agents?.[spec.id] ?? roleModel(spec.id, options) ?? options.models?.[spec.tier]
   if (!ref) return undefined
   return parseModelRef(ref)
 }
 
+/** Heterogeneous-model role keys (#170): the seat's models.<role> key, so enforcement and reality agree. */
+function roleModel(agentId: string, options: PluginOptions): string | undefined {
+  const role = ROLE_MODEL_KEY[agentId]
+  return role ? options.models?.[role] : undefined
+}
+
+const ROLE_MODEL_KEY: Record<string, "programmer" | "qa" | "auditor"> = {
+  "es-programmer": "programmer",
+  "es-qa-functional": "qa",
+  "es-qa-adversarial": "qa",
+  "es-auditor-thesis": "auditor",
+  "es-auditor-antithesis": "auditor",
+}
+
+/** The config key a seat's model resolved from (for remediation text). */
+function modelKey(spec: AgentSpec, options: PluginOptions): string {
+  if (options.models?.agents?.[spec.id] !== undefined) return `models.agents.${spec.id}`
+  if (roleModel(spec.id, options) !== undefined) return `models.${ROLE_MODEL_KEY[spec.id]!}`
+  return `models.${spec.tier}`
+}
+
 /** A configured model ref the host does not have: the seat is refused at launch (#96). */
 export interface ModelProblem {
   readonly agent: string
@@ -80,9 +101,9 @@ export function modelProblems(
 ): ModelProblem[] {
   const problems: ModelProblem[] = []
   for (const spec of specs) {
-    const ref = options.models?.agents?.[spec.id] ?? options.models?.[spec.tier]
+    const ref = options.models?.agents?.[spec.id] ?? roleModel(spec.id, options) ?? options.models?.[spec.tier]
     if (ref === undefined) continue
-    const key = options.models?.agents?.[spec.id] !== undefined ? `models.agents.${spec.id}` : `models.${spec.tier}`
+    const key = modelKey(spec, options)
     const parsed = parseModelRef(ref)
     if (parsed === undefined || !exists(parsed.providerID, parsed.id))
       problems.push({

package/src/approve-tui.ts

@@ -51,7 +51,7 @@ export interface ApproveTuiInput {
 export type ApproveTuiOutcome =
   | { readonly ok: true; readonly record: Approval }
   | { readonly ok: false; readonly fallback: true; readonly reason: string }
-  | { readonly ok: false; readonly locked: true; readonly retryAfterSec: number }
+  | { readonly ok: false; readonly locked: true; readonly retryAfterSec: number; readonly retryAt: string }
   | { readonly ok: false; readonly cancelled: true }
 
 const TERMINAL_FALLBACK = (stage: ApprovalStage) =>
@@ -71,6 +71,13 @@ export const APPROVAL_PREVIEW_TTL_MS = 120_000
  */
 export async function approveInTui(input: ApproveTuiInput): Promise<ApproveTuiOutcome> {
   const dir = input.stateDir ?? defaultStateDir()
+  const clock = input.now ?? Date.now
+  const locked = (retryAfterSec: number): ApproveTuiOutcome => ({
+    ok: false,
+    locked: true,
+    retryAfterSec,
+    retryAt: new Date(clock() + retryAfterSec * 1000).toISOString(),
+  })
   // A TUI that cannot see the project root and the sealed key (a remote
   // attach) keeps the "approve in a terminal" alert instead of signing
   // anywhere else.
@@ -78,12 +85,22 @@ export async function approveInTui(input: ApproveTuiInput): Promise<ApproveTuiOu
     return { ok: false, fallback: true, reason: TERMINAL_FALLBACK(input.stage) }
 
   const gate = await checkApprovalAttempts(dir)
-  if (!gate.allowed) return { ok: false, locked: true, retryAfterSec: gate.retryAfterSec ?? 0 }
+  if (!gate.allowed) return locked(gate.retryAfterSec ?? 0)
 
-  const title = `Approve ${input.stage} as ${input.approvedBy ?? userInfo().username}`
+  const base = `Approve ${input.stage} as ${input.approvedBy ?? userInfo().username}`
+  // #353: the reopened dialog names the failure reason and the attempts
+  // left, so a wrong passphrase is visible instead of silent.
+  let feedback: string | undefined
   for (;;) {
+    const title = feedback ? `${base} — ${feedback}` : base
     const codepoints = await input.readPassphrase(title)
     if (codepoints === undefined) return { ok: false, cancelled: true }
+    // #353: an empty Enter cancels like the CLI ("empty cancels"), and
+    // records no failure.
+    if (codepoints.length === 0) {
+      zeroCodepoints(codepoints)
+      return { ok: false, cancelled: true }
+    }
     // The string cannot be zeroed in JS (same as the CLI's echo-off input):
     // it lives in this local only, and the array is zeroed at once.
     const passphrase = codepoints.join("")
@@ -115,7 +132,8 @@ export async function approveInTui(input: ApproveTuiInput): Promise<ApproveTuiOu
     } catch (error) {
       if (error instanceof HumanKeyError && error.message === "wrong passphrase") {
         const check = await noteWrongPassphrase({ dir, root: input.root, stage: input.stage, channel: "tui" })
-        if (!check.allowed) return { ok: false, locked: true, retryAfterSec: check.retryAfterSec ?? 0 }
+        if (!check.allowed) return locked(check.retryAfterSec ?? 0)
+        feedback = `Wrong passphrase. ${check.remaining ?? 0} attempts left.`
         continue
       }
       throw error

package/src/hooks.ts

@@ -5,7 +5,10 @@
 //                          "ask" defers to the host permission prompt)
 //   PostToolUse(Failure)← tool.execute.after (feedback/context appended, output replaced)
 //   UserPromptSubmit    ← session prompt admission (block rejects, context appended)
-//   SessionStart        ← first prompt of a session (startup) and after compaction
+//   SessionStart        ← first prompt of a session (startup), a forked session
+//                          (fork), and after compaction (compact). Resume/clear
+//                          have no host bus events, so they stay intentionally
+//                          unsupported (the engine notices unmatched sources).
 //   PermissionRequest   ← permission.evaluate when the host would ask
 //   x-es.ShellPreExec   ← shell.create.before
 //   Stop (emulated)     ← session.execution.succeeded: a block re-prompts the
@@ -252,6 +255,15 @@ export async function createHookBridge(
         )
         return
       }
+      if (event.type === "session.forked" && engine.has("SessionStart")) {
+        // A forked session is a new session inheriting its parent's history
+        // (#289): run the SessionStart hooks filtered to "fork" now, and mark
+        // the fork started so its first prompt does not refire "startup".
+        const agent = await agentOf(sessionID)
+        stash(sessionContext, sessionID, (await engine.sessionStart(base(sessionID, agent), "fork")).additionalContext)
+        startedSessions.add(sessionID)
+        return
+      }
       if (event.type !== "session.execution.succeeded" || !engine.has("Stop")) return
       const count = continuations.get(sessionID) ?? 0
       if (count >= STOP_CAP) {

package/src/policy.ts

@@ -7,6 +7,7 @@ import path from "node:path"
 import {
   agentSpec,
   bwrapAvailable,
+  bwrapOverlay,
   checkStopFile,
   evaluateRead,
   evaluateShell,
@@ -22,7 +23,7 @@ import {
 import { Error as ToolError } from "@opencode/plugin/promise/tool"
 import { HOST_WEB_TOOLS } from "./agents.ts"
 import type { Runtime } from "./runtime.ts"
-import type { SeatTracker } from "./seats.ts"
+import { type SeatTracker, seatModelRefusal } from "./seats.ts"
 
 const WRITE_TOOLS = new Set(["write", "edit"])
 
@@ -39,6 +40,28 @@ export function patchTargets(patchText: string): string[] {
   return targets
 }
 
+/**
+ * The seat-shell sandbox mode for `cwd` (#326): "sandboxed" when bubblewrap
+ * can build the seat sandbox including the overlay mounts the shell backstop
+ * needs, "host-fallback" when bwrap is present but the overlay is unavailable
+ * for `cwd` (e.g. a btrfs mount without userxattr — the shell then runs
+ * without the read-only backstop, the #294 fallback), "unavailable" when
+ * there is no bwrap at all (seat shells are refused outright).
+ *
+ * Naming only: enforcement is unchanged. Whether the fallback stays or the
+ * shell fails closed on such hosts is the human's product decision on #326;
+ * this names the mode so the control matrix asserts the designed behaviour
+ * for the mode the host is in, with the mode in the assertion output.
+ */
+export function seatShellSandboxMode(cwd: string): "sandboxed" | "host-fallback" | "unavailable" {
+  if (!bwrapAvailable()) return "unavailable"
+  try {
+    return bwrapOverlay(cwd) ? "sandboxed" : "host-fallback"
+  } catch {
+    return "host-fallback"
+  }
+}
+
 const deny = (message: string): never => {
   throw new ToolError({ message })
 }
@@ -85,17 +108,24 @@ export function createPolicyHooks(runtime: Runtime, seats?: SeatTracker) {
     if (event.tool === "subagent" && typeof input.agent === "string") {
       const problem = runtime.modelProblems?.get(input.agent)
       if (problem) deny(problem.message)
+      // Heterogeneous models (#170): a programmer/QA seat that would share
+      // weights with the other side never launches.
+      const refusal = seatModelRefusal(input.agent, runtime.config?.models)
+      if (refusal) deny(`Seat "${input.agent}" cannot launch: ${refusal}`)
     }
     if (seat && event.tool === "subagent") guardSeatLaunch({ agent: event.agent, input }, seats)
     if (seat && event.sessionID) await seats?.onTool(event.sessionID, event.agent, event.tool)
-    if (seat || event.tool.startsWith("es_")) {
+    // STOP halts seats, es_* tools, and seat launches whoever fires them (#227):
+    // a user agent must not route around the kill-switch via `subagent`.
+    if (seat || event.tool.startsWith("es_") || event.tool === "subagent") {
       const stop = await checkStopFile(runtime.root)
       if (stop.stopped)
         deny(`The factory is stopped (.factory/STOP: ${stop.reason}). A human must remove it and resume.`)
     }
     // A halted run (spend ceiling, runtime cap, drift, STOP) stops every seat
     // tool except es_status, so no seat keeps spending through its own es_* tools.
-    if (seat && event.tool !== "es_status") {
+    // Seat launches count as seat tools whoever fires them (#227).
+    if ((seat || event.tool === "subagent") && event.tool !== "es_status") {
       const state = await runtime.factory.read().catch(() => undefined)
       if (state?.stage === "HALTED")
         deny(`The factory is halted: ${state.halt?.reason}. Stop and report; a human must resume.`)
@@ -174,7 +204,10 @@ export function createPolicyHooks(runtime: Runtime, seats?: SeatTracker) {
           ? patchTargets(input.patchText)
           : []
     if (!files.length) return
-    if (runtime.options.lspAfterEdit !== false) {
+    // The post-edit diagnostics are a language-server channel (#277.2): seats
+    // scoped to `lsp: "none"` never get them (their tool rules already hide
+    // `lsp_*`). Navigating seats and the user's own agents keep the channel.
+    if (runtime.options.lspAfterEdit !== false && agentSpec(event.agent)?.lsp !== "none") {
       const lines: string[] = []
       for (const file of files) {
         const absolute = path.resolve(runtime.root, file)
@@ -222,6 +255,8 @@ export function createPolicyHooks(runtime: Runtime, seats?: SeatTracker) {
   }) => {
     const seat = seatOf(event.agent)
     const context = await runtime.policy()
+    // The host's patch tool asks for `edit` too, once, with every target of
+    // the patch as a resource: there is no `patch` action to branch on (#220).
     if (event.action === "edit" || event.action === "read") {
       const decisions = event.resources.map((resource) =>
         event.action === "edit"

package/src/pr.ts

@@ -1,6 +1,10 @@
-// Release PR opener backed by the GitHub CLI. It pushes only the run's
-// integration branch (never the base branch) and opens a draft PR for a human
-// to review and merge.
+// Factory release PR opener backed by the GitHub CLI. Every factory push
+// path goes through here: it pushes only the run's `factory/` integration
+// branch — `branch === base` or a non-`factory/` branch is refused before
+// any push — and opens a draft PR for a human to review and merge. (Other
+// push paths exist outside the factory: `es improve --open-pr` pushes
+// `improve/*` branches on its own human-run path; phase fast-forwards and
+// fleet landings never touch the base branch; only a human merges.)
 import type { PrOpener } from "@heretek-ai/es-core"
 import { buildPrArgs, git, run } from "@heretek-ai/es-core"
 

package/src/rpc.ts

@@ -70,6 +70,37 @@ export function createRpcHandlers(
       reason: error instanceof Error ? error.message : String(error),
     })
 
+  // #355: an unreadable run state (missing/forged seal) is a status value,
+  // not a throw — otherwise the 5 s footer poll logs `rpc handler failed`
+  // every poll. The problem is logged once per distinct problem.
+  let lastSealProblem: string | undefined
+  const isSealProblem = (error: unknown): string | undefined => {
+    const message = error instanceof Error ? error.message : String(error)
+    return /Cannot verify \.factory\/runtime\/state\.json|\.factory\/runtime\/state\.json has a|is a version .* run/i.test(
+      message,
+    )
+      ? message
+      : undefined
+  }
+  const noteSealProblem = (message: string) => {
+    if (lastSealProblem !== message) {
+      lastSealProblem = message
+      console.warn(`[epistemic-swarm] run state unreadable: ${message}`)
+    }
+  }
+  const clearSealProblem = () => {
+    if (lastSealProblem !== undefined) {
+      lastSealProblem = undefined
+      console.warn("[epistemic-swarm] run state readable again")
+    }
+  }
+  const sealFix = (message: string): string => {
+    if (message.includes("es reseal --sign")) return "es reseal --sign"
+    if (message.includes("ES_STATE_DIR")) return "ES_STATE_DIR"
+    if (message.includes("/grill")) return "/grill"
+    return "see status"
+  }
+
   /** Everything a trust approval covers: gate commands and project hooks. */
   const trustSubject = async () => {
     const { config } = await loadGatesConfig(runtime.root)
@@ -87,7 +118,24 @@ export function createRpcHandlers(
 
   return {
     status: async () => {
-      const state = await runtime.factory.read()
+      let state: Awaited<ReturnType<Runtime["factory"]["read"]>>
+      try {
+        state = await runtime.factory.read()
+      } catch (error) {
+        const problem = isSealProblem(error)
+        if (problem === undefined) throw error
+        noteSealProblem(problem)
+        const fix = sealFix(problem)
+        return {
+          summary: `<factory-state>State unreadable: ${problem}</factory-state>`,
+          stage: "ERROR",
+          pending: [],
+          headline: `State unreadable: ${problem}`,
+          footer: `ES · state unreadable · ${problem.slice(0, 100)} · fix: ${fix}`,
+          sealProblem: problem,
+        }
+      }
+      clearSealProblem()
       const liveness = await readLiveness(runtime.root, state)
       const paused = live.paused?.()
       const footer = footerLine(state, liveness, paused)
@@ -106,7 +154,26 @@ export function createRpcHandlers(
       warnings: [...runtime.warnings],
     }),
     factoryState: async () => {
-      const state = await runtime.factory.read()
+      let state: Awaited<ReturnType<Runtime["factory"]["read"]>>
+      try {
+        state = await runtime.factory.read()
+      } catch (error) {
+        const problem = isSealProblem(error)
+        if (problem === undefined) throw error
+        noteSealProblem(problem)
+        return {
+          headline: `State unreadable: ${problem}`,
+          seats: [],
+          events: [],
+          phases: [],
+          audits: [],
+          pending: [],
+          spend: { usd: 0, estimated: false },
+          stage: "ERROR",
+          sealProblem: problem,
+        }
+      }
+      clearSealProblem()
       const frontier = await readFrontier(runtime.root).catch(() => undefined)
       const liveness = await readLiveness(runtime.root, state)
       const research = researchLine(liveness)

package/src/runtime.ts

@@ -1,8 +1,9 @@
 // Per-location runtime shared by the plugin's hooks, tools, commands and RPC.
-// Options are layered: the canonical config (global file → project file) with
-// plugin options as the most specific override. Plugin options are config
-// keys validated by the same strict schema; unknown keys are ignored with a
-// warning the TUI shows once.
+// The server only wires option layering (parseOptions → createRuntime); the
+// merge itself lives in core (loadEsConfig/mergeConfig): the canonical config
+// (global file → project file) with plugin options as the most specific
+// override. Plugin options are config keys validated by the same strict
+// schema; unknown keys are ignored with a warning the TUI shows once.
 import {
   stateDir as defaultStateDir,
   type EsConfig,
@@ -68,6 +69,9 @@ export async function createRuntime(root: string, parsed: ParsedOptions): Promis
     ...(config.searchProvider ? { searchProvider: config.searchProvider } : {}),
   }
   const stateDir = options.stateDir ?? defaultStateDir()
+  // One manager per project (#275.1): servers start lazily per (server, root)
+  // and are reaped by the idle sweeper between sessions, stopping only on
+  // plugin unload (see server.ts) — long-lived servers outlive sessions.
   const lsp = new LspManager({ root, stateDir })
   const factory = new Factory(root, {
     gates: gateRunner({ stateDir }),
@@ -76,6 +80,7 @@ export async function createRuntime(root: string, parsed: ParsedOptions): Promis
     researchDepth: config.research.depth,
     ...(config.domainPack ? { domainPack: config.domainPack } : {}),
     ...(config.audit.phase === "required" ? { auditPhase: "required" as const } : {}),
+    ...(config.models ? { models: config.models } : {}),
   })
   return {
     root,

package/src/seats.ts

@@ -3,7 +3,14 @@
 // tool and last activity in .factory/runtime/seats.json. es_status, `es
 // status`, the dashboard and the headless driver read it; the foreground guard
 // and the continuation ask it what is running right now.
-import { agentSpec, type SeatRecord, updateSeats } from "@heretek-ai/es-core"
+import {
+  agentSpec,
+  assertModelDiversity,
+  ModelDiversityError,
+  type SeatModelMap,
+  type SeatRecord,
+  updateSeats,
+} from "@heretek-ai/es-core"
 import type { Runtime } from "./runtime.ts"
 
 /** Activity-only updates (tool calls, steps) are persisted at most this often per seat. */
@@ -29,6 +36,26 @@ export interface SeatTracker {
   hasRunningChildren(parentID: string): boolean
 }
 
+/** Seats covered by the heterogeneous-model policy (#170): the programmer and both QA seats. */
+const DIVERSE_SEATS: ReadonlySet<string> = new Set(["es-programmer", "es-qa-functional", "es-qa-adversarial"])
+
+/**
+ * Refusal text when launching `target` would run the programmer and QA on the
+ * same model provider (shared weights share blind spots); undefined when the
+ * target is not a build seat or diversity holds. Unverified configs (unset
+ * seats) launch unless models.requireDiversity is set.
+ */
+export function seatModelRefusal(target: string, models: SeatModelMap | undefined): string | undefined {
+  if (!DIVERSE_SEATS.has(target)) return undefined
+  try {
+    assertModelDiversity(models)
+    return undefined
+  } catch (error) {
+    if (error instanceof ModelDiversityError) return error.message
+    throw error
+  }
+}
+
 /** Factory seats are the registry's subagents; primary agents (factory, grill) are drivers, not seats. */
 const isSeat = (agent: string | undefined): agent is string => agentSpec(agent)?.mode === "subagent"
 

package/src/server.ts

@@ -1,6 +1,9 @@
 // Epistemic Swarm for OpenCode v2 (server plugin). Additive: registers our
 // agents, tools, skills, commands, hooks and RPC through runtime transforms;
-// writes no config files and never touches built-in agents or defaults.
+// setup writes no project-tree files and no config files (the engine key goes
+// to the masked state dir; spend and seat tracking later write
+// .factory/runtime/* while sessions run). It never touches built-in agents or
+// defaults.
 import { readdir, readFile } from "node:fs/promises"
 import path from "node:path"
 import {
@@ -27,7 +30,7 @@ import { createPolicyHooks } from "./policy.ts"
 import { createWebCache, PendingSearches, registerWebsearch } from "./research.ts"
 import { createRpcHandlers } from "./rpc.ts"
 import { EsRpc } from "./rpc-def.ts"
-import { createRuntime, parseOptions } from "./runtime.ts"
+import { createRuntime, parseOptions, type Runtime } from "./runtime.ts"
 import { createSeatTracker } from "./seats.ts"
 import { createSessionHooks, createSpendTracker } from "./session.ts"
 import { registerTools } from "./tools.ts"
@@ -47,6 +50,346 @@ export function parseDeepResearchArgs(text: string): DeepResearchArgs {
   return { query, ceiling }
 }
 
+/** The session surface slash commands use (the host's `ctx.session`; stubbed in tests). */
+export interface CommandSession {
+  switchAgent(sessionID: string, agent: string): Promise<unknown>
+  sendPrompt(sessionID: string, prompt: Record<string, unknown>, text: string, delivery: unknown): Promise<unknown>
+  synthetic(sessionID: string, text: string): Promise<unknown>
+}
+
+/** One slash command: its name, description and host-independent body. */
+export interface CommandSpec {
+  readonly name: string
+  readonly description: string
+  readonly execute: (args: {
+    readonly sessionID: string
+    readonly prompt: { readonly text?: string } & Record<string, unknown>
+    readonly delivery?: unknown
+  }) => Promise<void>
+}
+
+/** The hook-bridge surface slash commands read (status for `/hooks`). */
+export interface CommandBridge {
+  readonly engine: {
+    refresh(): Promise<void>
+    status(): {
+      readonly handlers: number
+      readonly projectHandlers: number
+      readonly trusted: boolean
+      readonly projectLines: readonly string[]
+      readonly diagnostics: readonly string[]
+    }
+    readonly recent: readonly string[]
+  }
+}
+
+/**
+ * Every slash command the plugin registers, as data: the host loop below
+ * adds each one, and tests invoke each body against a stub session to prove
+ * routing (seat/verb per command) and name uniqueness (one `research`).
+ */
+export function esCommandSpecs(
+  io: CommandSession,
+  runtime: Runtime,
+  bridge: CommandBridge,
+  runners: { readonly runGates?: typeof runGates; readonly git?: typeof git } = {},
+): CommandSpec[] {
+  const specs: CommandSpec[] = []
+  const gates = runners.runGates ?? runGates
+  const gitStatus = runners.git ?? git
+  specs.push({
+    name: "grill",
+    description: "Grill an idea until the design and spend ceiling are settled (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      await io.switchAgent(sessionID, "grill")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        prompt.text?.trim() ? `Grill me on: ${prompt.text}` : "Start grilling me on my idea.",
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "brainstorm",
+    description: "Fan out divergent lenses on an idea and return a diversified shortlist (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      await io.switchAgent(sessionID, "brainstormer")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        prompt.text?.trim()
+          ? `Brainstorm: ${prompt.text}`
+          : "Ask me for the idea to brainstorm (one sentence), then run the lens fan-out.",
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "harvest",
+    description: "Tear down competitor projects: licences, feature matrix, clean-room specs (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      await io.switchAgent(sessionID, "harvester")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        prompt.text?.trim()
+          ? `Darkharvest: ${prompt.text}`
+          : "Ask me for the teardown objective and the candidate projects, then run the harvest.",
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "design",
+    description: "Interview me into a design system: tokens, contrast gates, style guide (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      await io.switchAgent(sessionID, "designer")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        prompt.text?.trim()
+          ? `Run the design interview. Product: ${prompt.text}`
+          : "Ask me for the product name and start the design interview, one question at a time.",
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "scout",
+    description: "Find and vet open-source candidates for a feature: licenses, maintenance, CVEs (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      await io.switchAgent(sessionID, "scout")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        prompt.text?.trim()
+          ? `Scout: ${prompt.text}`
+          : "Ask me for the feature to scout and our license posture, then plan the candidates.",
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "research",
+    // One name, one body (#274): a leading `deep` runs the adversarial deep
+    // flow (switching to the deep-researcher); anything else reads the
+    // research stage (report, audit coverage, cached sources).
+    description:
+      "Deep research to a grounded report, or the research stage: report, audit coverage and cached sources (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      const say = async (text: string) => {
+        await io.synthetic(sessionID, text)
+      }
+      const text = prompt.text?.trim() ?? ""
+      if (text.split(/\s+/)[0]?.toLowerCase() !== "deep") {
+        const layout = factoryLayout(runtime.root)
+        const report = await readFile(layout.researchReport, "utf8").catch(() => undefined)
+        const coverage = await readJson<{
+          claims?: number
+          grounded?: number
+          untagged?: number
+          ungrounded?: number
+          malformed?: number
+          sources?: number
+          passed?: boolean
+        }>(path.join(layout.research, "coverage.json")).catch(() => undefined)
+        const sources = (await readdir(researchSourcesDir(runtime.root)).catch(() => [])).filter((file) =>
+          file.endsWith(".md"),
+        )
+        const lines = [
+          report === undefined
+            ? "No research report yet (.factory/research/REPORT.md)."
+            : `Report: ${report.length} characters in .factory/research/REPORT.md.`,
+          coverage
+            ? `Audit: ${coverage.grounded ?? 0}/${coverage.claims ?? 0} claims grounded (untagged ${coverage.untagged ?? 0}, ungrounded ${coverage.ungrounded ?? 0}, malformed ${coverage.malformed ?? 0}); cited sources ${coverage.sources ?? 0}; passed ${coverage.passed ? "yes" : "no"}.`
+            : "No coverage.json yet (es_research_complete writes it).",
+          `Cached sources: ${sources.length}.`,
+        ]
+        return say(lines.join("\n"))
+      }
+      const parsed = parseDeepResearchArgs(text)
+      if ("error" in parsed && parsed.error === "usage") {
+        return say("Usage: /research deep <question> --max-usd N")
+      }
+      if ("error" in parsed) {
+        return say(
+          "Deep research needs a spend ceiling you set: /research deep <question> --max-usd N. Seats halt when the spend reaches it.",
+        )
+      }
+      const { query, ceiling } = parsed
+      const existing = await runtime.factory.read().catch(() => undefined)
+      if (existing && existing.mode !== "research") {
+        return say(
+          "This project holds a build run. Start deep research in a directory without one (`es research deep <question> --output <dir> --max-usd N` at a terminal).",
+        )
+      }
+      if (existing?.stage === "HALTED") {
+        return say(
+          "This research run is halted; resume it first (`es factory resume` at a terminal, or /es-resume to preview).",
+        )
+      }
+      if (existing?.stage === "DONE") {
+        return say(
+          "This research run is done. For a new question, start one in a fresh directory (`es research deep <question> --output <dir> --max-usd N` at a terminal).",
+        )
+      }
+      if (!existing) {
+        try {
+          // The human typed /research deep: beginning the run is their action.
+          await runtime.factory.beginResearchRun({ objective: query, ceilingUSD: Number(ceiling) }, "human:tui")
+        } catch (error) {
+          return say(`Could not start the research run: ${error instanceof Error ? error.message : String(error)}`)
+        }
+      }
+      await io.switchAgent(sessionID, "deep-researcher")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        `${await runtime.factory.summary()}\nDeep research runs adversarially, with no human answering questions mid-flow; follow your Flow through es_research_complete.`,
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "audit",
+    description: "Open a code audit of the active phase or a path and run the auditor pair (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      const target = prompt.text?.trim()
+      const say = async (text: string) => {
+        await io.synthetic(sessionID, text)
+      }
+      if (!target) return say("Usage: /audit <active phase id | path in the project>")
+      const state = await runtime.factory.read().catch(() => undefined)
+      if (state?.spendCeilingUSD === undefined)
+        return say(
+          "Audits run inside a factory run with a spend ceiling. Start one at a terminal with `es audit <target> --max-usd N`, or run /grill first.",
+        )
+      let opened: Awaited<ReturnType<typeof runtime.factory.openAudit>>
+      try {
+        // The human typed /audit: opening it is their action.
+        opened = await runtime.factory.openAudit(
+          "human:tui",
+          parseAuditTarget(
+            target,
+            state.phases.map((phase) => phase.id),
+          ),
+        )
+      } catch (error) {
+        return say(`Could not open the audit: ${error instanceof Error ? error.message : String(error)}`)
+      }
+      const { audit } = opened
+      await io.switchAgent(sessionID, "factory")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        `${await runtime.factory.summary()}\nThe human opened code audit ${audit.id} (round ${audit.round}) on ${describeTarget(audit.target)}. Launch es-auditor-thesis and es-auditor-antithesis in parallel with the audit id and target; if they split, have es-manager break the tie (es_tiebreak with audit). Report the verdicts and the report path when the audit settles.`,
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "factory",
+    description: "Drive the build factory from its current stage (Epistemic Swarm)",
+    execute: async ({ sessionID, prompt, delivery }) => {
+      const state = await runtime.factory.read()
+      if (!state) {
+        await io.synthetic(sessionID, "No factory run here yet — run /grill first.")
+        return
+      }
+      await io.switchAgent(sessionID, "factory")
+      await io.sendPrompt(
+        sessionID,
+        prompt,
+        `${await runtime.factory.summary(state)}\nContinue the factory run from its current stage.${prompt.text?.trim() ? `\nHuman note: ${prompt.text}` : ""}`,
+        delivery,
+      )
+    },
+  })
+  specs.push({
+    name: "gates",
+    description: "Run the mechanical gates on changed files (Epistemic Swarm)",
+    execute: async ({ sessionID }) => {
+      const changed = (await gitStatus(runtime.root, ["status", "--porcelain=v1", "-uall"], { allowFail: true })).stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => line.slice(3).split(" -> ").at(-1)!)
+      const report = await gates({
+        root: runtime.root,
+        scope: changed.length ? "touched" : "full",
+        touched: changed,
+        stateDir: runtime.stateDir,
+      })
+      await io.synthetic(sessionID, formatReport(report))
+    },
+  })
+  specs.push({
+    name: "lsp",
+    description: "Language servers: configured, available and running (Epistemic Swarm)",
+    execute: async ({ sessionID }) => {
+      const status = await runtime.lsp.status()
+      const settings = await runtime.lsp.settings()
+      const lines = [status.enabled ? "LSP is on." : "LSP is disabled (lsp: false)."]
+      for (const server of settings.servers) {
+        const command = await runtime.lsp.command(server, runtime.root)
+        const running = status.running.filter((item) => item.id === server.id)
+        lines.push(
+          `${server.id} [${server.extensions.join(" ")}]: ${Array.isArray(command) ? `available (${command.join(" ")})` : command.unavailable}${running.length ? ` · running for ${running.length} root(s)` : ""}`,
+        )
+      }
+      lines.push(...status.diagnostics.map((item) => `! ${item}`))
+      await io.synthetic(sessionID, lines.join("\n"))
+    },
+  })
+  specs.push({
+    name: "hooks",
+    description: "Show the hook bridge: sources, handlers, trust and diagnostics (Epistemic Swarm)",
+    execute: async ({ sessionID }) => {
+      await bridge.engine.refresh()
+      const status = bridge.engine.status()
+      const trust =
+        status.projectHandlers === 0
+          ? "nothing to trust"
+          : status.trusted
+            ? "trusted"
+            : "NOT trusted: run /es-trust or `es trust`"
+      const lines = [
+        `Hook bridge: ${status.handlers} handler(s), ${status.projectHandlers} from the project (${trust}).`,
+        ...status.projectLines,
+        ...status.diagnostics.map((item) => `! ${item}`),
+        ...bridge.engine.recent.slice(-10).map((item) => `recent error: ${item}`),
+        "Stop hooks are emulated after the turn ends (advisory for plain chat).",
+      ]
+      await io.synthetic(sessionID, lines.join("\n"))
+    },
+  })
+  specs.push({
+    name: "status",
+    description: "Show the factory state (Epistemic Swarm)",
+    execute: async ({ sessionID }) => {
+      const state = await runtime.factory.read()
+      const liveness = await readLiveness(runtime.root, state)
+      const text = [await runtime.factory.summary(state), ...livenessLines(state, liveness)].join("\n")
+      await io.synthetic(sessionID, text)
+    },
+  })
+  specs.push({
+    name: "config",
+    description: "Show the effective Epistemic Swarm config and where it came from (Epistemic Swarm)",
+    execute: async ({ sessionID }) => {
+      const lines = [
+        runtime.configSources.length
+          ? `Layers: ${runtime.configSources.join(" → ")} → plugin options`
+          : "Layers: defaults only (no config files)",
+        ...runtime.warnings.map((warning) => `Warning: ${warning}`),
+        JSON.stringify(runtime.config, null, 2),
+      ]
+      await io.synthetic(sessionID, lines.join("\n"))
+    },
+  })
+  return specs
+}
+
 export default Plugin.define({
   id: PLUGIN_ID,
   async setup(ctx) {
@@ -183,301 +526,13 @@ export default Plugin.define({
     }) as any)
 
     await ctx.command.transform((editor) => {
-      editor.add({
-        name: "grill",
-        description: "Grill an idea until the design and spend ceiling are settled (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          await ctx.session.switchAgent({ sessionID, agent: "grill" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: prompt.text?.trim() ? `Grill me on: ${prompt.text}` : "Start grilling me on my idea.",
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "brainstorm",
-        description: "Fan out divergent lenses on an idea and return a diversified shortlist (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          await ctx.session.switchAgent({ sessionID, agent: "brainstormer" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: prompt.text?.trim()
-              ? `Brainstorm: ${prompt.text}`
-              : "Ask me for the idea to brainstorm (one sentence), then run the lens fan-out.",
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "harvest",
-        description: "Tear down competitor projects: licences, feature matrix, clean-room specs (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          await ctx.session.switchAgent({ sessionID, agent: "harvester" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: prompt.text?.trim()
-              ? `Darkharvest: ${prompt.text}`
-              : "Ask me for the teardown objective and the candidate projects, then run the harvest.",
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "design",
-        description: "Interview me into a design system: tokens, contrast gates, style guide (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          await ctx.session.switchAgent({ sessionID, agent: "designer" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: prompt.text?.trim()
-              ? `Run the design interview. Product: ${prompt.text}`
-              : "Ask me for the product name and start the design interview, one question at a time.",
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "scout",
-        description: "Find and vet open-source candidates for a feature: licenses, maintenance, CVEs (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          await ctx.session.switchAgent({ sessionID, agent: "scout" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: prompt.text?.trim()
-              ? `Scout: ${prompt.text}`
-              : "Ask me for the feature to scout and our license posture, then plan the candidates.",
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "research",
-        description: "Adversarial deep research to a grounded report: thesis, antithesis, synthesis (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          const say = async (text: string) => {
-            await ctx.session.synthetic({ sessionID, text } as any)
-          }
-          const text = prompt.text?.trim() ?? ""
-          const parsed = parseDeepResearchArgs(text)
-          if ("error" in parsed && parsed.error === "usage") {
-            return say("Usage: /research deep <question> --max-usd N")
-          }
-          if ("error" in parsed) {
-            return say(
-              "Deep research needs a spend ceiling you set: /research deep <question> --max-usd N. Seats halt when the spend reaches it.",
-            )
-          }
-          const { query, ceiling } = parsed
-          const existing = await runtime.factory.read().catch(() => undefined)
-          if (existing && existing.mode !== "research") {
-            return say(
-              "This project holds a build run. Start deep research in a directory without one (`es research deep <question> --output <dir> --max-usd N` at a terminal).",
-            )
-          }
-          if (existing?.stage === "HALTED") {
-            return say(
-              "This research run is halted; resume it first (`es factory resume` at a terminal, or /es-resume to preview).",
-            )
-          }
-          if (existing?.stage === "DONE") {
-            return say(
-              "This research run is done. For a new question, start one in a fresh directory (`es research deep <question> --output <dir> --max-usd N` at a terminal).",
-            )
-          }
-          if (!existing) {
-            try {
-              // The human typed /research deep: beginning the run is their action.
-              await runtime.factory.beginResearchRun({ objective: query, ceilingUSD: Number(ceiling) }, "human:tui")
-            } catch (error) {
-              return say(`Could not start the research run: ${error instanceof Error ? error.message : String(error)}`)
-            }
-          }
-          await ctx.session.switchAgent({ sessionID, agent: "deep-researcher" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            // The coordinator flow is the deep-researcher seat's system prompt
-            // (single-sourced in core); this only adds the run state.
-            text: `${await runtime.factory.summary()}\nDeep research runs adversarially, with no human answering questions mid-flow; follow your Flow through es_research_complete.`,
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "audit",
-        description: "Open a code audit of the active phase or a path and run the auditor pair (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          const target = prompt.text?.trim()
-          const say = async (text: string) => {
-            await ctx.session.synthetic({ sessionID, text } as any)
-          }
-          if (!target) return say("Usage: /audit <active phase id | path in the project>")
-          const state = await runtime.factory.read().catch(() => undefined)
-          if (state?.spendCeilingUSD === undefined)
-            return say(
-              "Audits run inside a factory run with a spend ceiling. Start one at a terminal with `es audit <target> --max-usd N`, or run /grill first.",
-            )
-          let opened: Awaited<ReturnType<typeof runtime.factory.openAudit>>
-          try {
-            // The human typed /audit: opening it is their action.
-            opened = await runtime.factory.openAudit(
-              "human:tui",
-              parseAuditTarget(
-                target,
-                state.phases.map((phase) => phase.id),
-              ),
-            )
-          } catch (error) {
-            return say(`Could not open the audit: ${error instanceof Error ? error.message : String(error)}`)
-          }
-          const { audit } = opened
-          await ctx.session.switchAgent({ sessionID, agent: "factory" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: `${await runtime.factory.summary()}\nThe human opened code audit ${audit.id} (round ${audit.round}) on ${describeTarget(audit.target)}. Launch es-auditor-thesis and es-auditor-antithesis in parallel with the audit id and target; if they split, have es-manager break the tie (es_tiebreak with audit). Report the verdicts and the report path when the audit settles.`,
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "factory",
-        description: "Drive the build factory from its current stage (Epistemic Swarm)",
-        execute: async ({ sessionID, prompt, delivery }) => {
-          const state = await runtime.factory.read()
-          if (!state) {
-            await ctx.session.synthetic({
-              sessionID,
-              text: "No factory run here yet — run /grill first.",
-            } as any)
-            return
-          }
-          await ctx.session.switchAgent({ sessionID, agent: "factory" } as any)
-          await ctx.session.prompt({
-            ...prompt,
-            sessionID,
-            text: `${await runtime.factory.summary(state)}\nContinue the factory run from its current stage.${prompt.text?.trim() ? `\nHuman note: ${prompt.text}` : ""}`,
-            delivery,
-          } as any)
-        },
-      })
-      editor.add({
-        name: "gates",
-        description: "Run the mechanical gates on changed files (Epistemic Swarm)",
-        execute: async ({ sessionID }) => {
-          const changed = (await git(runtime.root, ["status", "--porcelain=v1", "-uall"], { allowFail: true })).stdout
-            .split("\n")
-            .filter(Boolean)
-            .map((line) => line.slice(3).split(" -> ").at(-1)!)
-          const report = await runGates({
-            root: runtime.root,
-            scope: changed.length ? "touched" : "full",
-            touched: changed,
-            stateDir: runtime.stateDir,
-          })
-          await ctx.session.synthetic({ sessionID, text: formatReport(report) } as any)
-        },
-      })
-      editor.add({
-        name: "lsp",
-        description: "Language servers: configured, available and running (Epistemic Swarm)",
-        execute: async ({ sessionID }) => {
-          const status = await runtime.lsp.status()
-          const settings = await runtime.lsp.settings()
-          const lines = [status.enabled ? "LSP is on." : "LSP is disabled (lsp: false)."]
-          for (const server of settings.servers) {
-            const command = await runtime.lsp.command(server, runtime.root)
-            const running = status.running.filter((item) => item.id === server.id)
-            lines.push(
-              `${server.id} [${server.extensions.join(" ")}]: ${Array.isArray(command) ? `available (${command.join(" ")})` : command.unavailable}${running.length ? ` · running for ${running.length} root(s)` : ""}`,
-            )
-          }
-          lines.push(...status.diagnostics.map((item) => `! ${item}`))
-          await ctx.session.synthetic({ sessionID, text: lines.join("\n") } as any)
-        },
-      })
-      editor.add({
-        name: "hooks",
-        description: "Show the hook bridge: sources, handlers, trust and diagnostics (Epistemic Swarm)",
-        execute: async ({ sessionID }) => {
-          await bridge.engine.refresh()
-          const status = bridge.engine.status()
-          const trust =
-            status.projectHandlers === 0
-              ? "nothing to trust"
-              : status.trusted
-                ? "trusted"
-                : "NOT trusted: run /es-trust or `es trust`"
-          const lines = [
-            `Hook bridge: ${status.handlers} handler(s), ${status.projectHandlers} from the project (${trust}).`,
-            ...status.projectLines,
-            ...status.diagnostics.map((item) => `! ${item}`),
-            ...bridge.engine.recent.slice(-10).map((item) => `recent error: ${item}`),
-            "Stop hooks are emulated after the turn ends (advisory for plain chat).",
-          ]
-          await ctx.session.synthetic({ sessionID, text: lines.join("\n") } as any)
-        },
-      })
-      editor.add({
-        name: "status",
-        description: "Show the factory state (Epistemic Swarm)",
-        execute: async ({ sessionID }) => {
-          const state = await runtime.factory.read()
-          const liveness = await readLiveness(runtime.root, state)
-          const text = [await runtime.factory.summary(state), ...livenessLines(state, liveness)].join("\n")
-          await ctx.session.synthetic({ sessionID, text } as any)
-        },
-      })
-      editor.add({
-        name: "config",
-        description: "Show the effective Epistemic Swarm config and where it came from (Epistemic Swarm)",
-        execute: async ({ sessionID }) => {
-          const lines = [
-            runtime.configSources.length
-              ? `Layers: ${runtime.configSources.join(" → ")} → plugin options`
-              : "Layers: defaults only (no config files)",
-            ...runtime.warnings.map((warning) => `Warning: ${warning}`),
-            JSON.stringify(runtime.config, null, 2),
-          ]
-          await ctx.session.synthetic({ sessionID, text: lines.join("\n") } as any)
-        },
-      })
-      editor.add({
-        name: "research",
-        description: "Research stage: report, audit coverage and cached sources (Epistemic Swarm)",
-        execute: async ({ sessionID }) => {
-          const layout = factoryLayout(runtime.root)
-          const report = await readFile(layout.researchReport, "utf8").catch(() => undefined)
-          const coverage = await readJson<{
-            claims?: number
-            grounded?: number
-            untagged?: number
-            ungrounded?: number
-            malformed?: number
-            sources?: number
-            passed?: boolean
-          }>(path.join(layout.research, "coverage.json")).catch(() => undefined)
-          const sources = (await readdir(researchSourcesDir(runtime.root)).catch(() => [])).filter((file) =>
-            file.endsWith(".md"),
-          )
-          const lines = [
-            report === undefined
-              ? "No research report yet (.factory/research/REPORT.md)."
-              : `Report: ${report.length} characters in .factory/research/REPORT.md.`,
-            coverage
-              ? `Audit: ${coverage.grounded ?? 0}/${coverage.claims ?? 0} claims grounded (untagged ${coverage.untagged ?? 0}, ungrounded ${coverage.ungrounded ?? 0}, malformed ${coverage.malformed ?? 0}); cited sources ${coverage.sources ?? 0}; passed ${coverage.passed ? "yes" : "no"}.`
-              : "No coverage.json yet (es_research_complete writes it).",
-            `Cached sources: ${sources.length}.`,
-          ]
-          await ctx.session.synthetic({ sessionID, text: lines.join("\n") } as any)
-        },
-      })
+      const io: CommandSession = {
+        switchAgent: (sessionID, agent) => ctx.session.switchAgent({ sessionID, agent } as any),
+        sendPrompt: (sessionID, prompt, text, delivery) =>
+          ctx.session.prompt({ ...prompt, sessionID, text, delivery } as any),
+        synthetic: (sessionID, text) => ctx.session.synthetic({ sessionID, text } as any),
+      }
+      for (const spec of esCommandSpecs(io, runtime, bridge as unknown as CommandBridge)) editor.add(spec as any)
     })
 
     // Spend: per-step host cost for factory-agent sessions (estimated from tokens when cost is 0).
@@ -495,6 +550,10 @@ export default Plugin.define({
         // stream closed on unload
       }
     })()
+    // Language-server lifecycle (#275.1): servers stop here on plugin unload;
+    // between sessions only the manager's idle sweeper (600 s default) reaps
+    // them, so a long-lived server outlives its session by design. The running
+    // set stays visible through `/lsp` and the LSP panel.
     return async () => {
       abort.abort()
       if (queued) clearTimeout(queued)