opencode-arbiter 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# opencode-arbiter
+
+Local-first model router for [OpenCode](https://opencode.ai). This package ships two things:
+
+- the **`arbiter` CLI**, which installs and runs the router server, and
+- the **Notary plugin**, the OpenCode-side UI (plan-mode menu, overrides, correction logging).
+
+Routing lives entirely in the server; the plugin is UI and logging only — it never calls a
+model directly.
+
+## Install
+
+```bash
+npm install -g opencode-arbiter
+arbiter setup     # download + install the server, create a venv, patch OpenCode config
+arbiter start     # run the router on 127.0.0.1:4317
+```
+
+`setup` needs Python 3.11+ on your PATH (used for a CPU-only PyTorch venv). Point OpenCode's
+provider `baseUrl` at the router and it decides local (Ollama) vs cloud per task.
+
+## CLI
+
+| Command | Does |
+|---|---|
+| `arbiter setup`  | Downloads the server bundle + classifier checkpoint for this package version, verifies checksums, creates `~/.arbiter/.venv`, installs deps, patches OpenCode config. |
+| `arbiter start`  | Starts the server detached, writes `~/.arbiter/server.pid`. |
+| `arbiter stop`   | Stops the running server. |
+| `arbiter status` | Reports running/stopped and the server's `/health`. |
+
+Env: `ARBITER_HOST`, `ARBITER_PORT`, `ARBITER_RELEASE_REPO`, `OPENCODE_CONFIG`.
+
+## Plugin
+
+OpenCode loads the `.ts` plugin directly (no build step). Add the entrypoint to your OpenCode
+config's `plugin` array:
+
+```jsonc
+// ~/.config/opencode/opencode.json
+{ "plugin": ["opencode-arbiter/src/index.ts"] }
+```
+
+`/train-mode` toggles manual approval. **Manual** (default) shows each resolution as an
+accept/override menu and feeds the correction loop; **auto** passes decisions straight through
+and only logs them.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck
+npm test
+```

package/bin/arbiter.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+// opencode-arbiter CLI: setup / start / stop / status.
+// Pure Node, cross-platform (Linux + macOS + Windows). No shell-outs for file ops or downloads.
+
+import { createHash } from "node:crypto";
+import { spawn, execFile } from "node:child_process";
+import { createWriteStream, createReadStream, existsSync } from "node:fs";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { x as tarExtract } from "tar";
+
+const execFileAsync = promisify(execFile);
+
+// --- constants ---------------------------------------------------------------
+
+const HOME = join(homedir(), ".arbiter");
+const SERVER_DIR = join(HOME, "server");
+const VENV_DIR = join(HOME, ".venv");
+const PID_FILE = join(HOME, "server.pid");
+const CHECKPOINT_REL = join("triage", "weights", "checkpoint.pt");
+
+const HOST = process.env.ARBITER_HOST || "127.0.0.1";
+const PORT = process.env.ARBITER_PORT || "4317";
+
+// Where release assets live. Override with ARBITER_RELEASE_REPO=owner/repo.
+const RELEASE_REPO = process.env.ARBITER_RELEASE_REPO || "Penitant/arbiter-release";
+
+const IS_WIN = platform() === "win32";
+
+// --- tiny logger -------------------------------------------------------------
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+const log = (...a) => console.log(...a);
+const step = (s) => log(c.cyan("›"), s);
+const ok = (s) => log(c.green("✓"), s);
+const fail = (s) => { console.error(c.red("✗"), s); process.exitCode = 1; };
+
+// --- version -----------------------------------------------------------------
+
+async function pkgVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const raw = await readFile(join(here, "..", "package.json"), "utf8");
+  return JSON.parse(raw).version;
+}
+
+// --- github release asset download -------------------------------------------
+
+function assetUrl(tag, name) {
+  return `https://github.com/${RELEASE_REPO}/releases/download/${tag}/${name}`;
+}
+
+async function download(url, dest) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok || !res.body) {
+    throw new Error(`download failed (${res.status}) for ${url}`);
+  }
+  await mkdir(dirname(dest), { recursive: true });
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+}
+
+async function fetchText(url) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`fetch failed (${res.status}) for ${url}`);
+  return res.text();
+}
+
+async function sha256File(path) {
+  const hash = createHash("sha256");
+  await pipeline(createReadStream(path), hash);
+  return hash.digest("hex");
+}
+
+// A .sha256 file may be "<hex>" or "<hex>  filename"; take the first field.
+function parseChecksum(text) {
+  return text.trim().split(/\s+/)[0].toLowerCase();
+}
+
+// --- python discovery --------------------------------------------------------
+
+async function findPython() {
+  const candidates = IS_WIN ? ["python", "python3"] : ["python3", "python"];
+  for (const bin of candidates) {
+    try {
+      const { stdout } = await execFileAsync(bin, ["--version"]);
+      if (/Python 3\.(1[1-9]|[2-9]\d)/.test(stdout)) return bin;
+    } catch {
+      // try next candidate
+    }
+  }
+  throw new Error(
+    "no suitable Python found. Install Python 3.11+ and put `python3` (or `python`) on PATH.",
+  );
+}
+
+function venvBin(name) {
+  return IS_WIN
+    ? join(VENV_DIR, "Scripts", `${name}.exe`)
+    : join(VENV_DIR, "bin", name);
+}
+
+// --- opencode config patch ---------------------------------------------------
+
+function opencodeConfigPath() {
+  if (process.env.OPENCODE_CONFIG) return process.env.OPENCODE_CONFIG;
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(xdg, "opencode", "opencode.json");
+}
+
+async function patchOpencodeConfig() {
+  const path = opencodeConfigPath();
+  const baseURL = `http://${HOST}:${PORT}/v1`;
+  let cfg = {};
+  if (existsSync(path)) {
+    try {
+      cfg = JSON.parse(await readFile(path, "utf8"));
+    } catch {
+      log(c.red("!"), `could not parse ${path}. Add this provider manually:`);
+      log(c.dim(`    provider.arbiter.options.baseURL = "${baseURL}"`));
+      return;
+    }
+  }
+  cfg.provider ??= {};
+  cfg.provider.arbiter = {
+    npm: "@ai-sdk/openai-compatible",
+    name: "Arbiter (local router)",
+    ...cfg.provider.arbiter,
+    options: { ...(cfg.provider.arbiter?.options || {}), baseURL },
+  };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(cfg, null, 2) + "\n");
+  ok(`patched OpenCode config ${c.dim(path)} → baseURL ${baseURL}`);
+}
+
+// --- commands ----------------------------------------------------------------
+
+async function cmdSetup() {
+  const version = await pkgVersion();
+  const tag = `v${version}`;
+  log(`Setting up Arbiter ${c.cyan(tag)} into ${c.dim(HOME)}\n`);
+  await mkdir(HOME, { recursive: true });
+
+  const tarName = `arbiter-server-${tag}.tar.gz`;
+  const tarPath = join(HOME, tarName);
+
+  step("downloading server bundle…");
+  await download(assetUrl(tag, tarName), tarPath);
+  const publishedTarSum = parseChecksum(await fetchText(assetUrl(tag, `${tarName}.sha256`)));
+  const actualTarSum = await sha256File(tarPath);
+  if (actualTarSum !== publishedTarSum) {
+    throw new Error(`server bundle checksum mismatch (got ${actualTarSum}, expected ${publishedTarSum})`);
+  }
+  ok("server bundle verified");
+
+  step("extracting server…");
+  await rm(SERVER_DIR, { recursive: true, force: true });
+  await mkdir(SERVER_DIR, { recursive: true });
+  // The tarball's top-level entry is `server/`; strip it so files land directly in SERVER_DIR.
+  await tarExtract({ file: tarPath, cwd: SERVER_DIR, strip: 1 });
+  ok("server extracted");
+
+  step("downloading classifier checkpoint…");
+  const ckptPath = join(SERVER_DIR, CHECKPOINT_REL);
+  await download(assetUrl(tag, "checkpoint.pt"), ckptPath);
+  const publishedCkptSum = parseChecksum(await fetchText(assetUrl(tag, "checkpoint.pt.sha256")));
+  const actualCkptSum = await sha256File(ckptPath);
+  if (actualCkptSum !== publishedCkptSum) {
+    await rm(ckptPath, { force: true });
+    throw new Error(`checkpoint checksum mismatch (got ${actualCkptSum}, expected ${publishedCkptSum})`);
+  }
+  ok("checkpoint verified");
+
+  step("creating Python virtualenv…");
+  const python = await findPython();
+  await execFileAsync(python, ["-m", "venv", VENV_DIR]);
+  ok(`virtualenv at ${c.dim(VENV_DIR)} (${python})`);
+
+  step("installing server dependencies (CPU torch — can take a few minutes)…");
+  const pip = venvBin("pip");
+  await execFileAsync(pip, ["install", "--upgrade", "pip"], { maxBuffer: 1 << 26 });
+  await execFileAsync(
+    pip,
+    [
+      "install",
+      "--extra-index-url", "https://download.pytorch.org/whl/cpu",
+      "fastapi>=0.115",
+      "uvicorn[standard]>=0.30",
+      "httpx>=0.27",
+      "torch>=2.4",
+      "transformers>=4.44,<5",
+    ],
+    { maxBuffer: 1 << 26 },
+  );
+  ok("dependencies installed");
+
+  step("patching OpenCode config…");
+  await patchOpencodeConfig();
+
+  log(`\n${c.green("Done.")} Start the server with ${c.cyan("arbiter start")}.`);
+}
+
+async function readPid() {
+  try {
+    const pid = parseInt(await readFile(PID_FILE, "utf8"), 10);
+    return Number.isInteger(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM"; // exists but owned by someone else
+  }
+}
+
+async function cmdStart() {
+  const existing = await readPid();
+  if (existing && isAlive(existing)) {
+    ok(`already running (pid ${existing}) on ${HOST}:${PORT}`);
+    return;
+  }
+  if (!existsSync(SERVER_DIR)) {
+    throw new Error(`server not installed. Run ${c.cyan("arbiter setup")} first.`);
+  }
+  const python = venvBin("python");
+  const child = spawn(
+    python,
+    ["-m", "uvicorn", "main:app", "--host", HOST, "--port", PORT],
+    { cwd: SERVER_DIR, detached: true, stdio: "ignore", windowsHide: true },
+  );
+  child.unref();
+  await writeFile(PID_FILE, String(child.pid) + "\n");
+  ok(`started (pid ${child.pid}) on http://${HOST}:${PORT}`);
+}
+
+async function cmdStop() {
+  const pid = await readPid();
+  if (!pid) {
+    log("not running (no pid file).");
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    ok(`stopped (pid ${pid}).`);
+  } catch (e) {
+    if (e.code === "ESRCH") log(`process ${pid} was not running.`);
+    else throw e;
+  } finally {
+    await rm(PID_FILE, { force: true });
+  }
+}
+
+async function cmdStatus() {
+  const pid = await readPid();
+  if (!pid || !isAlive(pid)) {
+    log(c.red("● stopped"));
+    return;
+  }
+  log(c.green("● running"), c.dim(`pid ${pid} — http://${HOST}:${PORT}`));
+  try {
+    const res = await fetch(`http://${HOST}:${PORT}/health`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    log("  /health:", JSON.stringify(await res.json()));
+  } catch {
+    log("  /health: unreachable (server starting or bound elsewhere)");
+  }
+}
+
+// --- dispatch ----------------------------------------------------------------
+
+const HELP = `opencode-arbiter — local-first model router for OpenCode
+
+Usage: arbiter <command>
+
+  setup    download + install the server, create a venv, patch OpenCode config
+  start    start the server (detached) on ${HOST}:${PORT}
+  stop     stop the running server
+  status   show whether the server is running + /health
+
+Env: ARBITER_HOST, ARBITER_PORT, ARBITER_RELEASE_REPO, OPENCODE_CONFIG`;
+
+const commands = { setup: cmdSetup, start: cmdStart, stop: cmdStop, status: cmdStatus };
+
+async function main() {
+  const cmd = process.argv[2];
+  if (!cmd || cmd === "-h" || cmd === "--help") return void log(HELP);
+  const handler = commands[cmd];
+  if (!handler) return fail(`unknown command "${cmd}"\n\n${HELP}`);
+  try {
+    await handler();
+  } catch (e) {
+    fail(e.message || String(e));
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "opencode-arbiter",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Local-first model router for OpenCode: per-task local (Ollama) vs cloud routing, with tier-scaled context handoff on model switches.",
+  "keywords": ["opencode", "ollama", "llm", "router", "plugin", "local-first"],
+  "license": "MIT",
+  "homepage": "https://github.com/Penitant/arbiter-release",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Penitant/arbiter-release.git"
+  },
+  "bin": {
+    "arbiter": "bin/arbiter.js"
+  },
+  "main": "src/index.ts",
+  "files": [
+    "bin/",
+    "src/",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types src/*.test.ts"
+  },
+  "dependencies": {
+    "tar": "^7.4.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.10",
+    "@types/node": "^22.20.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,78 @@
+// HTTP client for the Server's Notary contract; fails soft so a down Server never blocks the session.
+
+/** The resolved proposal the Server returns from POST /classify. */
+export interface Decision {
+  difficulty: "easy" | "medium" | "hard";
+  confidence: number;
+  tier: "local-simple" | "cloud-mid" | "cloud-heavy";
+  model: string; // "provider/id", e.g. "google/gemini-2.5-pro"
+  reasoning_effort: string | null;
+  reason: string;
+}
+
+export interface ClassifyRequest {
+  task_text: string;
+  session_id?: string;
+  context_tokens_estimate?: number;
+}
+
+/** One logged resolution — accepted or overridden. */
+export interface Correction {
+  task_text: string;
+  predicted_tier: string;
+  predicted_model: string;
+  confidence: number;
+  session_id: string;
+  corrected_tier?: string | null;
+  corrected_model?: string | null;
+}
+
+const DEFAULT_BASE_URL = "http://127.0.0.1:4317";
+
+export class ServerClient {
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+
+  constructor(baseUrl?: string, timeoutMs = 4000) {
+    // ARBITER_SERVER_URL overrides the default localhost host/port.
+    this.baseUrl = (
+      baseUrl ?? process.env.ARBITER_SERVER_URL ?? DEFAULT_BASE_URL
+    ).replace(/\/+$/, "");
+    this.timeoutMs = timeoutMs;
+  }
+
+  /** Resolve a proposal for a task; null on any failure (caller falls back silently). */
+  async classify(req: ClassifyRequest): Promise<Decision | null> {
+    try {
+      const resp = await this.post("/classify", req);
+      if (!resp.ok) return null; // includes 503 -> documented soft fallback
+      return (await resp.json()) as Decision;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Log a resolution. Best-effort: errors are swallowed, never disrupting the session. */
+  async logCorrection(c: Correction): Promise<void> {
+    try {
+      await this.post("/corrections", c);
+    } catch {
+      /* swallow — logging is never allowed to disrupt the session */
+    }
+  }
+
+  private async post(path: string, body: unknown): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/commands.ts

@@ -0,0 +1,29 @@
+// /train-mode toggle: manual (proposals shown) vs auto (logged silently). In-memory, per-process.
+
+export const TRAIN_MODE_COMMAND = "train-mode";
+
+function defaultManual(): boolean {
+  // Default manual ON; set ARBITER_TRAIN_MODE=auto (or off/0) to start in auto mode.
+  const v = (process.env.ARBITER_TRAIN_MODE ?? "manual").toLowerCase();
+  return !["auto", "off", "0", "false", "no"].includes(v);
+}
+
+let manual = defaultManual();
+
+/** True when proposals should be shown for accept/override (manual approval). */
+export function isManualMode(): boolean {
+  return manual;
+}
+
+/** Flip the mode and return the new state. */
+export function toggleManualMode(): boolean {
+  manual = !manual;
+  return manual;
+}
+
+/** Human-readable one-liner for a toast after toggling. */
+export function modeMessage(on: boolean): string {
+  return on
+    ? "Arbiter train-mode ON — proposals shown for accept/override."
+    : "Arbiter train-mode OFF — routing automatic, decisions logged silently.";
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+// Notary plugin: plan-mode menu, override handling, correction logging. UI only — no routing logic.
+
+import type { Plugin } from "@opencode-ai/plugin";
+
+import { ServerClient, type Correction, type Decision } from "./client.js";
+import { type Proposal, parseOverride, renderProposal } from "./menu.js";
+import {
+  TRAIN_MODE_COMMAND,
+  isManualMode,
+  modeMessage,
+  toggleManualMode,
+} from "./commands.js";
+
+// Injected-menu prefix; skipped in chat.message so our own output isn't read as an override.
+const MENU_PREFIX = "Arbiter proposes:";
+
+// Only pending/in-progress subtasks are still routable.
+const ACTIONABLE = new Set(["pending", "in_progress"]);
+
+/** ~4 chars/token is a coarse but adequate estimate for the context-fit field. */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/** Pull the concatenated text out of a message's parts (text parts only). */
+function extractText(parts: Array<{ type?: string; text?: string }>): string {
+  return parts
+    .filter((p) => p?.type === "text" && typeof p.text === "string")
+    .map((p) => p.text as string)
+    .join("\n");
+}
+
+export const NotaryPlugin: Plugin = async ({ client }) => {
+  const server = new ServerClient();
+
+  // Proposals shown but not yet accepted/overridden, keyed by session.
+  const pending = new Map<string, Proposal[]>();
+  // Last todo-set signature per session, so status-only updates don't re-show the menu.
+  const lastSignature = new Map<string, string>();
+
+  const toast = (message: string, variant: "info" | "success" = "info") =>
+    client.tui
+      .showToast({ body: { message, variant } })
+      .catch(() => {}); // a failed toast must never break the flow
+
+  const logAccepted = (p: Proposal, sessionID: string) =>
+    server.logCorrection({
+      task_text: p.taskText,
+      predicted_tier: p.decision.tier,
+      predicted_model: p.decision.model,
+      confidence: p.decision.confidence,
+      session_id: sessionID,
+    });
+
+  // Classify subtask texts in parallel, dropping any the Server can't resolve (null).
+  const classifyAll = async (
+    texts: string[],
+    sessionID: string,
+  ): Promise<Proposal[]> => {
+    const decisions = await Promise.all(
+      texts.map((t) =>
+        server.classify({
+          task_text: t,
+          session_id: sessionID,
+          context_tokens_estimate: estimateTokens(t),
+        }),
+      ),
+    );
+    const out: Proposal[] = [];
+    decisions.forEach((d: Decision | null, i) => {
+      if (d) out.push({ taskText: texts[i], decision: d });
+    });
+    return out;
+  };
+
+  console.log("[notary] Arbiter plugin loaded — Server contract at", "127.0.0.1:4317");
+
+  return {
+    /** Register the /train-mode command so OpenCode routes it to us. */
+    config: async (cfg) => {
+      cfg.command ??= {};
+      cfg.command[TRAIN_MODE_COMMAND] ??= {
+        // No-op template: the toggle happens in command.execute.before.
+        template: "",
+        description: "Toggle Arbiter train-mode (verify/override per-subtask routing)",
+      };
+    },
+
+    /** Intercept /train-mode: flip the mode, suppress the prompt, toast the result. */
+    "command.execute.before": async (input, output) => {
+      if (input.command !== TRAIN_MODE_COMMAND) return;
+      const on = toggleManualMode();
+      output.parts = []; // suppress — this is a UI toggle, not a model prompt
+      await toast(modeMessage(on));
+    },
+
+    /** Plan interception: classify each actionable subtask; in train-mode show the menu. */
+    event: async ({ event }) => {
+      if (event.type !== "todo.updated") return;
+      const { sessionID, todos } = event.properties;
+
+      const actionable = todos.filter((t) => ACTIONABLE.has(t.status));
+      const signature = JSON.stringify(actionable.map((t) => [t.id, t.content]));
+      if (signature === lastSignature.get(sessionID)) return; // status-only churn
+      lastSignature.set(sessionID, signature);
+
+      if (actionable.length === 0) {
+        pending.delete(sessionID);
+        return;
+      }
+
+      const proposals = await classifyAll(
+        actionable.map((t) => t.content),
+        sessionID,
+      );
+      if (proposals.length === 0) return; // Server couldn't resolve anything -> stay silent
+
+      if (isManualMode()) {
+        await client.session
+          .prompt({
+            path: { id: sessionID },
+            body: { noReply: true, parts: [{ type: "text", text: renderProposal(proposals) }] },
+          })
+          .catch(() => {});
+        pending.set(sessionID, proposals);
+      } else {
+        // Auto mode: pass-through, every subtask's decision logged silently.
+        for (const p of proposals) await logAccepted(p, sessionID);
+      }
+    },
+
+    /** Override channel: interpret the reply to a pending menu and log the correction(s). */
+    "chat.message": async (input, output) => {
+      const sessionID = input.sessionID;
+      const awaiting = pending.get(sessionID);
+      if (!awaiting) return; // no proposal in flight -> not our concern
+
+      const text = extractText(output.parts);
+      if (!text.trim() || text.startsWith(MENU_PREFIX)) return; // empty / our own menu
+
+      const ov = parseOverride(text, awaiting.length);
+      if (!ov) {
+        // Not a control reply: the user moved on; log the proposals as accepted-as-is.
+        pending.delete(sessionID);
+        for (const p of awaiting) await logAccepted(p, sessionID);
+        return;
+      }
+
+      pending.delete(sessionID);
+      if (ov.kind === "accept") {
+        for (const p of awaiting) await logAccepted(p, sessionID);
+        await toast("Arbiter: accepted.", "success");
+        return;
+      }
+
+      // Override of one subtask; the rest stand as proposed (accepted).
+      const target = awaiting[ov.index - 1];
+      const correction: Correction = {
+        task_text: target.taskText,
+        predicted_tier: target.decision.tier,
+        predicted_model: target.decision.model,
+        confidence: target.decision.confidence,
+        session_id: sessionID,
+        corrected_tier: ov.targetIsTier ? ov.target : null,
+        corrected_model: ov.targetIsTier ? null : ov.target,
+      };
+      await server.logCorrection(correction);
+      for (let i = 0; i < awaiting.length; i++) {
+        if (i !== ov.index - 1) await logAccepted(awaiting[i], sessionID);
+      }
+      await toast(`Arbiter: overrode #${ov.index} -> ${ov.target}.`, "success");
+    },
+  };
+};

package/src/menu.test.ts

@@ -0,0 +1,95 @@
+// Tests for menu rendering + override parsing; runs under Node's built-in test runner.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import type { Decision } from "./client.ts";
+import {
+  isTier,
+  parseOverride,
+  renderProposal,
+  shortModel,
+} from "./menu.ts";
+
+function decision(over: Partial<Decision> = {}): Decision {
+  return {
+    difficulty: "medium",
+    confidence: 0.82,
+    tier: "cloud-mid",
+    model: "google/gemini-2.5-flash",
+    reasoning_effort: "medium",
+    reason: "cheapest reasoning-capable cloud-mid model",
+    ...over,
+  };
+}
+
+test("shortModel strips the provider prefix", () => {
+  assert.equal(shortModel("google/gemini-3.5-flash"), "gemini-3.5-flash");
+  assert.equal(shortModel("qwen3:8b"), "qwen3:8b"); // no slash -> unchanged
+});
+
+test("isTier recognizes only the three real tiers", () => {
+  assert.ok(isTier("cloud-heavy"));
+  assert.ok(!isTier("ultra"));
+});
+
+test("renderProposal shows the tier->model tag, task, and footer", () => {
+  const out = renderProposal([
+    { taskText: "implement JWT refresh logic", decision: decision() },
+  ]);
+  assert.match(out, /^Arbiter proposes:/);
+  assert.match(out, /\[cloud-mid -> gemini-2\.5-flash\]/);
+  assert.match(out, /implement JWT refresh logic/);
+  assert.match(out, /Accept: enter/);
+});
+
+test("renderProposal aligns multiple subtasks and shows multi-footer", () => {
+  const out = renderProposal([
+    { taskText: "rename a var", decision: decision({ tier: "local-simple", model: "ollama/qwen3:8b" }) },
+    { taskText: "redesign session arch", decision: decision({ tier: "cloud-heavy", model: "google/gemini-3.5-flash" }) },
+  ]);
+  const lines = out.split("\n").filter((l) => /^\d+\. /.test(l));
+  assert.equal(lines.length, 2);
+  // Tags padded to equal width -> the task text starts at the same column.
+  assert.equal(lines[0].indexOf("rename"), lines[1].indexOf("redesign"));
+  assert.match(out, /Accept all: enter/);
+});
+
+test("parseOverride treats empty/accept tokens as accept", () => {
+  for (const t of ["", "  ", "accept", "ACCEPT ALL", "y", "ok"]) {
+    assert.deepEqual(parseOverride(t, 1), { kind: "accept" });
+  }
+});
+
+test("parseOverride parses '<n> <model>' as a model override", () => {
+  assert.deepEqual(parseOverride("2 gemini-3.5-flash", 3), {
+    kind: "override",
+    index: 2,
+    target: "gemini-3.5-flash",
+    targetIsTier: false,
+  });
+});
+
+test("parseOverride recognizes a tier target", () => {
+  const ov = parseOverride("2 cloud-heavy", 3);
+  assert.deepEqual(ov, { kind: "override", index: 2, target: "cloud-heavy", targetIsTier: true });
+});
+
+test("parseOverride allows a bare target only for a single subtask", () => {
+  assert.deepEqual(parseOverride("gemini-3.5-flash", 1), {
+    kind: "override",
+    index: 1,
+    target: "gemini-3.5-flash",
+    targetIsTier: false,
+  });
+  // With multiple subtasks a bare target is ambiguous -> not a control input.
+  assert.equal(parseOverride("gemini-3.5-flash", 3), null);
+});
+
+test("parseOverride rejects an out-of-range index", () => {
+  assert.equal(parseOverride("9 gemini-3.5-flash", 3), null);
+});
+
+test("parseOverride returns null for an ordinary new task message", () => {
+  assert.equal(parseOverride("now add tests for the auth module please", 1), null);
+});

package/src/menu.ts

@@ -0,0 +1,87 @@
+// Plan-mode menu rendering + override parsing. Pure string logic, no SDK/network deps.
+
+import type { Decision } from "./client.js";
+
+export const TIERS = ["local-simple", "cloud-mid", "cloud-heavy"] as const;
+export type Tier = (typeof TIERS)[number];
+
+/** One proposed subtask: the task text and the Server's resolved Decision. */
+export interface Proposal {
+  taskText: string;
+  decision: Decision;
+}
+
+export type Override =
+  | { kind: "accept" }
+  | { kind: "override"; index: number; target: string; targetIsTier: boolean };
+
+/** Display name for a "provider/id" model — the id half. */
+export function shortModel(model: string): string {
+  const slash = model.lastIndexOf("/");
+  return slash >= 0 ? model.slice(slash + 1) : model;
+}
+
+export function isTier(value: string): value is Tier {
+  return (TIERS as readonly string[]).includes(value);
+}
+
+/** Collapse a task to a single trimmed line for the menu. */
+function oneLine(text: string, max = 60): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/** Render the numbered plan-mode menu; the `[tier -> model]` column is width-padded. */
+export function renderProposal(proposals: Proposal[]): string {
+  if (proposals.length === 0) return "";
+
+  const tags = proposals.map(
+    (p) => `[${p.decision.tier} -> ${shortModel(p.decision.model)}]`,
+  );
+  const width = Math.max(...tags.map((t) => t.length));
+
+  const lines = proposals.map((p, i) => {
+    const tag = tags[i].padEnd(width);
+    return `${i + 1}. ${tag}   ${oneLine(p.taskText)}`;
+  });
+
+  const footer =
+    proposals.length === 1
+      ? [
+          "",
+          "Accept: enter",
+          'Override: type a tier or a model (e.g. "gemini-3.5-flash" or "cloud-heavy")',
+        ]
+      : [
+          "",
+          "Accept all: enter",
+          "Override: type subtask number, then a tier or a specific model",
+          '          (e.g. "2 gemini-3.5-flash")',
+        ];
+
+  return ["Arbiter proposes:", "", ...lines, ...footer].join("\n");
+}
+
+const ACCEPT_TOKENS = new Set(["", "accept", "accept all", "y", "yes", "ok"]);
+
+/** Parse a reply: accept token, "<n> <target>", bare "<target>" (single subtask), else null. */
+export function parseOverride(input: string, count: number): Override | null {
+  const trimmed = input.trim();
+  if (ACCEPT_TOKENS.has(trimmed.toLowerCase())) return { kind: "accept" };
+
+  // "<n> <target...>" — leading 1-based subtask index, then a tier or model.
+  const numbered = trimmed.match(/^(\d+)\s+(.+)$/);
+  if (numbered) {
+    const index = Number(numbered[1]);
+    if (index < 1 || index > count) return null; // out of range -> not a control input
+    const target = numbered[2].trim();
+    return { kind: "override", index, target, targetIsTier: isTier(target) };
+  }
+
+  // Bare "<target>" with a single subtask: unambiguous override of subtask 1.
+  if (count === 1 && /^[\w./:-]+$/.test(trimmed)) {
+    return { kind: "override", index: 1, target: trimmed, targetIsTier: isTier(trimmed) };
+  }
+
+  return null;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}