@heretek-ai/epistemic-swarm 1.1.3 → 1.6.0

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "1.1.3",
+  "version": "1.6.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,16 +44,16 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@heretek-ai/es-core": "1.1.3",
+    "@heretek-ai/es-core": "1.6.0",
     "@opencode/plugin": "2.0.24"
   },
   "devDependencies": {
-    "@babel/core": "7.28.0",
+    "@babel/core": "7.29.6",
     "@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,61 @@ export function permissionRules(spec: AgentSpec, mcpServers: readonly string[]):
   return rules
 }
 
-function modelFor(spec: AgentSpec, options: PluginOptions) {
+export 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) }
+  if (!ref) return undefined
+  return parseModelRef(ref)
+}
+
+/** 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] ?? options.models?.[spec.tier]
+    if (ref === undefined) continue
+    const key = options.models?.agents?.[spec.id] !== undefined ? `models.agents.${spec.id}` : `models.${spec.tier}`
+    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

@@ -15,6 +15,7 @@ import {
   bwrapAvailable,
   fromOpenCode,
   HookEngine,
+  parseModelRef,
   permissionActionTool,
   shellQuote,
   toOpenCodeInput,
@@ -100,8 +101,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
     },
   })

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

@@ -74,6 +74,18 @@ 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)
+    }
     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_")) {

package/src/pr.ts

@@ -2,7 +2,7 @@
 // integration branch (never the base branch) and opens a draft PR for a human
 // to review and merge.
 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 +16,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 },

package/src/rpc.ts

@@ -1,7 +1,9 @@
-// Server side of the TUI previews. Human-only mutations (approve, trust,
-// resume) happen at a terminal with the passphrase-sealed key, never via RPC:
-// the TUI previews, then points at `es approve`, `es trust`, `es factory
-// resume`. Only lspInstall still mutates via a preview token.
+// Server side of the TUI previews. Approvals complete in the TUI process
+// (masked dialog, in-process signing, ADR 0002); trust and resume sign at a
+// terminal with the passphrase-sealed key. The TUI previews, then either
+// signs itself or points at `es trust` / `es factory resume`. No approve,
+// trust or resume call ever crosses RPC: only lspInstall still mutates via
+// a preview token.
 import { randomBytes } from "node:crypto"
 import {
   type ApprovalStage,
@@ -19,6 +21,7 @@ import {
   headline,
   installServer,
   isTrusted,
+  listBrainstormRuns,
   loadGatesConfig,
   readFrontier,
   readIdeas,
@@ -54,14 +57,14 @@ export function createRpcHandlers(
     tickets.set(token, { kind, subject: hashJson(subject), expires: Date.now() + TTL_MS })
     return token
   }
-  const redeem = (token: string, kind: string, subject: unknown) => {
+  const redeemHash = (token: string, kind: string, subjectHash: string) => {
     const ticket = tickets.get(token)
     tickets.delete(token)
     if (!ticket || ticket.kind !== kind || ticket.expires < Date.now())
       throw new Error("The confirmation expired or does not match; preview again.")
-    if (ticket.subject !== hashJson(subject))
-      throw new Error("What you confirmed changed since the preview; preview again.")
+    if (ticket.subject !== subjectHash) throw new Error("What you confirmed changed since the preview; preview again.")
   }
+  const redeem = (token: string, kind: string, subject: unknown) => redeemHash(token, kind, hashJson(subject))
   const refused = (context: any, error: unknown) =>
     context.error("refused", error instanceof Error ? error.message : String(error), {
       reason: error instanceof Error ? error.message : String(error),
@@ -181,14 +184,19 @@ export function createRpcHandlers(
       }
     },
     brainstormState: async () => {
-      const plan = await readPlan(runtime.root).catch(() => undefined)
-      if (!plan) return { active: false }
-      const ideas = await readIdeas(runtime.root).catch(() => [])
-      const scores = await readScores(runtime.root).catch(() => [])
-      const result = await readResult(runtime.root).catch(() => undefined)
+      const runs = await listBrainstormRuns(runtime.root).catch(() => [] as string[])
+      // The panel shows the default run, else the latest; every run stays one CLI call away.
+      const run = runs.includes("default") ? "default" : runs[runs.length - 1]
+      const plan = run ? await readPlan(runtime.root, run).catch(() => undefined) : undefined
+      if (!plan || !run) return { active: false, runs }
+      const ideas = await readIdeas(runtime.root, run).catch(() => [])
+      const scores = await readScores(runtime.root, run).catch(() => [])
+      const result = await readResult(runtime.root, run).catch(() => undefined)
       const survivors = ideas.filter((idea) => !idea.duplicateOf)
       return {
         active: true,
+        run,
+        runs,
         brief: plan.brief.idea,
         lenses: plan.lenses,
         ideas: survivors.length,
@@ -221,6 +229,9 @@ export function createRpcHandlers(
           ],
           problems: [],
           token: issue(`approve:${stage}`, subject.subject),
+          // ADR 0002 I3: the TUI signs only this subject; approveStage refuses a mismatch.
+          subjectHash: hashJson(subject.subject),
+          issuedAt: Date.now(),
         }
       } catch (error) {
         return {
@@ -231,6 +242,23 @@ export function createRpcHandlers(
         }
       }
     },
+    /**
+     * Validate-only redeem of an approval preview ticket (ADR 0002 I3): the
+     * TUI calls this exactly once before signing in-process. It enforces the
+     * 120 s TTL and single-use and checks the subject hash, but signs
+     * nothing — there is still no approve RPC (#49).
+     */
+    redeemApproval: async (input: unknown, context: any) => {
+      const { stage, token, subjectHash } = input as { stage: ApprovalStage; token: unknown; subjectHash: unknown }
+      try {
+        if (typeof token !== "string" || typeof subjectHash !== "string")
+          throw new Error("The confirmation expired or does not match; preview again.")
+        redeemHash(token, `approve:${stage}`, subjectHash)
+        return { ok: true }
+      } catch (error) {
+        return refused(context, error)
+      }
+    },
     previewTrust: async () => {
       const subject = await trustSubject()
       const trusted =