feat(provider): add --model free to pick a random zero-cost opencode model

Resolves --model free to a randomly-chosen zero-cost opencode model per
invocation. Filter is structural (providerID === opencode and every cost
dim === 0), not name-based, so the resolver picks up new catalog members
automatically as models.dev rotates the OpenCode Zen tier.

Provider.resolveSelection takes an explicit InstanceContext arg because
Service.list() needs InstanceRef in the Effect fiber; plain-async CLI
callers (run and TUI) have no current fiber. bootstrap() forwards its
loaded ctx to its callback so the TUI can thread it through.

Resolution runs on both interactive/--mini and non-interactive paths.
--attach + --model free fails fast with a clean CLI error since the local
catalog isn't loaded in attach mode. Removes the --variant flag and its
threading: the free-model catalog rotates fast enough that variant
pinning doesn't make sense.

Author: caretak3r

packages/opencode/script/stress-free-models.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Parallel stress test for `opencode run --model free`.
+# Verifies the structural filter (provider==opencode, all costs==0) reaches
+# the full live catalog of zero-cost models.
+#
+# Usage:
+#   script/stress-free-models.sh [DURATION_SECONDS] [WORKERS]
+#
+# Defaults: 300s, 3 workers. Each worker loops, calling `run --model free "x"`,
+# captures the resolved model from the build line, appends to a shared log.
+# At the end, prints distribution + unique-model count.
+#
+# Requires: gtimeout (brew install coreutils).
+
+set -euo pipefail
+
+DURATION="${1:-300}"
+WORKERS="${2:-3}"
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+BIN="$REPO_ROOT/packages/opencode/dist/opencode-darwin-arm64/bin/opencode"
+
+if [ ! -x "$BIN" ]; then
+  echo "ERROR: binary not found at $BIN" >&2
+  echo "       run \`bun run build\` from $REPO_ROOT/packages/opencode first" >&2
+  exit 1
+fi
+if ! command -v gtimeout >/dev/null 2>&1; then
+  echo "ERROR: gtimeout not found. Install via: brew install coreutils" >&2
+  exit 1
+fi
+
+WORKDIR="$(mktemp -d -t oc-stress-XXXXXX)"
+LOG="$WORKDIR/stress.log"
+: > "$LOG"
+END=$(($(date +%s) + DURATION))
+
+export END BIN LOG WORKDIR
+
+worker() {
+  local id=$1
+  local dir="$WORKDIR/w$id"
+  mkdir -p "$dir"
+  cd "$dir"
+  local n=0
+  while [ "$(date +%s)" -lt "$END" ]; do
+    raw=$(gtimeout 12 "$BIN" run --model free "x" 2>&1 | sed $'s,\x1b\\[[0-9;]*[a-zA-Z],,g')
+    pick=$(echo "$raw" | grep -oE '> build · [a-z0-9.-]+' | sed 's/> build · //' | head -1)
+    if [ -n "$pick" ]; then
+      echo "$(date +%s) w$id #$n $pick" >> "$LOG"
+    else
+      echo "$(date +%s) w$id #$n MISS" >> "$LOG"
+    fi
+    n=$((n + 1))
+  done
+}
+
+export -f worker
+
+echo "stress test: ${DURATION}s × ${WORKERS} workers → $LOG"
+for i in $(seq 1 "$WORKERS"); do
+  worker "$i" &
+done
+wait
+
+echo
+echo "=== completed ==="
+echo "total samples: $(wc -l < "$LOG" | tr -d ' ')"
+echo "--- distribution ---"
+awk '{print $NF}' "$LOG" | sort | uniq -c | sort -rn
+echo "--- unique non-MISS models ---"
+awk '{print $NF}' "$LOG" | grep -v MISS | sort -u
+echo "--- unique count ---"
+awk '{print $NF}' "$LOG" | grep -v MISS | sort -u | wc -l | tr -d ' '
+echo "--- per-worker counts ---"
+awk '{print $2}' "$LOG" | sort | uniq -c
+echo
+echo "raw log: $LOG"

packages/opencode/src/cli/bootstrap.ts

@@ -1,10 +1,10 @@
 import { InstanceRuntime } from "../project/instance-runtime"
-import { context } from "../project/instance-context"
+import { context, type InstanceContext } from "../project/instance-context"
 
-export async function bootstrap<T>(directory: string, cb: () => Promise<T>) {
+export async function bootstrap<T>(directory: string, cb: (ctx: InstanceContext) => Promise<T>) {
   const ctx = await InstanceRuntime.load({ directory })
   try {
-    return await context.provide(ctx, cb)
+    return await context.provide(ctx, () => cb(ctx))
   } finally {
     await InstanceRuntime.disposeInstance(ctx)
   }

packages/opencode/src/cli/cmd/run.ts

@@ -24,6 +24,7 @@ import { EOL } from "os"
 import { Filesystem } from "@/util/filesystem"
 import { createOpencodeClient, type OpencodeClient, type ToolPart } from "@opencode-ai/sdk/v2"
 import { FormatError, FormatUnknownError } from "../error"
+import { Provider } from "@/provider/provider"
 import { INTERACTIVE_INPUT_ERROR, resolveInteractiveStdin } from "./run/runtime.stdin"
 
 type ModelInput = Parameters<OpencodeClient["session"]["prompt"]>[0]["model"]
@@ -209,10 +210,6 @@ export const RunCommand = effectCmd({
         type: "number",
         describe: "port for the local server (defaults to random port if no value provided)",
       })
-      .option("variant", {
-        type: "string",
-        describe: "model variant (provider-specific reasoning effort, e.g., high, max, minimal)",
-      })
       .option("thinking", {
         type: "boolean",
         describe: "show thinking blocks",
@@ -277,6 +274,19 @@ export const RunCommand = effectCmd({
         UI.error(message)
         process.exit(1)
       }
+      if (args.attach && args.model === "free") {
+        die(
+          "--model free is not supported with --attach; specify a concrete model id (e.g., --model opencode/mimo-v2.5-free)",
+        )
+      }
+      const resolved = await (async () => {
+        if (args.attach) return { model: args.model }
+        try {
+          return await Provider.resolveSelection(args.model, localInstance)
+        } catch (error) {
+          return die(error instanceof Error ? error.message : String(error))
+        }
+      })()
       const dieInteractive = (error: unknown): never => {
         if (error instanceof Error && error.message === INTERACTIVE_INPUT_ERROR) {
           die(error.message)
@@ -836,15 +846,13 @@ export const RunCommand = effectCmd({
             const error = await completed
             if (error) process.exitCode = 1
           }
-
           if (args.command) {
             const result = await client.session.command({
               sessionID,
               agent,
-              model: args.model,
+              model: resolved.model,
               command: args.command,
               arguments: message,
-              variant: args.variant,
             })
             if (result.error) {
               if (!emit("error", { error: result.error })) UI.error(formatRunError(result.error))
@@ -855,12 +863,11 @@ export const RunCommand = effectCmd({
             return
           }
 
-          const model = pick(args.model)
+          const model = resolved.model ? Provider.parseModel(resolved.model) : undefined
           const result = await client.session.prompt({
             sessionID,
             agent,
             model,
-            variant: args.variant,
             parts: [...files, { type: "text", text: message }],
           })
           if (result.error) {
@@ -872,7 +879,7 @@ export const RunCommand = effectCmd({
           return
         }
 
-        const model = pick(args.model)
+        const model = pick(resolved.model)
         const { runInteractiveMode } = await import("./run/runtime")
         try {
           await runInteractiveMode({
@@ -885,7 +892,7 @@ export const RunCommand = effectCmd({
             replayLimit: args["replay-limit"],
             agent,
             model,
-            variant: args.variant,
+            variant: undefined,
             files,
             initialInput,
             createSession: createFreshSession,
@@ -900,7 +907,7 @@ export const RunCommand = effectCmd({
       }
 
       if (interactive && !args.attach && !args.session && !args.continue) {
-        const model = pick(args.model)
+        const model = pick(resolved.model)
         const { runInteractiveLocalMode } = await import("./run/runtime")
         const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
           const { Server } = await import("@/server/server")
@@ -921,7 +928,7 @@ export const RunCommand = effectCmd({
             createSession: createFreshSession,
             agent: args.agent,
             model,
-            variant: args.variant,
+            variant: undefined,
             replay,
             replayLimit: args["replay-limit"],
             files,
@@ -995,7 +1002,6 @@ export async function runMini(input: MiniCommandInput) {
     username: input.username,
     dir: input.directory,
     port: undefined,
-    variant: undefined,
     thinking: undefined,
     mini: true,
     interactive: false,

packages/opencode/src/cli/cmd/tui.ts

@@ -14,6 +14,8 @@ import { writeHeapSnapshot } from "v8"
 import { ServerAuth } from "@/server/auth"
 import { validateSession } from "../tui/validate-session"
 import { win32InstallCtrlCGuard } from "@opencode-ai/tui/terminal-win32"
+import { Provider } from "@/provider/provider"
+import { bootstrap } from "@/cli/bootstrap"
 
 declare global {
   const OPENCODE_WORKER_PATH: string
@@ -206,6 +208,20 @@ export const TuiThreadCommand = cmd({
         return
       }
       const cwd = Filesystem.resolve(process.cwd())
+      // Resolving `--model free` requires Provider.Service.list, which needs the
+      // Instance ALS context the effectCmd wrapper would normally provide. The
+      // TUI handler runs outside it, so bootstrap it here only for `free`; any
+      // other model is passed through directly to avoid the load/dispose cost.
+      let model = args.model
+      if (args.model === "free") {
+        try {
+          model = (await bootstrap(cwd, (ctx) => Provider.resolveSelection(args.model, ctx))).model
+        } catch (error) {
+          UI.error(error instanceof Error ? error.message : String(error))
+          process.exitCode = 1
+          return
+        }
+      }
 
       const worker = new Worker(file, {
         env: Object.fromEntries(
@@ -288,7 +304,7 @@ export const TuiThreadCommand = cmd({
               continue: args.continue,
               sessionID: args.session,
               agent: args.agent,
-              model: args.model,
+              model,
               prompt,
               fork: args.fork,
               auto: args.auto || args.yolo || args["dangerously-skip-permissions"],

packages/opencode/src/provider/provider.ts

@@ -1,4 +1,5 @@
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import os from "os"
 import { ConfigV1 } from "@opencode-ai/core/v1/config/config"
 import fuzzysort from "fuzzysort"
@@ -23,6 +24,7 @@ import { EffectBridge } from "@/effect/bridge"
 import { InstanceState } from "@/effect/instance-state"
 import { EffectPromise } from "@/effect/promise"
 import { FSUtil } from "@opencode-ai/core/fs-util"
+import { makeRuntime } from "@/effect/run-service"
 import { isRecord } from "@/util/record"
 import { optional } from "@opencode-ai/core/schema"
 import { ProviderTransform } from "./transform"
@@ -31,6 +33,8 @@ import { ModelV2 } from "@opencode-ai/core/model"
 import { ModelStatus } from "./model-status"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { ProviderError } from "./error"
+import { InstanceRef } from "@/effect/instance-ref"
+import type { InstanceContext } from "@/project/instance-context"
 
 const OPENAI_HEADER_TIMEOUT_DEFAULT = 10_000
 
@@ -1987,6 +1991,48 @@ export function sort<T extends { id: string }>(models: T[]) {
   )
 }
 
+const FREE = "free"
+
+export function isFree(model: Model) {
+  // Structural filter only: any opencode model whose every cost dimension is
+  // zero is a candidate. models.dev does not expose a "Zen tier" flag, and the
+  // OpenCode Zen endpoint (api.url = opencode.ai/zen/v1) is shared by both the
+  // -free suffix models and promotional zero-cost models (e.g. "big-pickle").
+  const extra = model.cost.experimentalOver200K
+  return (
+    model.providerID === ProviderV2.ID.opencode &&
+    model.cost.input === 0 &&
+    model.cost.output === 0 &&
+    model.cost.cache.read === 0 &&
+    model.cost.cache.write === 0 &&
+    (!extra || (extra.input === 0 && extra.output === 0 && extra.cache.read === 0 && extra.cache.write === 0))
+  )
+}
+
+export async function resolveSelection(model?: string, instance?: InstanceContext) {
+  if (!model) return { model }
+  if (model !== FREE) return { model }
+  // Service.list() requires InstanceRef in the Effect fiber. Callers from plain
+  // async code (run.ts handler post-await, thread.ts bootstrap callback) have no
+  // current fiber, so we provide it explicitly when given. Tests run inside an
+  // Effect fiber that already has InstanceRef set up, so the arg is optional.
+  const providers = await runPromise((svc) =>
+    instance ? svc.list().pipe(Effect.provideService(InstanceRef, instance)) : svc.list(),
+  )
+  const provider = providers[ProviderV2.ID.opencode]
+  const models = sort(Object.values(provider?.models ?? {}).filter(isFree))
+  // Unseeded by design: the same `--model free` in two terminals picks
+  // different models.
+  const pick = models[Math.floor(Math.random() * models.length)]
+  if (!pick)
+    throw new Error(
+      `No free opencode models found. The opencode provider must be configured (set OPENCODE_API_KEY) and at least one model in its catalog must have all costs set to 0.`,
+    )
+  return {
+    model: `${pick.providerID}/${pick.id}`,
+  }
+}
+
 export function parseModel(model: string) {
   const [providerID, ...rest] = model.split("/")
   return {
@@ -2001,4 +2047,6 @@ export const node = LayerNode.make({
   deps: [FSUtil.node, Config.node, Auth.node, Env.node, Plugin.node, ModelsDev.node, RuntimeFlags.node],
 })
 
+const { runPromise } = makeRuntime(Service, AppNodeBuilder.build(node))
+
 export * as Provider from "./provider"