@heretek-ai/epistemic-swarm 1.1.4 → 2.3.0

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "1.1.4",
+  "version": "2.3.0",
+  "esRelease": {
+    "order": 3
+  },
   "description": "Epistemic Swarm: an AI build factory for OpenCode v2 — grill, research, spec, build, QA and release, gated mechanically.",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,7 +44,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@heretek-ai/es-core": "1.1.4",
+    "@heretek-ai/es-core": "2.3.0",
     "@opencode/plugin": "2.0.24"
   },
   "devDependencies": {
@@ -49,8 +52,8 @@
     "@babel/preset-typescript": "7.27.1",
     "@heretek-ai/es-testkit": "1.0.0",
     "@opencode/sdk": "2.0.24",
-    "@opentui/core": "0.5.14",
-    "@opentui/solid": "0.5.14",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
     "babel-preset-solid": "1.9.12",
     "solid-js": "1.9.15"
   },

package/src/agents.ts

@@ -2,7 +2,7 @@
 // we add our own agents and never edit built-ins, default_agent or models.
 // Per-agent tool/skill/MCP scoping is expressed as wildcard-deny permission
 // rules (proven in M0: denied tools, MCP tools and skills are not advertised).
-import { AGENTS, type AgentSpec, ALL_ES_TOOLS, loadPrompt } from "@heretek-ai/es-core"
+import { AGENTS, type AgentSpec, ALL_ES_TOOLS, loadPrompt, parseModelRef } from "@heretek-ai/es-core"
 import type { PluginOptions } from "./runtime.ts"
 
 export interface CompiledAgent {
@@ -47,11 +47,82 @@ export function permissionRules(spec: AgentSpec, mcpServers: readonly string[]):
   return rules
 }
 
-function modelFor(spec: AgentSpec, options: PluginOptions) {
-  const ref = options.models?.agents?.[spec.id] ?? options.models?.[spec.tier]
-  const slash = ref?.indexOf("/") ?? -1
-  if (!ref || slash <= 0) return undefined
-  return { providerID: ref.slice(0, slash), id: ref.slice(slash + 1) }
+export function modelFor(spec: AgentSpec, options: PluginOptions) {
+  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
+  /** The config key to fix: models.<tier> or models.agents.<id>. */
+  readonly key: string
+  readonly ref: string
+  /** Remediation for the user (es config set is human-only). */
+  readonly message: string
+}
+
+/** Remediation text for an unusable seat model (es config set is human-only). */
+export function modelProblemMessage(agent: string, key: string, ref: string, wellFormed: boolean): string {
+  return (
+    `Seat "${agent}" cannot launch: its model "${ref}" (${key}) is ` +
+    (wellFormed ? "not on this host." : 'malformed (want "provider/model").') +
+    ` Set ${key} to "provider/model" from the host model list with \`es config set\`, or unset it to use the session default.`
+  )
+}
+
+/** Every configured ref, per seat, that `exists` cannot find on the host. */
+export function modelProblems(
+  options: PluginOptions,
+  specs: readonly AgentSpec[],
+  exists: (providerID: string, modelID: string) => boolean,
+): ModelProblem[] {
+  const problems: ModelProblem[] = []
+  for (const spec of specs) {
+    const ref = options.models?.agents?.[spec.id] ?? roleModel(spec.id, options) ?? options.models?.[spec.tier]
+    if (ref === undefined) continue
+    const key = modelKey(spec, options)
+    const parsed = parseModelRef(ref)
+    if (parsed === undefined || !exists(parsed.providerID, parsed.id))
+      problems.push({
+        agent: spec.id,
+        key,
+        ref,
+        message: modelProblemMessage(spec.id, key, ref, parsed !== undefined),
+      })
+  }
+  return problems
+}
+
+/** es_status lines for the runtime's model problems (empty when healthy). */
+export function modelProblemLines(problems: ReadonlyMap<string, ModelProblem>): string[] {
+  if (problems.size === 0) return []
+  return [
+    `Model problems (${problems.size}): configured models missing on this host — those seats refuse to launch.`,
+    ...[...problems.values()].map((problem) => `- ${problem.message}`),
+  ]
 }
 
 export async function compileAgents(options: PluginOptions, mcpServers: readonly string[]): Promise<CompiledAgent[]> {

package/src/approve-tui.ts

@@ -0,0 +1,124 @@
+// In-TUI approval signing (#119, ADR 0002). The TUI process runs on the
+// human's machine, so it unlocks the sealed key and signs in-process through
+// the core approveStage service — no passphrase and no approval ever cross
+// RPC (the #49 property still holds: there is no approve RPC). Trust, waive
+// and resume keep routing to the terminal (ADR 0002 I7).
+import { userInfo } from "node:os"
+import {
+  type Approval,
+  type ApprovalStage,
+  approveStage,
+  checkApprovalAttempts,
+  stateDir as defaultStateDir,
+  exists,
+  factoryLayout,
+  HumanKeyError,
+  hasHumanKey,
+  noteApprovalSuccess,
+  noteWrongPassphrase,
+  unlockHumanKey,
+  zeroCodepoints,
+} from "@heretek-ai/es-core"
+
+export interface ApproveTuiInput {
+  readonly root: string
+  readonly stage: ApprovalStage
+  /** ADR 0002 I3: hashJson of the previewed subject, from previewApproval. */
+  readonly expectedSubjectHash: string
+  readonly approvedBy?: string
+  readonly stateDir?: string
+  /**
+   * ADR 0002 I3: the preview ticket redeemed exactly once before signing
+   * (single-use + 120 s TTL). Production passes the token from
+   * previewApproval and a redeem that calls the validate-only
+   * `redeemApproval` RPC (it signs nothing); tests script the ticket map.
+   */
+  readonly previewToken?: string
+  /** `issuedAt` from previewApproval; a preview older than 120 s is refused. */
+  readonly previewIssuedAt?: number
+  /** Validate-only redeem of the preview token (signs nothing). */
+  readonly redeemPreview?: (token: string) => Promise<void>
+  /** Clock override (tests). */
+  readonly now?: () => number
+  /**
+   * The masked passphrase dialog (production: readMaskedPassphrase over
+   * dialog.show; tests: a scripted function). Resolves to the entered code
+   * points, or undefined on cancel. The array is zeroed by the caller.
+   */
+  readonly readPassphrase: (title: string) => Promise<string[] | undefined>
+}
+
+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 cancelled: true }
+
+const TERMINAL_FALLBACK = (stage: ApprovalStage) =>
+  `Run \`es approve ${stage}\` at a terminal with your passphrase (approvals need the sealed human key).`
+
+/** ADR 0002 I3: a preview older than this is refused instead of signed. */
+export const APPROVAL_PREVIEW_TTL_MS = 120_000
+
+/**
+ * Complete a frontier/spec approval inside the TUI: throttle check, masked
+ * passphrase loop, unlock, preview-ticket redeem, approveStage with channel
+ * "tui" and the preview's subject hash, key destruction. Returns a fallback when this TUI cannot
+ * sign (remote attach without the project root or sealed key): the caller
+ * shows the terminal alert. ApprovalError (subject changed since preview),
+ * an expired or already-used preview, and unexpected failures propagate to
+ * the caller's guard.
+ */
+export async function approveInTui(input: ApproveTuiInput): Promise<ApproveTuiOutcome> {
+  const dir = input.stateDir ?? defaultStateDir()
+  // 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.
+  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}`
+  for (;;) {
+    const codepoints = await input.readPassphrase(title)
+    if (codepoints === undefined) 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("")
+    zeroCodepoints(codepoints)
+    try {
+      const signer = await unlockHumanKey(passphrase, dir)
+      try {
+        // ADR 0002 I3: the preview ticket is redeemed exactly once, after
+        // the unlock (a typo must not consume it) and before anything is
+        // signed. An expired or already-used preview refuses here.
+        const now = input.now ?? Date.now
+        if (input.previewIssuedAt !== undefined && now() - input.previewIssuedAt > APPROVAL_PREVIEW_TTL_MS)
+          throw new Error("The approval preview expired (> 120 s old); preview again.")
+        if (input.previewToken !== undefined && input.redeemPreview !== undefined)
+          await input.redeemPreview(input.previewToken)
+        await noteApprovalSuccess(dir)
+        const { record } = await approveStage(input.root, {
+          stage: input.stage,
+          channel: "tui",
+          signer,
+          ...(input.approvedBy ? { approvedBy: input.approvedBy } : {}),
+          stateDir: dir,
+          expectedSubjectHash: input.expectedSubjectHash,
+        })
+        return { ok: true, record }
+      } finally {
+        signer.destroy()
+      }
+    } 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 }
+        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
@@ -15,6 +18,7 @@ import {
   bwrapAvailable,
   fromOpenCode,
   HookEngine,
+  parseModelRef,
   permissionActionTool,
   shellQuote,
   toOpenCodeInput,
@@ -100,8 +104,7 @@ export async function createHookBridge(
     root: runtime.root,
     stateDir: runtime.stateDir,
     generate: async (prompt, model) => {
-      const slash = model?.indexOf("/") ?? -1
-      const ref = model && slash > 0 ? { providerID: model.slice(0, slash), id: model.slice(slash + 1) } : undefined
+      const ref = model ? parseModelRef(model) : undefined
       return (await ctx.generate.text({ prompt, ...(ref ? { model: ref } : {}) })).text
     },
   })
@@ -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/masked-input.tsx

@@ -0,0 +1,123 @@
+// Masked passphrase input for the OpenCode TUI (#119, from the #118 spike
+// verdict GO). A custom dialog.show component: keystrokes are captured with
+// no echo and plaintext lives only in a closure-scoped array (never in
+// reactive state), zeroed on submit and on cancel. Only the bullet count is
+// reactive (screen-equivalent: the bullets are visible anyway).
+
+import { zeroCodepoints } from "@heretek-ai/es-core"
+import { useKeyboard, usePaste } from "@opentui/solid"
+import { createSignal, onCleanup } from "solid-js"
+
+export interface MaskedInputOptions {
+  readonly title: string
+  readonly onSubmit: (codepoints: string[]) => void
+  readonly onCancel: () => void
+}
+
+export function MaskedInput(props: MaskedInputOptions) {
+  // The ONLY place plaintext lives: a plain closure array, not reactive state.
+  const codepoints: string[] = []
+  const [count, setCount] = createSignal(0)
+  const [cancelled, setCancelled] = createSignal(false)
+  let done = false
+
+  const finish = (submit: boolean) => {
+    if (done) return
+    done = true
+    try {
+      if (submit) props.onSubmit(codepoints)
+      else props.onCancel()
+    } finally {
+      zeroCodepoints(codepoints)
+      setCount(0)
+    }
+  }
+  onCleanup(() => {
+    zeroCodepoints(codepoints)
+    setCount(0)
+  })
+
+  useKeyboard((key) => {
+    if (done) return
+    if (key.name === "return" || key.name === "enter") {
+      key.preventDefault()
+      key.stopPropagation()
+      finish(true)
+      return
+    }
+    if (key.name === "escape" || (key.name === "c" && key.ctrl)) {
+      key.preventDefault()
+      key.stopPropagation()
+      setCancelled(true)
+      finish(false)
+      return
+    }
+    if (key.name === "backspace") {
+      key.preventDefault()
+      key.stopPropagation()
+      if (codepoints.length > 0) {
+        codepoints.pop()
+        setCount(codepoints.length)
+      }
+      return
+    }
+    // Printable characters only; everything else is consumed so it never
+    // reaches the TUI keymap layer underneath the dialog.
+    if (!key.ctrl && !key.meta && key.sequence && [...key.sequence].length === 1) {
+      key.preventDefault()
+      key.stopPropagation()
+      for (const point of key.sequence) codepoints.push(point)
+      setCount(codepoints.length)
+      return
+    }
+    key.preventDefault()
+    key.stopPropagation()
+  })
+
+  usePaste((event) => {
+    if (done) return
+    event.preventDefault()
+    event.stopPropagation()
+    // Bracketed paste arrives as one event: accept it atomically, strip newlines.
+    const text = new TextDecoder().decode(event.bytes).replace(/[\r\n]+/g, "")
+    if (text) {
+      for (const point of text) codepoints.push(point)
+      setCount(codepoints.length)
+    }
+  })
+
+  return (
+    <box flexDirection="column" padding={1} gap={1}>
+      <text>{props.title}</text>
+      <text>{cancelled() ? "Cancelled." : `Passphrase: ${"•".repeat(count())}`}</text>
+      <text>Enter submits · Esc cancels · paste accepted as one unit</text>
+    </box>
+  )
+}
+
+/** The dialog surface the masked input needs (structural: scriptable in tests). */
+export interface MaskedDialog {
+  show(render: () => unknown, onClose?: () => void): void
+  clear(): void
+}
+
+/**
+ * Open the masked dialog and resolve to the entered code points, or
+ * undefined on cancel. The caller copies, uses and zeroes them; the
+ * component zeroes its own buffer on submit/cancel/unmount.
+ */
+export function readMaskedPassphrase(dialog: MaskedDialog, title: string): Promise<string[] | undefined> {
+  return new Promise((resolve) => {
+    let settled = false
+    const done = (codepoints: string[] | undefined) => {
+      if (settled) return
+      settled = true
+      dialog.clear()
+      resolve(codepoints === undefined ? undefined : [...codepoints])
+    }
+    dialog.show(
+      () => <MaskedInput title={title} onSubmit={(codepoints) => done(codepoints)} onCancel={() => done(undefined)} />,
+      () => done(undefined),
+    )
+  })
+}

package/src/panels.tsx

@@ -127,8 +127,8 @@ const FactoryPanel = (props: PanelProps) => {
             </Show>
             <Show when={data().pending.length}>
               <text>
-                Waiting on you: approve {data().pending.join(", ")}: run `es approve {data().pending[0]}` in a terminal
-                (/es-approve previews it)
+                Waiting on you: approve {data().pending.join(", ")} with /es-approve (or `es approve {data().pending[0]}
+                `)
               </text>
             </Show>
             <Show when={data().seats.length}>
@@ -255,6 +255,11 @@ const BrainstormPanel = (props: PanelProps) => {
         {(data: () => any) => (
           <Show when={data().active} fallback={<text>No brainstorm in .factory/brainstorm yet. Run /brainstorm.</text>}>
             <text>Brief: {data().brief}</text>
+            <Show when={data().runs?.length > 1}>
+              <text>
+                Run {data().run} ({data().runs.length} runs: {data().runs.join(", ")} — `es brainstorm show [run]`)
+              </text>
+            </Show>
             <text>
               {data().ideas} idea(s) · {data().duplicates} duplicate(s) · {data().scored} scored ·{" "}
               {data().complete ? "complete" : "in progress"}

package/src/policy.ts

@@ -22,7 +22,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"])
 
@@ -74,16 +74,35 @@ export function createPolicyHooks(runtime: Runtime, seats?: SeatTracker) {
   const before = async (event: { tool: string; agent: string; id: string; sessionID?: string; input: unknown }) => {
     const seat = seatOf(event.agent)
     const input = (event.input ?? {}) as Record<string, any>
+    // Fail-closed models (#96): a seat whose own configured model is missing
+    // on the host is refused on every tool call, with remediation. Primary
+    // seats are never launched through `subagent`, so the launch guard below
+    // never sees them; without this they would silently run on the default.
+    const ownProblem = runtime.modelProblems?.get(event.agent)
+    if (ownProblem) deny(ownProblem.message)
+    // Fail-closed models (#96): whoever launches a seat with an unusable
+    // model is refused, seat or user agent alike.
+    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.`)
@@ -162,7 +181,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)
@@ -210,6 +232,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,8 +1,12 @@
-// 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 { git, run } from "@heretek-ai/es-core"
+import { buildPrArgs, git, run } from "@heretek-ai/es-core"
 
 export const ghPrOpener: PrOpener = {
   id: "gh",
@@ -16,17 +20,17 @@ export const ghPrOpener: PrOpener = {
     const remote = await git(root, ["remote", "get-url", "origin"], { allowFail: true })
     return remote.code === 0
   },
-  async open({ root, branch, base, title, body }) {
+  async open({ root, branch, base, title, body, preset }) {
     if (branch === base || !branch.startsWith("factory/")) throw new Error(`refusing to push "${branch}"`)
+    // One argv builder for every opener; it refuses an off-base preset run
+    // (e.g. --base main) before anything is pushed.
+    const argv = buildPrArgs({ branch, base, title, body, preset })
     await git(root, ["push", "--set-upstream", "origin", `${branch}:${branch}`])
-    const created = await run(
-      ["gh", "pr", "create", "--draft", "--head", branch, "--base", base, "--title", title, "--body", body],
-      {
-        cwd: root,
-        timeoutMs: 60_000,
-        passEnv: ["GH_TOKEN", "GITHUB_TOKEN", "GH_HOST"],
-      },
-    )
+    const created = await run(argv, {
+      cwd: root,
+      timeoutMs: 60_000,
+      passEnv: ["GH_TOKEN", "GITHUB_TOKEN", "GH_HOST"],
+    })
     const url = created.stdout
       .trim()
       .split("\n")

package/src/research.ts

@@ -4,7 +4,7 @@
 // .factory/ directory: the user's own agents get plain results, and no
 // project gains a .factory/ because someone searched the web.
 import { stat } from "node:fs/promises"
-import { factoryLayout, researchCache, seatOf, selectProvider } from "@heretek-ai/es-core"
+import { factoryLayout, researchCache, SEARCH_PROVIDERS, seatOf, selectProvider } from "@heretek-ai/es-core"
 import type { Runtime } from "./runtime.ts"
 
 interface SearchHit {
@@ -52,7 +52,14 @@ export function registerWebsearch(
 ) {
   const searxng = runtime.config.research?.searxngUrl
   const env = searxng ? { ...process.env, SEARXNG_URL: searxng } : process.env
-  const provider = selectProvider(runtime.options.searchProvider, env)
+  // A legacy searchProvider pin keeps its exact behaviour; otherwise the
+  // first configured backend with a host search provider wins (#106).
+  const ordered = runtime.config.research?.backends
+    ?.map((id) => SEARCH_PROVIDERS.find((provider) => provider.id === id))
+    .find((provider) => provider?.available(env))
+  const provider = runtime.options.searchProvider
+    ? selectProvider(runtime.options.searchProvider, env)
+    : (ordered ?? selectProvider(undefined, env))
   if (!provider) return
   editor.add({
     id: "epistemic-swarm",

package/src/rpc-def.ts

@@ -1,7 +1,9 @@
 // RPC contract between the server plugin and the TUI. Previews are shown in
-// the TUI; human-only mutations (approve, trust, resume) happen at a terminal
-// with the passphrase (`es approve`, `es trust`, `es factory resume`), never
-// through an agent tool or RPC. Only lspInstall still mutates via RPC.
+// the TUI; approvals complete there through the masked dialog and in-process
+// signing (ADR 0002), while trust and resume sign at a terminal with the
+// passphrase (`es trust`, `es factory resume`). No approve, trust or resume
+// call ever crosses RPC: there is no mutating approval RPC for an agent tool
+// or a stolen server password to call. Only lspInstall still mutates via RPC.
 import { Rpc } from "@opencode/plugin/rpc"
 
 const obj = (properties: Record<string, unknown>, required: string[] = []) => ({
@@ -12,13 +14,22 @@ const obj = (properties: Record<string, unknown>, required: string[] = []) => ({
 })
 const str = { type: "string" }
 const strArray = { type: "array", items: str }
+const num = { type: "number" }
 
-const Preview = obj({ ok: { type: "boolean" }, title: str, lines: strArray, problems: strArray, token: str }, [
-  "ok",
-  "title",
-  "lines",
-  "problems",
-])
+const Preview = obj(
+  {
+    ok: { type: "boolean" },
+    title: str,
+    lines: strArray,
+    problems: strArray,
+    token: str,
+    /** ADR 0002 I3: hashJson of the previewed approval subject (present on approval previews). */
+    subjectHash: str,
+    /** ADR 0002 I3: when the preview was issued (present on approval previews). */
+    issuedAt: num,
+  },
+  ["ok", "title", "lines", "problems"],
+)
 
 export const EsRpc = Rpc.define({
   id: "epistemic-swarm",
@@ -42,6 +53,16 @@ export const EsRpc = Rpc.define({
       input: obj({ stage: { type: "string", enum: ["frontier", "spec"] } }, ["stage"]),
       output: Preview,
     },
+    /** Validate-only redeem of an approval preview ticket: single-use + TTL, signs nothing. */
+    redeemApproval: {
+      input: obj({ stage: { type: "string", enum: ["frontier", "spec"] }, token: str, subjectHash: str }, [
+        "stage",
+        "token",
+        "subjectHash",
+      ]),
+      output: obj({ ok: { type: "boolean" } }, ["ok"]),
+      errors: { refused: obj({ reason: str }, ["reason"]) },
+    },
     previewTrust: { input: obj({}), output: Preview },
     previewResume: { input: obj({}), output: Preview },
     previewLspInstall: { input: obj({ id: str }, ["id"]), output: Preview },