fix(tui): render submitted prompts optimistically

Co-authored-by: Dax Raad <thdxr@users.noreply.github.com>

.changeset/calm-services-start.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/client": patch
+---
+
+Reuse a same-version background service when a repeated health probe succeeds instead of replacing an endpoint another client may already be using.

.opencode/skills/opencode-drive/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: opencode-drive
+description: Use when an agent needs drive OpenCode via a script or interact with an isolated instance
+---
+
+# OpenCode Drive
+
+Use `opencode-drive` to launch an isolated OpenCode instance and control it via commands or a script.
+
+There are two modes. Always default to using a script unless specifically directed to be interactive (connect
+to an existing running instance, or start a new one, and make a few changes to the UI and read it, and iterate
+on changes).
+
+Scripts allow you to run a full walkthrough in one run. When the script is done opencode-drive exits,
+stops all processes, and cleans up all artifacts.
+
+# Prepare The Environment
+
+Use `init` when files must be added to the isolated home or project before OpenCode starts. It prints the artifact directory without launching OpenCode. A later `start` with the same name reuses it.
+
+```bash
+artifacts=$(opencode-drive init --name demo)
+cp -R ./fixtures/home/. "$artifacts/"
+cp -R ./fixtures/project/. "$artifacts/files/"
+opencode-drive start --name demo --dev ~/projects/opencode
+```
+
+The simulated project is under `$artifacts/files`. Running `start` without a prior `init` initializes the artifacts automatically.
+
+# Scripted usage
+
+You can write scripts that walk through entire flows, and gives you full access to controlling
+the backend too. See examples of the script API at the bottom of this file.
+
+After creating or editing a script, always typecheck it before running. Never skip this step:
+
+```bash
+opencode-drive check ./reproduce-stale-exploring-empty.ts
+```
+
+Run it by passing `--script` to start:
+
+```bash
+opencode-drive start --name auto-stop-reproduction --script ./reproduce-stale-exploring-empty.ts
+```
+
+It will output information about the run, including paths to log files which you can read
+to inspect what happened. If you need to dig into failures that aren't clear, read those log
+files. If the script is unsuccessful, automatically fix the script and run it again.
+
+Scripts use one typed definition object. `setup` runs before OpenCode starts,
+and `fs.writeFile` always writes inside the simulated project.
+
+You can read the full typed API here: https://raw.githubusercontent.com/jlongster/opencode-drive/refs/heads/main/src/script/types.ts
+
+```ts
+import { defineScript } from "opencode-drive"
+
+export default defineScript({
+  async setup({ fs, config }) {
+    config.autoupdate = false
+    await fs.writeFile("src/example.ts", "export const value = 1\n")
+  },
+
+  async run({ ui, llm }) {
+    await ui.submit("Open src/example.ts")
+    await llm.send(llm.text("The file exports `value`."))
+    await ui.waitFor("The file exports `value`.")
+  },
+})
+```
+
+`setup` receives the current OpenCode config object, which starts from the
+default drive config unless the prepared instance already has one. When a script
+needs custom config, mutate this `config` parameter instead of generating and
+writing a new config object from scratch, so the script keeps the default
+provider/model settings unless it intentionally changes them.
+
+Note that the simulated model is a GPT model type, and opencode uses the `patch` tool for working with files Do not use a `edit` or `write` tool to edit files.
+
+Use `launch: "manual"` when the script needs to launch the server and every TUI
+itself (this is extremely rare, do not use this unless explicitly asked). In this
+mode `ui` is typed as `null`; call `server.launch()` exactly
+once before launching clients. Each `clients.launch(name)` result provides the
+same UI methods as the automatic client. You can see an example of this API
+here: https://raw.githubusercontent.com/jlongster/opencode-drive/refs/heads/main/examples/multiple-clients.ts
+
+Use the exported `wait(milliseconds)` utility for an unconditional delay.
+
+`await llm.send(...)` waits for the next request and resolves after OpenCode
+acknowledges its complete response. `llm.queue(...)` declares responses in
+advance. Chunks may be built with `text`, `reasoning`, `toolCall`, `raw`,
+`finish`, and `disconnect`. A normal response receives `finish("stop")`
+automatically unless it yields or queues an explicit terminal event.
+
+`llm.text(text, { delay, chunkSize })` defaults to a 2 ms delay and a
+15-character target varied by plus or minus 5 per chunk.
+
+`llm.reasoning` accepts the same options, and `llm.pause(milliseconds)` adds a
+delay between any two outputs.
+
+Use `llm.serve` for an ongoing typed response generator:
+
+```ts
+llm.serve(async function* (request, index) {
+  yield llm.reasoning(`Handling request ${index + 1}`)
+  yield llm.text(`Received ${request.id}`)
+  yield llm.finish("stop")
+})
+```
+
+The backend connection, response cleanup, cancellation, and recording
+completion are automatic.
+
+You can see some example scripts here:
+
+- https://raw.githubusercontent.com/jlongster/opencode-drive/refs/heads/main/examples/simple.ts
+- https://raw.githubusercontent.com/jlongster/opencode-drive/refs/heads/main/examples/serve.ts
+
+## Prune
+
+- `prune` removes artifact directories. These are always cleaned up after running a script
+  successfully, but leftover on failed runs. Always call this if a script fails.
+
+```bash
+opencode-drive prune --name demo
+
+// --force cleans up all artifcat directories
+opencode-dirve prune --force
+```
+
+# Live interaction usage
+
+- Always give headless instances a unique `--name`. Visible instances may omit it.
+- A normal headless `start` detaches automatically and returns after the instance is ready.
+- Do not add `&`; the long-running owner already runs in the background.
+- Configure simulated model responses after startup when needed.
+- Send ordered UI commands with `send`.
+- Always stop the instance when finished.
+
+```bash
+opencode-drive start --name demo
+
+opencode-drive send --name demo \
+  --command.ui.type '{"text":"Explain this project"}' \
+  --command.ui.enter
+
+opencode-drive stop --name demo
+```
+
+## Send UI Commands
+
+- Every `send` opens a connection to the named instance, runs its commands in order, and exits.
+- Combine typing and Enter in one command when submitting a prompt.
+- JSON-valued commands require one JSON argument.
+- Multiple command flags execute from left to right.
+
+Commands:
+
+- `--command.ui.type <json>` types into the focused editor. Arguments: `text` string.
+- `--command.ui.press <json>` presses a key. Arguments: `key` string; optional `modifiers` object with boolean `ctrl`, `shift`, `meta`, `super`, or `hyper`.
+- `--command.ui.enter` presses Enter. Arguments: none.
+- `--command.ui.arrow <json>` presses an arrow key. Arguments: `direction` is `up`, `down`, `left`, or `right`.
+- `--command.ui.focus <json>` focuses an element. Arguments: `target` is the numeric element `num` returned by `ui.state`.
+- `--command.ui.click <json>` clicks an element. Arguments: numeric `target`, `x`, and `y`; use the element `num` returned by `ui.state` as `target`.
+- `--command.ui.state` prints focus and interactive element metadata as JSON. Arguments: none.
+- `--command.ui.matches <json>` prints whether literal, case-sensitive text appears on screen. Arguments: `text` string.
+
+```bash
+opencode-drive send --name demo \
+  --command.ui.type '{"text":"Find the relevant code and explain it"}' \
+  --command.ui.enter
+
+opencode-drive send --name demo \
+  --command.ui.press '{"key":"p","modifiers":{"ctrl":true}}'
+
+opencode-drive send --name demo \
+  --command.ui.arrow '{"direction":"down"}'
+
+opencode-drive send --name demo \
+  --command.ui.focus '{"target":12}'
+
+opencode-drive send --name demo \
+  --command.ui.click '{"target":12,"x":4,"y":1}'
+
+opencode-drive send --name demo \
+  --command.ui.matches '{"text":"OpenCode"}'
+```
+
+To read the UI state and see information about interactable elements, use the `ui.state` command:
+
+```bash
+opencode-drive send --name demo --command.ui.state
+```
+
+## Configure LLM Responses
+
+- `responses` controls what the LLM responds with
+- Only use this if you are wanting to reproduce an exact type of response
+- Defaults are `text,reasoning,diff,tool` with `write,apply_patch`.
+- Supported types are `text`, `reasoning`, `diff`, and `tool`.
+- `--tools` limits generated tool calls to names offered by OpenCode.
+
+```bash
+opencode-drive responses --name demo \
+  --types text,reasoning,diff,tool \
+  --tools write,apply_patch
+
+opencode-drive responses --name demo \
+  --types tool \
+  --tools read,glob,grep
+```
+
+## Inspect The UI
+
+- `ui.state` prints focus and interactive element metadata as JSON.
+- `ui.matches` checks for literal, case-sensitive screen text.
+- `screenshot` prints the generated image path.
+
+```bash
+opencode-drive screenshot --name demo
+```
+
+## Lifecycle
+
+- `stop` waits for recording export and owner cleanup before returning.
+
+```bash
+opencode-drive stop --name demo
+```
+
+# Record The UI
+
+- Start with `--record` to capture a headless instance from its first rendered frame.
+- `stop` finishes the recording, exports an MP4, and prints its path.
+
+```bash
+opencode-drive start --name demo --record
+
+opencode-drive send --name demo \
+  --command.ui.type '{"text":"Show me the current architecture"}' \
+  --command.ui.enter
+
+opencode-drive stop --name demo
+```
+
+# Artifacts dir
+
+- `dir` prints the artifact directory for the instance.
+
+```bash
+opencode-drive dir --name demo
+```
+

AGENTS.md

@@ -27,6 +27,7 @@ Never bypass Git hooks. Do not use `--no-verify` or otherwise disable, skip, or
 
 - Keep things in one function unless composable or reusable
 - Do not extract single-use helpers preemptively. Inline the logic at the call site unless the helper is reused, hides a genuinely complex boundary, or has a clear independent name that improves the caller.
+- Before adding complexity for a speculative or vanishingly unlikely race or security edge case, explain the concrete failure mode, likelihood, and complexity cost to the user and get their buy-in. Do not silently expand scope for theoretical robustness.
 - Avoid `try`/`catch` where possible
 - Avoid using the `any` type
 - Use Bun APIs when possible, like `Bun.file()`
@@ -156,12 +157,12 @@ const table = sqliteTable("session", {
 - Keep durable events minimal: record irreducible new facts and do not repeat state derivable by folding the ordered aggregate history. Enrich projections and read models with previous or derived state when consumers need self-contained views.
 - Keep durable prompt admission separate from model execution. `SessionV2.prompt(...)` admits one durable `session_pending` row before scheduling advisory `SessionExecution.wake(sessionID)` unless `resume: false` requests admit-only behavior. The serialized runner promotes admitted inputs into visible user messages at safe boundaries, consuming the pending row in the same event transaction; `session_pending` stores only unconsumed work.
 - Reusing a Session ID adopts the existing Session. Reusing a prompt message ID reconciles an exact retry only when Session, prompt, and delivery mode match; conflicting reuse fails. Retry of an already-promoted input reconciles against the projected message and the durable admitted event rather than a retained row.
-- Keep `SessionExecution` process-global and Session-ID based. Its local implementation owns the process-local Session coordinator and discovers placement through `SessionStore` plus `LocationServiceMap.get(session.location)` only when a drain starts; no layer should take a Session ID. V2 interruption targets the active process-local ownership chain for that Session; idle or missing interruption is a no-op.
+- Keep `SessionExecution` process-global and Session-ID based. Its local implementation owns the process-local Session coordinator and discovers placement through `SessionStore` plus `LocationServiceMap.get(session.location)` only when a drain starts; no layer should take a Session ID. V2 interruption targets the active process-local ownership chain for that Session; interruption of a known but idle or locally unowned Session is a no-op, while the public API rejects an unknown Session.
 - Keep `SessionRunner`, model resolution, tool registry, permissions, and filesystem Location-scoped. Omitted `Location.workspaceID` means implicit-local placement; explicit workspace identity remains reserved for future placement semantics.
-- Preserve one explicit `llm.stream(request)` call per step and reload projected history before durable continuation. Do not bridge through legacy `SessionPrompt.loop(...)` or delegate orchestration to an in-memory tool loop.
+- Preserve one explicit `llm.stream(request)` call per Physical Attempt and reload projected history before durable continuation. Most Steps have one Physical Attempt; overflow-triggered compaction recovery may rebuild one Step for a second attempt. Do not bridge through legacy `SessionPrompt.loop(...)` or delegate orchestration to an in-memory tool loop.
 - Keep local Session drains process-local until clustering is implemented. `SessionRunCoordinator` joins explicit same-Session resumes, coalesces prompt wakeups, and allows different Sessions to run concurrently. Advisory wakes drain eligible durable inbox rows only; post-crash continuation recovery requires a separate explicit design before it may retry provider work. A drain has no durable identity or transcript boundary.
 - Keep delivery vocabulary explicit. Prompts steer by default and promote at the next safe step boundary while the current drain requires continuation. An explicit `queue` input remains pending until the Session would otherwise become idle; promote one queued input at that boundary, then reevaluate continuation before promoting another. Promoting any new user input resets the selected agent's step allowance; a batch of steers resets it once.
 - One step is one logical LLM call; its durable record covers only the model-visible span. Do not write "provider turn", and do not use bare "turn" for a single call: "turn" is reserved for the future assistant-turn unit containing all steps from prompt promotion until the session would go idle.
 - Keep EventV2 replay owner claims separate from clustered Session execution ownership.
-- Keep the Instructions algebra and built-ins in `src/instructions`; keep instruction producers with their observed domains, and keep Session History selection plus `InstructionCheckpoint` and `InstructionEntry` persistence Session-owned. `InstructionDiscovery` observes ambient global and upward-project instructions. The runner composes built-ins, discovery, guidance, and entries explicitly in `loadInstructions`; there is no instruction registry.
-- The durable `Instructions.Applied` record is what the model was last told, per instruction source. Reconciliation narrates drift through `session.instructions.updated` and never rewrites the baseline; only completed compaction rebaselines, while Session movement or committed revert resets the `InstructionCheckpoint`. Unavailable sources keep the model's prior belief, blocking only a Session's first instruction baseline.
+- Keep the Instructions algebra and built-ins in `src/instructions`; keep instruction producers with their observed domains, and keep Session History selection plus `InstructionState` and `InstructionEntry` persistence Session-owned. `InstructionDiscovery` observes ambient global and upward-project instructions. The runner composes built-ins, discovery, guidance, and entries explicitly in `loadInstructions`; there is no instruction registry.
+- `session.instructions.updated` stores only changed source keys and content hashes. Blob values live once in `instruction_blob`; `instruction_state` is a rebuildable fold cache, never primary state. Render initial instructions and chronological updates from values during request assembly. Completed compaction moves the instruction epoch; Session movement and committed revert clear it. Unavailable sources retain the last value and block only the initial complete delta.

CONTEXT.md

@@ -1,245 +0,0 @@
-# OpenCode Session Runtime
-
-OpenCode sessions preserve durable conversational history while assembling the runtime context an agent needs to act correctly in its current environment.
-
-## Language
-
-**Model Context**:
-The complete model-visible input assembled for one **Step**, including system instructions, **Session History**, tool definitions, and step-local additions. **Instructions** are one component of Model Context, not a synonym for it.
-_Avoid_: System Context
-
-**Instructions**:
-The opaque algebra of independently refreshable typed instruction sources that render the durable instruction baseline and chronological updates shown to the model.
-_Avoid_: Model Context, System Context
-
-**Session History**:
-The projected chronological conversation selected for a **Step** after applying the active compaction and **InstructionCheckpoint** baseline cutoffs.
-_Avoid_: Session Context
-
-**Instruction Source**:
-One independently observed typed value within **Instructions**, represented by a stable namespaced key, JSON codec, loader, pure baseline/update renderers, and an optional removal renderer.
-_Avoid_: Prompt fragment
-
-**InstructionEntry**:
-One API-managed, durable, per-Session instruction value. Its slash-free client key maps to the `api/<key>` **Instruction Source** key. Entries deliberately render to the model as mechanism-neutral `<context>` blocks: the model sees session context, not how it was attached.
-
-**InstructionDiscovery**:
-The Location-scoped service that observes ambient global and upward-project `AGENTS.md` files as one ordered aggregate **Instruction Source**.
-
-**InstructionCheckpoint**:
-The Session-owned durable instruction baseline, baseline sequence, and `Instructions.Applied` record used to prepare later Steps.
-
-**Instruction Update**:
-A durable chronological System message published as `session.instructions.updated` that tells the model the newly effective state of one or more changed **Instruction Sources**.
-_Avoid_: System notification, raw text diff
-
-**Instruction Baseline**:
-The exact joined instruction text stored by **InstructionCheckpoint** and sent as immutable provider-cache prefix state until completed compaction rebaselines it or Session movement or committed revert resets it.
-_Avoid_: Live system prompt
-
-**Applied Instructions**:
-The overwriteable model-hidden `Instructions.Applied` record in **InstructionCheckpoint**, containing what the model was last told per **Instruction Source**.
-
-**Unavailable Instruction Source**:
-An expected temporary inability to observe an **Instruction Source** value; the runtime retains its prior effective state and emits no update, while an unavailable source blocks creation of the first complete **Instruction Baseline**.
-
-**Safe Step Boundary**:
-The point during Step preparation, after prior tool settlement and before durable input promotion, where instruction changes may be admitted chronologically.
-
-**Admitted Prompt**:
-A durable user input accepted into the Session inbox but not yet included in **Session History**.
-
-**Prompt Promotion**:
-The durable transition that removes an **Admitted Prompt** from pending input and appends its user message to **Session History**.
-
-**Step**:
-One logical LLM call spanning pre-flight instruction checkpoint preparation, input promotion, request build, and compaction check; the provider stream; and tool settlement.
-_Avoid_: provider turn, turn (unqualified)
-
-**Physical Attempt**:
-One actual provider request on the wire in service of a **Step**; most Steps have one Physical Attempt, while overflow-triggered compaction recovery may give one Step two.
-
-**Assistant Turn**:
-A reserved name for the not-yet-modeled unit containing all **Steps** from prompt promotion until the assistant yields the floor; do not reify it until something durable needs it.
-
-**Settlement**:
-The terminal transition for a unit of work: Step and tool settlement are durable, while drain and execution settlement are coordinator-observed.
-
-**Execution**:
-One session-scoped coordinator busy period from first wake until idle. An Execution is process-local coordination rather than a durable domain entity.
-
-**Session Drain**:
-One process-local execution span that promotes eligible input and runs required **Steps** until no immediate continuation remains. A Session Drain has no durable identity or transcript boundary.
-
-**Model Tool Output**:
-The bounded projection of a Core-executed tool result persisted in Session history and replayed to the model. A tool may shape this projection semantically, but the Tool Registry enforces the final size limit.
-
-**Managed Tool Output File**:
-A temporary file created under OpenCode's shared tool-output directory to retain complete output that was too large for Session history.
-
-**Model Request Options**:
-Provider-semantic model settings selected from the Catalog and active Session variant before the LLM protocol adapter encodes them for a provider request.
-_Avoid_: Request body, wire options
-
-**Generation Controls**:
-Provider-neutral sampling and output controls, partitioned from provider semantics and compatibility wire fields when model metadata enters the Catalog.
-
-**Native Continuation Metadata**:
-Opaque protocol-shaped data attached to assistant content and required to continue that content natively with a compatible model, such as a reasoning signature or provider-hosted item identifier.
-
-**PTY Environment**:
-The host-supplied environment overlay applied by the server when creating a PTY, observed for the request Location and resolved PTY working directory.
-
-**OpenCode Client**:
-The generated Promise and Effect APIs derived from the public `HttpApi`; **Embedded OpenCode** shares the Effect API through an in-memory `HttpClient` against the same router and handlers.
-_Avoid_: Remote client
-
-**SDK Contract IR**:
-The runtime-neutral compiled representation of the authoritative `HttpApi`, preserving encoded and decoded type projections plus transport metadata so independent SDK emitters can choose their public value model and runtime interpreter.
-
-**Embedded OpenCode**:
-A scoped in-process host that structurally extends the **OpenCode Client**, supplies an in-memory HTTP transport, and exposes additional same-process capabilities directly.
-_Avoid_: Local implementation
-
-**Page**:
-A bounded ordered result containing `items` and opaque `previous` and `next` cursor links for navigating the same query in either direction.
-_Avoid_: Response envelope
-
-## Relationships
-
-- **Instructions** is an opaque carrier composed from zero or more **Instruction Sources**.
-- **Model Context** is broader than **Instructions**. For each **Step**, the runner assembles the selected agent or provider system text, the **Instruction Baseline**, **Session History**, available tools, and step-local additions into one model request.
-- **Session History** contains projected conversational messages and admitted **Instruction Updates**; the active **Instruction Baseline** remains separate provider-request state.
-- The runner explicitly loads and combines instruction built-ins, **InstructionDiscovery**, selected-agent skill guidance, reference guidance, MCP guidance, and **InstructionEntry** values. There is no instruction registry.
-- `Instructions.combine(...)` preserves caller order and rejects duplicate stable namespaced source keys. The runner loads its producers concurrently, then combines them in its fixed declared order.
-- Each **Instruction Source** loader returns one coherent typed value or explicitly reports unavailability. `Instructions.make(...)` hides the value type so differently typed sources compose uniformly; its codec compares and stores the value, while pure renderers produce baseline, update, and optional removal text.
-- `Instructions.initialize(...)` observes composed **Instructions** once and produces a complete **Instruction Baseline** with **Applied Instructions**.
-- `Instructions.reconcile(...)` observes composed **Instructions** once and returns either unchanged or one combined chronological update. It never rewrites the baseline.
-- `Instructions.rebaseline(...)` renders a fresh baseline after completed compaction, recalling previously applied values for sources that are temporarily unavailable.
-- A changed **Instruction Source** may contribute text to one **Instruction Update** containing the newly effective state.
-- An **Instruction Update** persists the exact combined rendered text sent to the model through `session.instructions.updated`.
-- **Applied Instructions** advances atomically with the corresponding durable **Instruction Update**.
-- **Applied Instructions** stores one codec-encoded JSON value and, for removable sources, a pre-rendered removal message per stable **Instruction Source** key.
-- Changes from multiple **Instruction Sources** admitted at one safe boundary combine into one **Instruction Update**.
-- Instruction changes are sampled and admitted lazily at a **Safe Step Boundary**, never pushed asynchronously when their source changes.
-- At a **Safe Step Boundary**, prior tool results are already settled; instruction preparation completes before newly admitted user input promotes.
-- An **Admitted Prompt** is replayable pending input, not yet model-visible **Session History**.
-- **Prompt Promotion** atomically consumes the pending inbox entry and appends its model-visible user message.
-- Steering prompts promote at the next **Safe Step Boundary** while the current **Session Drain** still requires continuation. Promoting any newly admitted user input resets the selected agent's step allowance; multiple prompts promoted at one boundary reset it once.
-- A queued prompt does not promote while the current **Session Drain** requires continuation. The runner promotes one queued prompt when the Session would otherwise become idle, then reevaluates continuation before promoting another.
-- A **Session Drain** is process-local coordination rather than a durable domain entity. Durable recovery must reason from prompts, projected history, physical attempts, and tool state rather than inventing an enclosing execution identity.
-- An **Execution** contains one or more **Session Drains**; a **Session Drain** contains one reserved assistant-turn span at a time; that span contains **Steps**; and each **Step** contains one or more **Physical Attempts** plus any tool calls it requires.
-- A **Step** record covers only the model-visible span from first assistant output through tool settlement; pre-flight leaves no record, and one Step settles at most one record.
-- The first **Step** renders the latest complete **Instruction Baseline** and creates its **InstructionCheckpoint** without emitting a redundant **Instruction Update**; an unavailable initial source blocks the Step instead of persisting an incomplete baseline.
-- Instruction preparation precedes durable input promotion on every Step so an unavailable first baseline leaves pending input untouched and later updates enter history before newly promoted input.
-- Completed compaction rebaselines the **InstructionCheckpoint** from current **Instructions** and removes earlier **Instruction Updates** from active projected model history while preserving durable audit history.
-- A newly composed **Instruction Source** absent from **Applied Instructions** emits its baseline rendering once at the next **Safe Step Boundary**.
-- **Unavailable Instruction Source** uses stale-while-revalidate semantics and is distinct from a successfully loaded absence, which may emit removal text.
-- **InstructionDiscovery** observes ambient instructions as one ordered aggregate **Instruction Source**.
-- Ambient discovery reads global and upward-project `AGENTS.md` files and honors `OPENCODE_DISABLE_PROJECT_CONFIG` for project files.
-- After a successful internal file or directory read, nearby `AGENTS.md` files toward the Location root are injected once per Session as durable synthetic instruction messages.
-- **InstructionEntry** stores API-managed per-Session JSON values. Each entry contributes one `api/<key>` **Instruction Source**, so adding, replacing, or removing an entry is reconciled at the next **Safe Step Boundary**.
-- Location-scoped instruction producers naturally re-resolve when a moved Session next runs in its destination Location.
-- Moving a Session resets its **InstructionCheckpoint**, so the destination must initialize a complete baseline before another prompt can promote. Committed revert also resets the checkpoint.
-- Selected-agent available-skill guidance is an **Instruction Source** composed explicitly by the runner. It lists only names and descriptions permitted for that agent; skill bodies and locations are exposed only through the permission-checked `skill` tool.
-- The selected agent and model are sampled when a **Step** starts. Changes admitted after that boundary apply to the next Step and do not restart the current Step.
-- An agent switch that changes selected-agent guidance produces an **Instruction Update** while preserving the current baseline.
-- Local tool authorization and pending permission requests retain the effective agent of the **Step** that issued the call; a later agent switch cannot change that call's policy.
-- Instruction source changes never wake idle Sessions; the next naturally scheduled **Safe Step Boundary** loads and compares current values lazily.
-- Once admitted, an **Instruction Update** remains durable even if the following **Physical Attempt** fails and is replayed unchanged on retry.
-- **Instruction Updates** remain durable Session-message history; normal user-facing transcript surfaces may hide them.
-- The date **Instruction Source** initially preserves host-local calendar-date behavior; a configured user timezone may replace that default later.
-- An **Instruction Baseline** is stored durably and reused verbatim across process restarts until rebaseline or reset.
-- An **Instruction Baseline** durably preserves the exact joined text used for its part of the active provider-cache prefix.
-- A model/provider switch preserves the current **InstructionCheckpoint** and chronological conversation history; the new selection applies to the next **Step**.
-- **Native Continuation Metadata** remains in durable history. Step projection includes it only for a successful exact originating provider/model match; failed Steps and incompatible models omit opaque metadata, while non-empty visible reasoning lowers to ordinary assistant text after a model switch. This conservative relation may widen only when recorded provider tests establish compatibility.
-- **Model Request Options** remain provider-semantic through Catalog resolution. The Session runner maps them into the LLM package's provider-option namespace; the selected protocol adapter alone owns provider wire encoding.
-- **Generation Controls**, protocol-semantic **Model Request Options**, and compatibility request body fields are separate Catalog domains. A shared ingestion adapter partitions legacy and models.dev AI-SDK-shaped options before routing.
-- The **PTY Environment** is a server concern rather than a Core PTY concern. PTY creation merges caller values, then the host overlay, then Core-forced terminal invariants such as `TERM` and `OPENCODE_TERMINAL`.
-- Networked and **Embedded OpenCode** use the same **OpenCode Client** and preserve the full HTTP encoding, routing, middleware, and decoding boundary; only the `HttpClient` transport differs.
-- The Effect-native network constructor obtains `HttpClient.HttpClient` from its environment so callers own transport selection, recording, tracing, retries, and tests. Convenience runtimes may provide a fetch transport separately.
-- Creating **Embedded OpenCode** is scoped. Closing its owning Scope releases the in-process server resources, database resources, registrations, and fibers.
-- **Embedded OpenCode** exposes shared client capabilities and embedded-only capabilities on one object; consumers do not navigate through a nested `.client` property.
-- The beta **OpenCode Client** currently uses plural consumer-facing capability groups such as `sessions`; whether the stable Session namespace should instead be singular `session` must be settled before stabilization. Internal server identifiers do not implicitly define public client names.
-- Server's concrete `HttpApi` is authoritative for shared **OpenCode Client** capabilities. Codegen compiles its Session group directly; the Effect runtime uses an equivalent Protocol-only projection so generated artifacts remain independent of Core and Server.
-- SDK generation reflects the public `HttpApi` once into an **SDK Contract IR**. Promise and Effect emitters share endpoint structure and transport metadata without being required to expose identical public values: an emitter may select encoded wire types, decoded domain types, compile-time brands, runtime validation, and its own execution abstraction independently.
-- The first Effect emitter is the rich projection: it exposes decoded Effect-native values, preserves brands and schema transformations, performs runtime schema decoding, and delegates transport interpretation to `HttpApiClient`. Lighter wire-shaped Effect output remains possible through another emitter policy rather than constraining the shared IR.
-- The rich Effect emitter regenerates private executable schemas when the **SDK Contract IR** proves that their transport semantics can be reproduced exactly. Contracts with authoritative custom transformations use the import-based Effect emitter against a Protocol-only client projection whose generated transport output is tested against Server's concrete API; the Promise emitter still derives zero-Effect structural wire types from the same IR.
-- `@opencode-ai/protocol` owns Session endpoint construction and middleware placement. Server supplies concrete middleware keys to produce the authoritative build-time API; the client projection supplies transport-only keys without importing Core or Server at runtime.
-- The first Promise emitter targets the same clean domain-oriented method organization rather than Hey API source compatibility. It returns unwrapped values directly, rejects declared and infrastructure failures, and begins with minimal client-level transport configuration; result wrappers, interceptors, and legacy generated signatures are outside the initial surface.
-- The first Promise emitter parses response syntax and trusts its generated structural types; it does not perform runtime structural validation. Malformed payload syntax fails, while a syntactically valid shape mismatch is not detected at the SDK boundary. Standalone validator generation remains an optional future emitter policy.
-- Declared Promise-client failures retain their tagged structural wire values and have generated type guards. Consumers do not depend on generated `Error` subclass identity, preserving discrimination across package copies and realms while remaining structurally aligned with Effect domain errors.
-- Promise-client infrastructure failures use one generated `ClientError` class with a structured reason such as transport failure, unexpected status, unsupported content type, or malformed response. Promise methods reject with either a tagged declared domain failure or `ClientError`, matching the Effect client's conceptual domain/infrastructure error division.
-- Promise methods accept a separate optional per-call transport-options argument containing `AbortSignal` and header overrides. Cancellation and transport metadata do not enter the domain input object; broader interceptor and response-mode APIs remain deferred.
-- Promise streaming methods return a lazy `AsyncIterable` directly rather than a Promise-wrapped stream object. Iteration opens the connection, `AbortSignal` cancels it, and ending iteration closes the underlying request; the Effect emitter analogously returns `Stream` directly.
-- Promise SSE connection establishment, declared HTTP failures, and infrastructure failures occur during `AsyncIterable` iteration, beginning with its first `next()` call, rather than during synchronous method construction.
-- Neither generated streaming runtime automatically reconnects after disconnection. Promise `AsyncIterable` and Effect `Stream` fail explicitly; live consumers refresh and resubscribe, while durable sequence-based resume remains explicit composition above the generated client.
-- Promise client construction is synchronous and network-free. It requires `baseUrl`, defaults to `globalThis.fetch`, accepts client-level headers, and merges them with per-call header overrides.
-- Effect client construction accepts an explicit `baseUrl` and obtains `HttpClient.HttpClient` from the Effect environment. It does not install fetch or duplicate per-call transport policy; callers transform/provide the client for headers, tracing, retries, recording, and tests, while fiber interruption owns cancellation.
-- Promise and Effect emitters each own their generated public type modules. The **SDK Contract IR**, not a physically shared generated type package, is the common source; this permits zero-Effect wire types and rich decoded Effect types to evolve independently.
-- Promise and Effect network clients ship from `@opencode-ai/client` behind isolated root and `/effect` exports. The root has no runtime path to Effect; `/effect` imports only Effect, Schema, and Protocol.
-- The Effect-native scoped host belongs to `@opencode-ai/sdk-next`, which will assume the existing `@opencode-ai/sdk` name after legacy consumers migrate. Client remains network-only and SDK depends one-way on Client.
-- SDK executes Server's assembled `HttpRouter` in memory. It opens no listener and performs no network I/O, while preserving Server routing, middleware, codecs, handlers, and errors.
-- The Effect Client and SDK re-export their decoded datatype facade from Schema so callers do not depend on internal package locations or Core's versioned names.
-- A capability intended for both networked and **Embedded OpenCode** belongs in the authoritative public `HttpApi`; embedded-only same-process capabilities extend **Embedded OpenCode** separately.
-- `sessions.events({ sessionID, after })` is a public durable Session event stream. It verifies the Session, replays durable events after the optional aggregate sequence, continues with newly committed durable events, excludes live-only fragments, and is transported as SSE in both networked and embedded modes.
-- `events.subscribe()` is a distinct public instance-wide live stream for Session and non-Session activity. It has no replay guarantee and includes connection, heartbeat, and instance-disposal lifecycle events; consumers recover from disconnection by refreshing authoritative state.
-- A Session ID is not an optional filter on `events.subscribe()`: instance-wide live events and durable Session events have different schemas, replay guarantees, cursors, lifecycle events, and failure behavior.
-- The initial common OpenCode Client does not expose server-global event aggregation. `events.subscribe()` is bounded to the connected OpenCode instance or workspace; any future cross-instance administrative stream requires a separately designed API.
-- `events.subscribe()` does not automatically reconnect after transport loss. The live-only stream fails with `ClientError`; consumers refresh authoritative state before explicitly opening a new subscription because events missed during disconnection cannot be replayed.
-- `sessions.events({ sessionID, after })` returns the generated HTTP client's cold durable event stream and does not build reconnection policy into the endpoint or client constructor. Transport loss fails the stream with `ClientError`. Callers may compose an explicit resuming stream above it by retaining the last observed durable sequence and opening a new subscription with `after`; any reusable resume helper remains a separate API design question.
-- The stable `sessions.list(...)` design returns a **Page** in both networked and **Embedded OpenCode**; embedded execution does not define a separate unbounded array-returning list operation. The beta client currently preserves the existing HTTP `{ data, cursor }` envelope until emitter-level Page projection is implemented.
-- Session list cursors are opaque branded values carrying continuation query and ordering state. Consumers pass them back unchanged and do not inspect storage anchors or encoded filter fields.
-- A Session list continuation accepts only its opaque cursor. Scope, filters, ordering, and page size are fixed by the initial query and carried by that cursor.
-- `sessions.messages(...)` returns a **Page** and uses the same cursor discipline as `sessions.list(...)`: the initial request supplies `sessionID`, ordering, and page size; continuation supplies `sessionID` plus only an opaque branded message cursor carrying ordering, page size, direction, and message anchor. Using a cursor with another Session is invalid.
-- `sessions.message({ sessionID, messageID })` is a required resource lookup. An unknown Session fails with `SessionNotFoundError`; a known Session with an absent or differently owned message fails with `MessageNotFoundError` without disclosing cross-Session ownership. Absence is not represented as `undefined` across the public HTTP boundary.
-- `sessions.interrupt({ sessionID })` first verifies that the durable Session exists, failing with `SessionNotFoundError` otherwise. For a known Session, interruption is idempotent: idle, already-settled, or locally unowned execution is a no-op.
-- `sessions.active()` snapshots the current process's foreground Session drain registry as a record of Session IDs to `{ type: "running" }`. Missing IDs are inactive; background subagents and tasks do not make their parent Session active, and process restart clears the registry.
-- `sessions.context({ sessionID })` preserves the existing message-only operation. It returns projected **Session History**; it does not include or represent the complete **Model Context**, whose system text, **Instruction Baseline**, tools, and step-local additions remain separate.
-- **Open question**: Should a future, separately named operation expose complete **Model Context**, including the instruction baseline, applied instruction metadata, tools, and step-local additions?
-- `sessions.prompt(...)` exposes `resume?: boolean`. Omitting it preserves durable admission followed by an advisory execution wake; `resume: false` requests durable admit-only behavior.
-- The public operation remains `sessions.prompt(...)`; `SessionPending.admit` is the internal primitive, while the public `Admission` result and `resume` option express its durable admission semantics.
-- `sessions.create(...)` accepts an optional `location`. Omission resolves through the connected OpenCode instance's default or current location; an explicit value selects a known location. Networked and embedded transports use the same handler semantics.
-- `sessions.switchAgent({ sessionID, agent })` is part of the common client alongside `sessions.switchModel(...)`. It affects subsequent Session activity and fails with `SessionNotFoundError` for an unknown Session.
-- The **Embedded OpenCode** Layer delegates to the same scoped creation path; it does not define a second implementation.
-- A **PTY Environment** adapter observes plugins in the request Location while passing the resolved PTY working directory to the hook; standalone servers use an empty adapter.
-- An **Instruction Update** lowers to the provider's native chronological instruction role when supported and to a wrapped chronological fallback otherwise.
-- When the aggregate discovered instruction set changes, its **Instruction Update** includes the complete current ordered set and supersedes the prior aggregate value; when no discovered instructions remain, the message states that previously loaded instructions no longer apply.
-- Ambient project instruction discovery honors `OPENCODE_DISABLE_PROJECT_CONFIG`; global instructions remain eligible.
-- Oversized textual **Model Tool Output** retains a bounded preview in Session history while its complete text moves to managed tool-output storage. Arbitrary structured-result size is a separate concern.
-- One tool settlement receives one aggregate textual limit, using the configured maximum lines or UTF-8 bytes, whichever is reached first. The limit is provider-independent; token pressure belongs to context assembly and compaction.
-- Generic truncation preserves the beginning and end of textual output. Tools may apply a more meaningful strategy before the Tool Registry enforces the final limit.
-- A truncated **Model Tool Output** identifies its complete text both in the bounded model-visible preview and as a typed managed output path. Managed output paths do not modify the tool's validated structured result.
-- A **Managed Tool Output File** is temporary and may expire after its retention period. The bounded **Model Tool Output**, not the file, is the durable replayable record.
-- Failure to retain a **Managed Tool Output File** does not change a successful tool operation into a failed one. The Session records an explicitly lossy bounded output without a path, while operators receive diagnostics for the storage failure.
-- Once a tool operation succeeds, bounding its **Model Tool Output** and publishing its one durable settlement form an interruption-safe completion region. Raw oversized success is never published before a later correction.
-- When a structured-only result would exceed the **Model Tool Output** limit, its validated structured value remains unchanged for Session consumers while model replay uses a bounded textual JSON preview and optional managed output path.
-- Existing tool-managed output paths survive generic bounding. A fallback file retains exactly the complete projected text received by the Tool Registry and never claims to reconstruct output already discarded by tool-specific shaping.
-- **Managed Tool Output Files** use globally unique names in one shared flat directory. Their absolute paths are readable and searchable by ordinary tools; other absolute paths remain outside Location-scoped filesystem authority.
-- Provider-executed tool results remain provider-native transcript facts outside generic Tool Registry bounding. Their context control requires provider-aware pruning or compaction because some providers require exact structured round-trip payloads.
-
-## Client contract architecture
-
-Semantic values that mean the same thing internally and publicly live in the lightweight Schema leaf. Core consumes Schema for domain behavior; Protocol composes Schema values into paths, payloads, envelopes, errors, cursors, and streams; Server imports both, hosts Protocol's exact groups, and owns protocol/domain adaptation. The root Promise client remains zero-Effect, `/effect` depends on Effect plus Schema and Protocol, and `@opencode-ai/sdk-next` composes the scoped in-process host above Client, Core, and Server.
-
-Shared public records are plain objects declared with `Schema.Struct`. A same-name inferred interface gives object records readable TypeScript signatures without constructors, prototypes, or nominal identity; unions retain explicit type aliases.
-
-Before stabilizing the client API:
-
-- Keep additional public schemas in Schema and additional network groups in Protocol; neither package may transitively load databases, Drizzle, Session execution, providers, watchers, native modules, or WASM.
-- Keep concrete Location middleware keys in Server while Protocol owns their placement. Client projections may supply transport-only keys, but must prove generated equivalence with Server's concrete API.
-- Project the existing list response envelope to the stable client **Page** shape and enforce separate initial-query and cursor-continuation inputs without changing the hosted V2 wire contract.
-- Settle the stable consumer namespace (`session` versus the current beta `sessions`) and use an explicit codegen annotation if the consumer name should differ from the server group identifier.
-- Preserve V2 route paths, operation IDs, codecs, errors, middleware behavior, and OpenAPI output while making this change.
-- Preserve browser-safe `@opencode-ai/client` and `@opencode-ai/client/effect` bundles through import-boundary tests.
-- Define embedded-host placement before supporting multiple hosts over one database. Hosts that share durable Session storage must also share process-local Session execution coordination, or each host must receive isolated storage explicitly.
-- Keep an embedded request scope alive until any streamed response body finishes. The initial non-streaming Session surface does not exercise this lifetime boundary; Session and instance event streams must do so before joining the embedded client.
-
-## Example dialogue
-
-> **Dev:** "The date changed while the session was active. Should the **Instruction Update** say what the old date was?"
-> **Domain expert:** "No. Emit the newly effective date so the agent can act on the current instructions."
-
-## Flagged ambiguities
-
-- Legacy `experimental.chat.system.transform` can mutate assembled system text arbitrarily, but V2 plugins do not yet expose an equivalent hook. Decide separately whether to port it, model dynamic uses as explicit **Instruction Sources**, or narrow its semantics.

artifacts/glm52-rise-video/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../sst-env.d.ts" />
+
+import "sst"
+export {}

infra/lake.ts

@@ -67,6 +67,10 @@ const athenaWorkgroup = new aws.athena.Workgroup("LakeAthenaWorkgroup", {
   configuration: {
     enforceWorkgroupConfiguration: true,
     publishCloudwatchMetricsEnabled: true,
+    // Athena bills $5/TB scanned; kill any query that would scan more than 2 TB
+    // so a regression cannot silently burn money. Stats sync full passes scan
+    // ~250 GB as of 2026-07.
+    bytesScannedCutoffPerQuery: 2 * 1024 ** 4,
     resultConfiguration: {
       outputLocation: $interpolate`s3://${athenaResultsBucket.bucket}/`,
     },

infra/stats.ts

@@ -185,7 +185,9 @@ export const statSync = new sst.aws.Service("StatsSyncService", {
   cluster: lakeCluster,
   architecture: "arm64",
   cpu: "0.25 vCPU",
-  memory: "0.5 GB",
+  // 0.5 GB caused an OOM crash loop: every restart immediately re-ran the 4 Athena
+  // stats queries (~$5/pass) every ~5 minutes instead of hourly.
+  memory: "2 GB",
   image: {
     context: ".",
     dockerfile: "packages/stats/server/Dockerfile",

package.json

@@ -12,6 +12,7 @@
     "dev:web": "bun --cwd packages/app dev",
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",
     "dev:stats": "bun sst shell --stage=production -- bun run --cwd packages/stats/app dev",
+    "dev:www": "bun run --cwd packages/www dev",
     "dev:storybook": "bun --cwd packages/storybook storybook",
     "lint": "oxlint",
     "lint:effect-patterns": "ast-grep scan -c script/ast-grep/sgconfig.yml packages/core/src packages/server/src packages/protocol/src packages/cli/src",
@@ -102,6 +103,8 @@
   "devDependencies": {
     "@actions/artifact": "5.0.1",
     "@ast-grep/cli": "0.44.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
     "@tsconfig/bun": "catalog:",
     "@types/mime-types": "3.0.1",
     "@typescript/native-preview": "catalog:",

packages/app/e2e/regression/review-open-file.spec.ts

@@ -74,6 +74,10 @@ test("opens and searches project files inline", async ({ page }) => {
         "opencode.global.dat:layout",
         JSON.stringify({ review: { diffStyle: "split", panelOpened: true } }),
       )
+      localStorage.setItem(
+        "opencode.global.dat:review-panel-v2",
+        JSON.stringify({ sidebarOpened: false, sidebarWidth: 240, expandMode: "collapse" }),
+      )
       localStorage.setItem(
         "opencode.window.browser.dat:tabs",
         JSON.stringify([{ type: "session", server, sessionId: sessionID }]),
@@ -86,13 +90,16 @@ test("opens and searches project files inline", async ({ page }) => {
   await expectSessionTitle(page, title)
 
   const panel = page.locator("#review-panel")
+  const sidebar = panel.locator('[data-slot="session-review-v2-sidebar"]')
   const contextButton = page.getByRole("button", { name: "View context usage" })
   await contextButton.click()
   await expect(panel.getByRole("tab", { name: "Context" })).toHaveAttribute("data-selected", "")
   await panel.getByRole("button", { name: "Open file" }).click()
   await expect(panel.getByRole("tab", { name: "Open file" })).toHaveAttribute("data-selected", "")
+  await expect(sidebar).toBeVisible()
   await contextButton.click()
   await expect(panel.getByRole("tab", { name: "Context" })).toHaveAttribute("data-selected", "")
+  await expect(sidebar).toHaveCount(0)
   await panel.getByRole("button", { name: "Open file" }).click()
   const filter = panel.getByRole("combobox", { name: "Filter files" })
   await expect(filter).toBeFocused()
@@ -102,9 +109,11 @@ test("opens and searches project files inline", async ({ page }) => {
   await panel.getByRole("button", { name: "README.md" }).click()
   await expect(panel.getByRole("tab", { name: "README.md" })).toHaveAttribute("data-selected", "")
   await expect(panel.getByText("contents:README.md", { exact: true })).toBeVisible()
+  await expect(sidebar).toHaveCount(0)
 
   await panel.getByRole("button", { name: "Open file" }).click()
   await expect(panel.getByRole("tab", { name: "README.md" })).toHaveCount(0)
+  await expect(sidebar).toBeVisible()
   await filter.fill("nested")
   const result = panel.getByRole("option", { name: /nested\.ts/ })
   await expect(result).toBeVisible()

packages/app/e2e/regression/session-timeline-shell-outline.spec.ts

@@ -0,0 +1,228 @@
+import { expect, test, type Locator, type Page } from "@playwright/test"
+import {
+  assistantMessage,
+  setupTimeline,
+  shell,
+  textPart,
+  toolPart,
+  userMessage,
+} from "../performance/timeline-stability/fixture"
+
+for (const deviceScaleFactor of [1.25, 1.5]) {
+  test(`keeps the shell outline inside a fractionally short virtual row at ${deviceScaleFactor}x`, async ({ page }) => {
+    const shellID = "prt_shell_outline"
+    const timeline = await setupTimeline(page, {
+      messages: [userMessage(), assistantMessage([shell(shellID, "completed", "shell output")])],
+      settings: { newLayoutDesigns: true, shellToolPartsExpanded: true },
+      reducedMotion: true,
+      deviceScaleFactor,
+    })
+    const part = page.locator(`[data-timeline-part-id="${shellID}"]`)
+    const output = part.locator('[data-component="bash-output"]')
+    const row = page.locator("[data-timeline-key]", { has: part })
+    await expect(output).toBeVisible()
+    await timeline.settle()
+
+    const geometry = await row.evaluate((element) => {
+      const output = element.querySelector<HTMLElement>('[data-component="bash-output"]')
+      if (!output) throw new Error("Shell output is unavailable")
+      const rowRect = element.getBoundingClientRect()
+      const outputRect = output.getBoundingClientRect()
+      // Match a rounded-down measurement at a fractional device-pixel phase.
+      element.style.height = `${outputRect.bottom - rowRect.top - 0.49}px`
+      element.style.transform = "translateY(0.25px)"
+      output.style.setProperty("--v2-border-border-base", "rgb(255, 0, 255)")
+      output.style.setProperty("background", "rgb(0, 0, 0)", "important")
+      const style = getComputedStyle(output)
+      return {
+        outputWidth: outputRect.width,
+        outputHeight: outputRect.height,
+        borderColor: style.borderTopColor,
+        boxShadow: style.boxShadow,
+        clipMargin: getComputedStyle(element).overflowClipMargin,
+      }
+    })
+    await timeline.settle()
+
+    const clipped = await row.evaluate((element) => {
+      const output = element.querySelector<HTMLElement>('[data-component="bash-output"]')!
+      return output.getBoundingClientRect().bottom - element.getBoundingClientRect().bottom
+    })
+    expect(clipped).toBeCloseTo(0.49, 1)
+
+    expect(await page.evaluate(() => devicePixelRatio)).toBe(deviceScaleFactor)
+    const edges = await captureCardEdges(page, output)
+
+    expect(edges.box.width).toBeCloseTo(geometry.outputWidth, 2)
+    expect(edges.box.height).toBeCloseTo(geometry.outputHeight, 2)
+    expect(geometry.borderColor).toBe("rgb(255, 0, 255)")
+    expect(geometry.boxShadow).toBe("none")
+    expect(geometry.clipMargin).toBe("0.5px")
+    expect(edges.magenta.top).toBeGreaterThan(0.75)
+    expect(edges.magenta.bottom).toBeGreaterThan(0.75)
+    expect(edges.magenta.vertical).toBeGreaterThanOrEqual(2)
+  })
+}
+
+test("keeps the patch card inside a fractionally short virtual row", async ({ page }) => {
+  const patchID = "prt_patch_outline"
+  const file = {
+    filePath: "src/outline.ts",
+    relativePath: "src/outline.ts",
+    type: "update",
+    additions: 1,
+    deletions: 1,
+    before: "const outline = false\n",
+    after: "const outline = true\n",
+  }
+  const timeline = await setupTimeline(page, {
+    messages: [
+      userMessage(),
+      assistantMessage([
+        toolPart(patchID, "apply_patch", "completed", { files: [file.filePath] }, { metadata: { files: [file] } }),
+      ]),
+    ],
+    settings: { editToolPartsExpanded: true, newLayoutDesigns: true },
+    reducedMotion: true,
+  })
+  const part = page.locator(`[data-timeline-part-id="${patchID}"]`)
+  const card = part.locator('[data-component="accordion"][data-scope="apply-patch"]')
+  const row = page.locator("[data-timeline-key]", { has: part })
+  await expect(card).toBeVisible()
+  await timeline.settle()
+
+  const geometry = await row.evaluate((element) => {
+    const card = element.querySelector<HTMLElement>('[data-component="accordion"][data-scope="apply-patch"]')
+    if (!card) throw new Error("Patch card is unavailable")
+    const rowRect = element.getBoundingClientRect()
+    const cardRect = card.getBoundingClientRect()
+    element.style.height = `${cardRect.bottom - rowRect.top - 0.49}px`
+    const clipMargin = getComputedStyle(element).overflowClipMargin
+    const bottom = element.getBoundingClientRect().bottom
+    return {
+      overflow: card.getBoundingClientRect().bottom - bottom,
+      paintOverflow: card.getBoundingClientRect().bottom - bottom - Number.parseFloat(clipMargin),
+      clipMargin,
+      cardWidth: cardRect.width,
+      cardHeight: cardRect.height,
+    }
+  })
+  await timeline.settle()
+
+  expect(geometry.overflow).toBeCloseTo(0.49, 1)
+  expect(geometry.paintOverflow).toBeLessThanOrEqual(0)
+  const edges = await captureCardEdges(page, card)
+  expect(edges.box.width).toBeCloseTo(geometry.cardWidth, 2)
+  expect(edges.box.height).toBeCloseTo(geometry.cardHeight, 2)
+  expect(edges.luminance.top).toBeLessThan(245)
+  expect(edges.luminance.bottom).toBeLessThan(245)
+  expect(Math.abs(edges.luminance.bottom - edges.luminance.top)).toBeLessThan(10)
+  expect(geometry.clipMargin).toBe("0.5px")
+})
+
+test("allows paint rounding for every framed row but not fixed turn gaps", async ({ page }) => {
+  const secondUserID = "msg_outline_second_user"
+  await setupTimeline(page, {
+    messages: [
+      userMessage(undefined, {
+        summary: {
+          diffs: [
+            {
+              file: "src/summary.ts",
+              additions: 1,
+              deletions: 1,
+              patch: "@@ -1 +1 @@\n-export const value = 1\n+export const value = 2",
+            },
+          ],
+        },
+      }),
+      assistantMessage([textPart("prt_outline_text", "Assistant text")]),
+      userMessage(undefined, { id: secondUserID, created: 1700000010000 }),
+      assistantMessage([], {
+        id: "msg_outline_second_assistant",
+        parentID: secondUserID,
+        created: 1700000011000,
+      }),
+    ],
+  })
+  await expect(page.locator('[data-timeline-row="DiffSummary"]')).toBeVisible()
+  await expect(page.locator('[data-timeline-row="TurnGap"]')).toBeVisible()
+
+  const rows = await page.locator("[data-timeline-key]").evaluateAll((elements) =>
+    elements.map((element) => ({
+      tag: element.querySelector<HTMLElement>("[data-timeline-row]")?.dataset.timelineRow,
+      clipMargin: getComputedStyle(element).overflowClipMargin,
+    })),
+  )
+  expect(rows.filter((row) => row.tag !== "TurnGap").every((row) => row.clipMargin === "0.5px")).toBe(true)
+  expect(rows.filter((row) => row.tag === "TurnGap")).toEqual([{ tag: "TurnGap", clipMargin: "0px" }])
+})
+
+async function captureCardEdges(page: Page, card: Locator) {
+  const box = await card.boundingBox()
+  if (!box) throw new Error("Tool card bounds are unavailable")
+  const viewport = page.viewportSize()
+  if (!viewport) throw new Error("Viewport bounds are unavailable")
+  const screenshot = await page.screenshot()
+  return page.evaluate(
+    async ({ source, box, viewport }) => {
+      const image = new Image()
+      image.src = source
+      await image.decode()
+      const canvas = document.createElement("canvas")
+      canvas.width = image.naturalWidth
+      canvas.height = image.naturalHeight
+      const context = canvas.getContext("2d")
+      if (!context) throw new Error("2D canvas is unavailable")
+      context.drawImage(image, 0, 0)
+      const scale = {
+        x: image.naturalWidth / viewport.width,
+        y: image.naturalHeight / viewport.height,
+      }
+      const rows = (candidates: number[]) => {
+        const left = Math.floor((box.x + 8) * scale.x)
+        const width = Math.floor((box.width - 16) * scale.x)
+        return candidates.map((row) => {
+          const pixels = context.getImageData(left, row, width, 1).data
+          const indexes = Array.from({ length: width }, (_, index) => index * 4)
+          return {
+            luminance:
+              indexes
+                .map((index) => (pixels[index]! + pixels[index + 1]! + pixels[index + 2]!) / 3)
+                .reduce((sum, value) => sum + value, 0) / width,
+            magenta:
+              indexes.filter((index) => pixels[index]! > 200 && pixels[index + 1]! < 180 && pixels[index + 2]! > 200)
+                .length / width,
+          }
+        })
+      }
+      const pixels = context.getImageData(0, 0, image.naturalWidth, image.naturalHeight).data
+      const columns = new Uint32Array(image.naturalWidth)
+      for (let index = 0; index < pixels.length; index += 4) {
+        if (pixels[index]! <= 200 || pixels[index + 1]! >= 180 || pixels[index + 2]! <= 200) continue
+        columns[(index / 4) % image.naturalWidth] = columns[(index / 4) % image.naturalWidth]! + 1
+      }
+      const top = box.y * scale.y
+      const bottom = (box.y + box.height) * scale.y
+      const topRows = rows([Math.floor(top) - 1, Math.floor(top), Math.ceil(top)])
+      const bottomRows = rows([Math.floor(bottom) - 2, Math.floor(bottom) - 1, Math.ceil(bottom) - 1])
+      return {
+        box,
+        luminance: {
+          top: Math.min(...topRows.map((row) => row.luminance)),
+          bottom: rows([Math.ceil(bottom) - 1])[0]!.luminance,
+        },
+        magenta: {
+          top: Math.max(...topRows.map((row) => row.magenta)),
+          bottom: Math.max(...bottomRows.map((row) => row.magenta)),
+          vertical: Array.from(columns).filter((count) => count > box.height * scale.y * 0.75).length,
+        },
+      }
+    },
+    {
+      source: `data:image/png;base64,${screenshot.toString("base64")}`,
+      viewport,
+      box,
+    },
+  )
+}

packages/app/src/components/prompt-input.tsx

@@ -36,6 +36,8 @@ import { Icon } from "@opencode-ai/ui/icon"
 import { ProviderIcon } from "@opencode-ai/ui/provider-icon"
 import { Tooltip, TooltipKeybind } from "@opencode-ai/ui/tooltip"
 import { ButtonV2 } from "@opencode-ai/ui/v2/button-v2"
+import { Icon as IconV2 } from "@opencode-ai/ui/v2/icon"
+import { IconButtonV2 } from "@opencode-ai/ui/v2/icon-button-v2"
 import { KeybindV2 } from "@opencode-ai/ui/v2/keybind-v2"
 import { MenuV2 } from "@opencode-ai/ui/v2/menu-v2"
 import { TooltipV2 } from "@opencode-ai/ui/v2/tooltip-v2"
@@ -1333,6 +1335,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
       onQueue: props.onQueue,
       onAbort: props.onAbort,
       onSubmit: props.onSubmit,
+      model: props.controls.model.selection,
     })
 
   const handleKeyDown = (event: KeyboardEvent) => {
@@ -1704,22 +1707,19 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
                   >
                     <MenuV2 gutter={6} modal={false} placement="top-start">
                       <MenuV2.Trigger
-                        as={IconButton}
+                        as={IconButtonV2}
                         data-action="prompt-attach"
                         type="button"
-                        icon="plus"
-                        variant="ghost"
-                        class="size-7 rounded-md p-[6px] text-v2-icon-icon-muted"
+                        icon={<IconV2 name="plus" />}
+                        variant="ghost-muted"
+                        size="large"
                         style={buttons()}
                         disabled={store.mode !== "normal"}
                         tabIndex={store.mode === "normal" ? undefined : -1}
                         aria-label={language.t("prompt.menu.addImagesAndFiles")}
                       />
                       <MenuV2.Portal>
-                        <MenuV2.Content
-                          class="[&_[data-slot=menu-v2-item-shortcut]]:w-5 [&_[data-slot=menu-v2-item-shortcut]]:justify-center"
-                          style={{ "min-width": "180px" }}
-                        >
+                        <MenuV2.Content style={{ "min-width": "180px" }}>
                           <MenuV2.Item onSelect={pick} shortcut={command.keybind("file.attach")}>
                             {language.t("prompt.menu.imagesAndFiles")}
                           </MenuV2.Item>

packages/app/src/components/prompt-input/submit.test.ts

@@ -1,5 +1,6 @@
 import { beforeAll, beforeEach, describe, expect, mock, test } from "bun:test"
 import type { Prompt } from "@/context/prompt"
+import type { ModelSelection } from "@/context/local"
 
 let createPromptSubmit: typeof import("./submit").createPromptSubmit
 
@@ -33,6 +34,10 @@ const prompt = {
   current: () => promptValue,
   cursor: () => 0,
   dirty: () => true,
+  model: {
+    current: () => undefined,
+    set: () => undefined,
+  },
   reset: () => undefined,
   set: () => undefined,
   context: {
@@ -378,6 +383,39 @@ describe("prompt submit worktree selection", () => {
     })
   })
 
+  test("uses an injected model selection", async () => {
+    params = { id: "session-1" }
+    const model = {
+      current: () => ({ id: "draft-model", provider: { id: "draft-provider" } }),
+      variant: { current: () => "draft-variant" },
+    } as unknown as ModelSelection
+    const submit = createPromptSubmit({
+      prompt,
+      info: () => ({ id: "session-1" }),
+      imageAttachments: () => [],
+      commentCount: () => 0,
+      autoAccept: () => false,
+      mode: () => "normal",
+      working: () => false,
+      editor: () => undefined,
+      queueScroll: () => undefined,
+      promptLength: (value) => value.reduce((sum, part) => sum + ("content" in part ? part.content.length : 0), 0),
+      addToHistory: () => undefined,
+      resetHistoryNavigation: () => undefined,
+      setMode: () => undefined,
+      setPopover: () => undefined,
+      model,
+    })
+
+    await submit.handleSubmit({ preventDefault: () => undefined } as unknown as Event)
+
+    expect(optimistic[0]).toMatchObject({
+      message: {
+        model: { providerID: "draft-provider", modelID: "draft-model", variant: "draft-variant" },
+      },
+    })
+  })
+
   test("seeds new sessions before optimistic prompts are added", async () => {
     const submit = createPromptSubmit({
       prompt,

packages/app/src/components/prompt-input/submit.ts

@@ -3,12 +3,12 @@ import { showToast } from "@/utils/toast"
 import { base64Encode } from "@opencode-ai/core/util/encode"
 import { Binary } from "@opencode-ai/core/util/binary"
 import { useNavigate, useParams, useSearchParams } from "@solidjs/router"
-import { batch, type Accessor } from "solid-js"
+import { batch, startTransition, type Accessor } from "solid-js"
 import { useTabs } from "@/context/tabs"
 import { useServerSync, type ServerSync } from "@/context/server-sync"
 import { useLanguage } from "@/context/language"
 import { useLayout } from "@/context/layout"
-import { useLocal } from "@/context/local"
+import { useLocal, type ModelSelection } from "@/context/local"
 import { usePermission } from "@/context/permission"
 import { type ContextItem, type ImageAttachmentPart, type Prompt, type usePrompt } from "@/context/prompt"
 import { useSDK, type DirectorySDK } from "@/context/sdk"
@@ -191,6 +191,7 @@ type PromptSubmitInput = {
   onQueue?: (draft: FollowupDraft) => void
   onAbort?: () => void
   onSubmit?: () => void
+  model?: ModelSelection
 }
 
 export function createPromptSubmit(input: PromptSubmitInput) {
@@ -296,9 +297,10 @@ export function createPromptSubmit(input: PromptSubmitInput) {
       return
     }
 
-    const currentModel = local.model.current()
+    const modelSelection = input.model ?? local.model
+    const currentModel = modelSelection.current()
     const currentAgent = local.agent.current()
-    const variant = local.model.variant.current()
+    const variant = modelSelection.variant.current()
     if (!currentModel || !currentAgent) {
       showToast({
         title: language.t("prompt.toast.modelAgentRequired.title"),
@@ -372,13 +374,20 @@ export function createPromptSubmit(input: PromptSubmitInput) {
       if (created) {
         seed(sessionDirectory, created)
         session = created
-        if (shouldAutoAccept) permission.enableAutoAccept(session.id, sessionDirectory)
-        local.session.promote(sessionDirectory, session.id)
-        layout.handoff.setTabs(base64Encode(sessionDirectory), session.id)
-        const draftID = search.draftId
-        if (draftID) tabs.promoteDraft(draftID, { server: tabs.draft(draftID).server, sessionId: session.id })
-        else navigate(`/${base64Encode(sessionDirectory)}/session/${session.id}`)
-        submission.retarget(prompt.capture({ dir: base64Encode(sessionDirectory), id: session.id }))
+        await startTransition(() => {
+          if (!session) return
+          if (shouldAutoAccept) permission.enableAutoAccept(session.id, sessionDirectory)
+          local.session.promote(sessionDirectory, session.id, {
+            agent: currentAgent.name,
+            model: { providerID: currentModel.provider.id, modelID: currentModel.id },
+            variant: variant ?? null,
+          })
+          layout.handoff.setTabs(base64Encode(sessionDirectory), session.id)
+          const draftID = search.draftId
+          if (draftID) tabs.promoteDraft(draftID, { server: tabs.draft(draftID).server, sessionId: session.id })
+          else navigate(`/${base64Encode(sessionDirectory)}/session/${session.id}`)
+          submission.retarget(prompt.capture({ dir: base64Encode(sessionDirectory), id: session.id }))
+        })
       }
     }
     if (!session) {

packages/app/src/components/session-context-usage.tsx

@@ -12,7 +12,7 @@ import { useSync } from "@/context/sync"
 import { useLanguage } from "@/context/language"
 import { useProviders } from "@/hooks/use-providers"
 import { useSDK } from "@/context/sdk"
-import { getSessionContext, getSessionTokenTotal } from "@/components/session/session-context-metrics"
+import { getSessionContext } from "@/components/session/session-context-metrics"
 import { useSessionLayout } from "@/pages/session/session-layout"
 import { createSessionTabs } from "@/pages/session/helpers"
 import { useSettings } from "@/context/settings"
@@ -74,7 +74,6 @@ export function SessionContextUsage(props: SessionContextUsageProps) {
   )
 
   const context = createMemo(() => getSessionContext(messages(), [...providers.all().values()]))
-  const tokens = createMemo(() => info()?.tokens)
   const cost = createMemo(() => {
     return usd().format(info()?.cost ?? 0)
   })
@@ -132,7 +131,7 @@ export function SessionContextUsage(props: SessionContextUsageProps) {
       <ContextTooltipRow name={language.t("context.usage.usage")} value={`${context()?.usage ?? 0}%`} />
       <ContextTooltipRow
         name={language.t("context.usage.tokens")}
-        value={getSessionTokenTotal(tokens())?.toLocaleString(language.intl()) ?? "0"}
+        value={context()?.total.toLocaleString(language.intl()) ?? "0"}
       />
     </div>
   )

packages/app/src/components/session/session-context-metrics.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import type { Message } from "@opencode-ai/sdk/v2/client"
-import { getSessionContext, getSessionTokenTotal } from "./session-context-metrics"
+import { getSessionContext } from "./session-context-metrics"
 
 const assistant = (
   id: string,
@@ -38,10 +38,10 @@ const user = (id: string) => {
 }
 
 describe("getSessionContext", () => {
-  test("computes usage from latest assistant with tokens", () => {
+  test("computes token totals and usage from latest assistant with tokens", () => {
     const messages = [
       user("u1"),
-      assistant("a1", { input: 0, output: 0, reasoning: 0, read: 0, write: 0 }, 0.5),
+      assistant("a1", { input: 600, output: 200, reasoning: 100, read: 50, write: 50 }, 0.5),
       assistant("a2", { input: 300, output: 100, reasoning: 50, read: 25, write: 25 }, 1.25),
     ]
     const providers = [
@@ -60,6 +60,8 @@ describe("getSessionContext", () => {
     const ctx = getSessionContext(messages, providers)
 
     expect(ctx?.message.id).toBe("a2")
+    expect(ctx?.total).toBe(500)
+    expect(ctx?.input).toBe(300)
     expect(ctx?.usage).toBe(50)
     expect(ctx?.providerLabel).toBe("OpenAI")
     expect(ctx?.modelLabel).toBe("GPT-4.1")
@@ -94,15 +96,4 @@ describe("getSessionContext", () => {
 
     expect(ctx).toBeUndefined()
   })
-
-  test("computes stored session token totals", () => {
-    expect(
-      getSessionTokenTotal({
-        input: 10,
-        output: 20,
-        reasoning: 30,
-        cache: { read: 40, write: 50 },
-      }),
-    ).toBe(150)
-  })
 })

packages/app/src/components/session/session-context-metrics.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, Message, Session } from "@opencode-ai/sdk/v2/client"
+import type { AssistantMessage, Message } from "@opencode-ai/sdk/v2/client"
 
 type Provider = {
   id: string
@@ -21,6 +21,7 @@ type Context = {
   modelLabel: string
   limit: number | undefined
   input: number
+  total: number
   usage: number | null
 }
 
@@ -54,6 +55,7 @@ const build = (messages: Message[] = [], providers: Provider[] = []): Context |
     modelLabel: model?.name ?? message.modelID,
     limit,
     input: message.tokens.input,
+    total,
     usage: limit ? Math.round((total / limit) * 100) : null,
   }
 }
@@ -61,8 +63,3 @@ const build = (messages: Message[] = [], providers: Provider[] = []): Context |
 export function getSessionContext(messages: Message[] = [], providers: Provider[] = []) {
   return build(messages, providers)
 }
-
-export function getSessionTokenTotal(tokens: Session["tokens"] | undefined) {
-  if (!tokens) return undefined
-  return tokens.input + tokens.output + tokens.reasoning + tokens.cache.read + tokens.cache.write
-}

packages/app/src/components/session/session-context-tab.tsx

@@ -15,7 +15,7 @@ import { useLanguage } from "@/context/language"
 import { useProviders } from "@/hooks/use-providers"
 import { useSDK } from "@/context/sdk"
 import { useSessionLayout } from "@/pages/session/session-layout"
-import { getSessionContext, getSessionTokenTotal } from "./session-context-metrics"
+import { getSessionContext } from "./session-context-metrics"
 import { estimateSessionContextBreakdown, type SessionContextBreakdownKey } from "./session-context-breakdown"
 import { createSessionContextFormatter } from "./session-context-format"
 
@@ -135,7 +135,6 @@ export function SessionContextTab() {
   )
 
   const ctx = createMemo(() => getSessionContext(messages(), [...providers.all().values()]))
-  const tokens = createMemo(() => info()?.tokens)
   const formatter = createMemo(() => createSessionContextFormatter(language.intl()))
 
   const cost = createMemo(() => {
@@ -204,14 +203,15 @@ export function SessionContextTab() {
     { label: "context.stats.provider", value: providerLabel },
     { label: "context.stats.model", value: modelLabel },
     { label: "context.stats.limit", value: () => formatter().number(ctx()?.limit) },
-    { label: "context.stats.totalTokens", value: () => formatter().number(getSessionTokenTotal(tokens())) },
+    { label: "context.stats.totalTokens", value: () => formatter().number(ctx()?.total) },
     { label: "context.stats.usage", value: () => formatter().percent(ctx()?.usage) },
-    { label: "context.stats.inputTokens", value: () => formatter().number(tokens()?.input) },
-    { label: "context.stats.outputTokens", value: () => formatter().number(tokens()?.output) },
-    { label: "context.stats.reasoningTokens", value: () => formatter().number(tokens()?.reasoning) },
+    { label: "context.stats.inputTokens", value: () => formatter().number(ctx()?.input) },
+    { label: "context.stats.outputTokens", value: () => formatter().number(ctx()?.message.tokens.output) },
+    { label: "context.stats.reasoningTokens", value: () => formatter().number(ctx()?.message.tokens.reasoning) },
     {
       label: "context.stats.cacheTokens",
-      value: () => `${formatter().number(tokens()?.cache.read)} / ${formatter().number(tokens()?.cache.write)}`,
+      value: () =>
+        `${formatter().number(ctx()?.message.tokens.cache.read)} / ${formatter().number(ctx()?.message.tokens.cache.write)}`,
     },
     { label: "context.stats.userMessages", value: () => counts().user.toLocaleString(language.intl()) },
     { label: "context.stats.assistantMessages", value: () => counts().assistant.toLocaleString(language.intl()) },

packages/app/src/components/session/session-sortable-terminal-tab-v2.tsx

@@ -211,7 +211,17 @@ export function SortableTerminalTabV2(props: {
           <MenuV2.Context.Trigger class="relative" as="div">
             <Tabs.Trigger
               value={props.terminal.id}
-              onClick={focus}
+              onMouseDown={(e) => {
+                // Switch on mousedown to shave the press-release delay off tab switches.
+                if (e.button !== 0) return
+                if (store.editing) return
+                focus()
+              }}
+              onClick={(e) => {
+                // Mouse navigation already happened on mousedown; detail 0 means keyboard activation.
+                if (e.detail > 0) return
+                focus()
+              }}
               closeButton={
                 <IconButton
                   icon="close-small"

packages/app/src/components/settings-v2/settings-v2.css

@@ -20,6 +20,11 @@
   height: 100%;
   overflow-y: auto;
   scrollbar-width: none;
+  user-select: none;
+}
+
+.settings-v2-panel :is(input, textarea, [contenteditable="true"]) {
+  user-select: text;
 }
 
 .settings-v2-panel::-webkit-scrollbar {
@@ -181,6 +186,7 @@
   flex-direction: column;
   gap: 8px;
   padding: 4px 0 4px 4px;
+  user-select: none;
 }
 
 .settings-v2-nav-footer > span {

packages/app/src/components/terminal.tsx

@@ -1,7 +1,8 @@
 import { withAlpha } from "@opencode-ai/ui/theme/color"
 import { useTheme } from "@opencode-ai/ui/theme/context"
 import { resolveThemeVariant } from "@opencode-ai/ui/theme/resolve"
-import type { HexColor } from "@opencode-ai/ui/theme/types"
+import { resolveThemeVariantV2 } from "@opencode-ai/ui/theme/v2/resolve"
+import type { HexColor, ResolvedV2Theme } from "@opencode-ai/ui/theme/types"
 import { showToast } from "@/utils/toast"
 import type { FitAddon, Ghostty, Terminal as Term } from "ghostty-web"
 import { type ComponentProps, createEffect, createMemo, onCleanup, onMount, splitProps } from "solid-js"
@@ -68,6 +69,19 @@ const debugTerminal = (...values: unknown[]) => {
   console.debug("[terminal]", ...values)
 }
 
+const resolveV2Token = (tokens: ResolvedV2Theme, key: string) => {
+  let current = tokens[key]
+  for (let i = 0; i < 8 && current; i++) {
+    const match = /^var\(--([^)]+)\)$/.exec(current.trim())
+    if (!match) {
+      const hex = current.trim()
+      if (/^#[0-9a-fA-F]{8}$/.test(hex)) return hex.slice(0, 7)
+      return hex
+    }
+    current = tokens[match[1]]
+  }
+}
+
 const useTerminalUiBindings = (input: {
   container: HTMLDivElement
   term: Term
@@ -238,7 +252,10 @@ export const Terminal = (props: TerminalProps) => {
     if (!variant?.seeds && !variant?.palette) return fallback
     const resolved = resolveThemeVariant(variant, mode === "dark")
     const text = resolved["text-stronger"] ?? fallback.foreground
-    const background = resolved["background-stronger"] ?? fallback.background
+    const background = settings.general.newLayoutDesigns()
+      ? (resolveV2Token(resolveThemeVariantV2(variant, mode === "dark"), "v2-background-bg-base") ??
+        fallback.background)
+      : (resolved["background-stronger"] ?? fallback.background)
     const alpha = mode === "dark" ? 0.25 : 0.2
     const base = text.startsWith("#") ? (text as HexColor) : (fallback.foreground as HexColor)
     const selectionBackground = withAlpha(base, alpha)

packages/app/src/components/titlebar.tsx

@@ -25,6 +25,7 @@ import { readSessionTabsRemovedDetail, SESSION_TABS_REMOVED_EVENT } from "@/comp
 import { useGlobal } from "@/context/global"
 import { ServerConnection, useServer } from "@/context/server"
 import { tabKey, useTabs } from "@/context/tabs"
+import type { PromptSession } from "@/context/prompt"
 import "./titlebar.css"
 import { newTabTooltipKeybind } from "./command-tooltip-keybind"
 
@@ -324,13 +325,20 @@ export function Titlebar(props: { update?: TitlebarUpdate }) {
               const route = layout.route()
               const activeSession = session()
               if (route.type === "session" && activeSession) {
-                tabs.newDraft({ server: route.server ?? server.key, directory: activeSession.directory }, "")
+                const sessionTab = {
+                  type: "session" as const,
+                  server: route.server ?? server.key,
+                  sessionId: activeSession.id,
+                }
+                const model = tabs.stateValue<PromptSession>(sessionTab, "prompt")?.model.current()
+                tabs.newDraft({ server: sessionTab.server, directory: activeSession.directory }, "", model)
                 return
               }
 
               const activeTab = currentTab()
               if (activeTab?.type === "draft") {
-                tabs.newDraft({ server: activeTab.server, directory: activeTab.directory }, "")
+                const model = tabs.stateValue<PromptSession>(activeTab, "prompt")?.model.current()
+                tabs.newDraft({ server: activeTab.server, directory: activeTab.directory }, "", model)
                 return
               }
 

packages/app/src/context/local.tsx

@@ -67,7 +67,7 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
     const list = createMemo(() => sync().data.agent.filter((item) => item.mode !== "subagent" && !item.hidden))
     const connected = createMemo(() => new Set(providers.connected().map((item) => item.id)))
 
-    const [saved, setSaved] = persisted(
+    const [saved, setSaved, , savedReady] = persisted(
       {
         ...Persist.serverWorkspace(serverSDK().scope, sdk().directory, "model-selection", ["model-selection.v1"]),
         migrate,
@@ -375,11 +375,12 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
       model,
       agent,
       session: {
+        ready: savedReady,
         reset() {
           setStore({ draft: undefined, promoting: undefined })
         },
-        promote(dir: string, session: string) {
-          const next = clone(snapshot())
+        promote(dir: string, session: string, state?: State) {
+          const next = clone(state ?? snapshot())
           if (!next) return
           const key = handoffKey(serverSDK().scope, dir, session)
           handoff.set(key, next)
@@ -409,3 +410,5 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
     return result
   },
 })
+
+export type ModelSelection = ReturnType<typeof useLocal>["model"]

packages/app/src/context/prompt-state.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { createPromptState, DEFAULT_PROMPT } from "./prompt-state"
+
+describe("prompt state initialization", () => {
+  test("initializes prompt text, cursor, and model together", () => {
+    createRoot((dispose) => {
+      const model = { providerID: "anthropic", modelID: "claude", variant: "high" }
+      const prompt = createPromptState({ prompt: "hello", model })
+
+      expect(prompt.current()).toEqual([{ type: "text", content: "hello", start: 0, end: 5 }])
+      expect(prompt.cursor()).toBe(5)
+      expect(prompt.model.current()).toEqual(model)
+      expect(prompt.model.current()).not.toBe(model)
+      dispose()
+    })
+  })
+
+  test("uses the default prompt without initial values", () => {
+    createRoot((dispose) => {
+      const prompt = createPromptState()
+
+      expect(prompt.current()).toEqual(DEFAULT_PROMPT)
+      expect(prompt.cursor()).toBeUndefined()
+      expect(prompt.model.current()).toBeUndefined()
+      dispose()
+    })
+  })
+})

packages/app/src/context/prompt-state.ts

@@ -0,0 +1,265 @@
+import { checksum } from "@opencode-ai/core/util/encode"
+import type { FilePartSource } from "@opencode-ai/sdk/v2/client"
+import { batch, createMemo, type Accessor } from "solid-js"
+import { createStore, type SetStoreFunction } from "solid-js/store"
+import type { FileSelection } from "@/context/file"
+import { Persist, persisted } from "@/utils/persist"
+import type { ServerScope } from "@/utils/server-scope"
+
+interface PartBase {
+  content: string
+  start: number
+  end: number
+}
+
+export interface TextPart extends PartBase {
+  type: "text"
+}
+
+export interface FileAttachmentPart extends PartBase {
+  type: "file"
+  path: string
+  selection?: FileSelection
+  mime?: string
+  filename?: string
+  url?: string
+  source?: FilePartSource
+}
+
+export interface AgentPart extends PartBase {
+  type: "agent"
+  name: string
+}
+
+export interface ImageAttachmentPart {
+  type: "image"
+  id: string
+  filename: string
+  sourcePath?: string
+  mime: string
+  dataUrl: string
+}
+
+export type ContentPart = TextPart | FileAttachmentPart | AgentPart | ImageAttachmentPart
+export type Prompt = ContentPart[]
+
+export type PromptModel = {
+  providerID: string
+  modelID: string
+  variant?: string | null
+}
+
+export type FileContextItem = {
+  type: "file"
+  path: string
+  selection?: FileSelection
+  comment?: string
+  commentID?: string
+  commentOrigin?: "review" | "file"
+  preview?: string
+}
+
+export type ContextItem = FileContextItem
+export type PromptScope = { draftID: string } | { dir: string; id?: string }
+
+export const DEFAULT_PROMPT: Prompt = [{ type: "text", content: "", start: 0, end: 0 }]
+
+type PromptStore = {
+  prompt: Prompt
+  cursor?: number
+  model?: PromptModel
+  context: {
+    items: (ContextItem & { key: string })[]
+  }
+}
+
+type InitialPrompt = {
+  prompt?: string
+  model?: PromptModel
+}
+
+function isSelectionEqual(a?: FileSelection, b?: FileSelection) {
+  if (!a && !b) return true
+  if (!a || !b) return false
+  return (
+    a.startLine === b.startLine && a.startChar === b.startChar && a.endLine === b.endLine && a.endChar === b.endChar
+  )
+}
+
+function isPartEqual(partA: ContentPart, partB: ContentPart) {
+  switch (partA.type) {
+    case "text":
+      return partB.type === "text" && partA.content === partB.content
+    case "file":
+      return (
+        partB.type === "file" &&
+        partA.path === partB.path &&
+        partA.mime === partB.mime &&
+        partA.filename === partB.filename &&
+        isSelectionEqual(partA.selection, partB.selection)
+      )
+    case "agent":
+      return partB.type === "agent" && partA.name === partB.name
+    case "image":
+      return partB.type === "image" && partA.id === partB.id
+  }
+}
+
+export function isPromptEqual(promptA: Prompt, promptB: Prompt): boolean {
+  if (promptA.length !== promptB.length) return false
+  for (let i = 0; i < promptA.length; i++) {
+    if (!isPartEqual(promptA[i], promptB[i])) return false
+  }
+  return true
+}
+
+function cloneSelection(selection?: FileSelection) {
+  if (!selection) return undefined
+  return { ...selection }
+}
+
+function clonePart(part: ContentPart): ContentPart {
+  if (part.type === "text") return { ...part }
+  if (part.type === "image") return { ...part }
+  if (part.type === "agent") return { ...part }
+  return {
+    ...part,
+    selection: cloneSelection(part.selection),
+  }
+}
+
+function clonePrompt(prompt: Prompt): Prompt {
+  return prompt.map(clonePart)
+}
+
+function contextItemKey(item: ContextItem) {
+  if (item.type !== "file") return item.type
+  const start = item.selection?.startLine
+  const end = item.selection?.endLine
+  const key = `${item.type}:${item.path}:${start}:${end}`
+
+  if (item.commentID) return `${key}:c=${item.commentID}`
+  const comment = item.comment?.trim()
+  if (!comment) return key
+  const digest = checksum(comment) ?? comment
+  return `${key}:c=${digest.slice(0, 8)}`
+}
+
+function isCommentItem(item: ContextItem | (ContextItem & { key: string })) {
+  return item.type === "file" && !!item.comment?.trim()
+}
+
+function createPromptActions(setStore: SetStoreFunction<PromptStore>) {
+  return {
+    set(prompt: Prompt, cursorPosition?: number) {
+      const next = clonePrompt(prompt)
+      batch(() => {
+        setStore("prompt", next)
+        if (cursorPosition !== undefined) setStore("cursor", cursorPosition)
+      })
+    },
+    reset() {
+      batch(() => {
+        setStore("prompt", clonePrompt(DEFAULT_PROMPT))
+        setStore("cursor", 0)
+      })
+    },
+  }
+}
+
+function promptTarget(serverScope: ServerScope, scope: PromptScope) {
+  if ("draftID" in scope) return Persist.draft(scope.draftID, "prompt")
+  const legacy = `${scope.dir}/prompt${scope.id ? "/" + scope.id : ""}.v2`
+  return Persist.serverScoped(serverScope, scope.dir, scope.id, "prompt", [legacy])
+}
+
+function promptStore(initial?: InitialPrompt): PromptStore {
+  const text = initial?.prompt
+  return {
+    prompt:
+      text === undefined ? clonePrompt(DEFAULT_PROMPT) : [{ type: "text", content: text, start: 0, end: text.length }],
+    cursor: text === undefined ? undefined : text.length,
+    model: initial?.model ? { ...initial.model } : undefined,
+    context: {
+      items: [],
+    },
+  }
+}
+
+function createPromptStateValue(store: PromptStore, setStore: SetStoreFunction<PromptStore>) {
+  const actions = createPromptActions(setStore)
+  const value = {
+    current: () => store.prompt,
+    cursor: createMemo(() => store.cursor),
+    dirty: () => !isPromptEqual(store.prompt, DEFAULT_PROMPT),
+    model: {
+      current: () => store.model,
+      set: (model: PromptModel | undefined) => setStore("model", model),
+    },
+    context: {
+      items: createMemo(() => store.context.items),
+      add(item: ContextItem) {
+        const key = contextItemKey(item)
+        if (store.context.items.find((x) => x.key === key)) return
+        setStore("context", "items", (items) => [...items, { key, ...item }])
+      },
+      remove(key: string) {
+        setStore("context", "items", (items) => items.filter((x) => x.key !== key))
+      },
+      removeComment(path: string, commentID: string) {
+        setStore("context", "items", (items) =>
+          items.filter((item) => !(item.type === "file" && item.path === path && item.commentID === commentID)),
+        )
+      },
+      updateComment(path: string, commentID: string, next: Partial<FileContextItem> & { comment?: string }) {
+        setStore("context", "items", (items) =>
+          items.map((item) => {
+            if (item.type !== "file" || item.path !== path || item.commentID !== commentID) return item
+            const value = { ...item, ...next }
+            return { ...value, key: contextItemKey(value) }
+          }),
+        )
+      },
+      replaceComments(items: FileContextItem[]) {
+        setStore("context", "items", (current) => [
+          ...current.filter((item) => !isCommentItem(item)),
+          ...items.map((item) => ({ ...item, key: contextItemKey(item) })),
+        ])
+      },
+    },
+    set: actions.set,
+    reset: actions.reset,
+    capture: () => value,
+  }
+  return value
+}
+
+function createPersistedPrompt(target: ReturnType<typeof promptTarget>, initial?: InitialPrompt) {
+  const [store, setStore, _, ready] = persisted(target, createStore<PromptStore>(promptStore(initial)))
+  return { ready, ...createPromptStateValue(store, setStore) }
+}
+
+export function createPromptSession(serverScope: ServerScope, scope: PromptScope, initial?: InitialPrompt) {
+  return createPersistedPrompt(promptTarget(serverScope, scope), initial)
+}
+
+export function createDraftPromptSession(draftID: string, initial?: InitialPrompt) {
+  return createPersistedPrompt(Persist.draft(draftID, "prompt"), initial)
+}
+
+export type PromptSession = ReturnType<typeof createPromptSession>
+
+export function createPromptReady(session: Accessor<PromptSession>) {
+  return Object.defineProperty(() => session().ready(), "promise", {
+    get: () => session().ready.promise,
+  }) as (() => boolean) & { readonly promise: Promise<unknown> | undefined }
+}
+
+export function createPromptState(initial?: InitialPrompt) {
+  const [store, setStore] = createStore<PromptStore>(promptStore(initial))
+  const ready = Object.assign(() => true, { promise: Promise.resolve(true) })
+  return {
+    ready,
+    ...createPromptStateValue(store, setStore),
+  }
+}

packages/app/src/context/prompt.tsx

@@ -1,186 +1,49 @@
+import { base64Encode } from "@opencode-ai/core/util/encode"
 import { createSimpleContext } from "@opencode-ai/ui/context"
-import { base64Encode, checksum } from "@opencode-ai/core/util/encode"
 import { useParams, useSearchParams } from "@solidjs/router"
-import { batch, createMemo, createRoot, getOwner, onCleanup, type Accessor } from "solid-js"
-import { createStore, type SetStoreFunction } from "solid-js/store"
-import type { FileSelection } from "@/context/file"
-import { Persist, persisted } from "@/utils/persist"
+import { createMemo, createRoot, getOwner, onCleanup } from "solid-js"
+import { requireServerKey } from "@/utils/session-route"
+import { ServerConnection } from "./server"
 import { useServerSDK } from "./server-sdk"
-import type { ServerScope } from "@/utils/server-scope"
+import { useSettings } from "./settings"
 import { useSDK } from "./sdk"
 import { useTabs, type Tab } from "./tabs"
-import { ServerConnection } from "./server"
-import { requireServerKey } from "@/utils/session-route"
-import { useSettings } from "./settings"
-import type { FilePartSource } from "@opencode-ai/sdk/v2/client"
+import {
+  createPromptReady,
+  createPromptSession,
+  type ContextItem,
+  type FileContextItem,
+  type Prompt,
+  type PromptModel,
+  type PromptScope,
+  type PromptSession,
+} from "./prompt-state"
 
-interface PartBase {
-  content: string
-  start: number
-  end: number
-}
-
-export interface TextPart extends PartBase {
-  type: "text"
-}
-
-export interface FileAttachmentPart extends PartBase {
-  type: "file"
-  path: string
-  selection?: FileSelection
-  mime?: string
-  filename?: string
-  url?: string
-  source?: FilePartSource
-}
-
-export interface AgentPart extends PartBase {
-  type: "agent"
-  name: string
-}
-
-export interface ImageAttachmentPart {
-  type: "image"
-  id: string
-  filename: string
-  sourcePath?: string
-  mime: string
-  dataUrl: string
-}
-
-export type ContentPart = TextPart | FileAttachmentPart | AgentPart | ImageAttachmentPart
-export type Prompt = ContentPart[]
-
-export type FileContextItem = {
-  type: "file"
-  path: string
-  selection?: FileSelection
-  comment?: string
-  commentID?: string
-  commentOrigin?: "review" | "file"
-  preview?: string
-}
-
-export type ContextItem = FileContextItem
-
-export const DEFAULT_PROMPT: Prompt = [{ type: "text", content: "", start: 0, end: 0 }]
-
-function isSelectionEqual(a?: FileSelection, b?: FileSelection) {
-  if (!a && !b) return true
-  if (!a || !b) return false
-  return (
-    a.startLine === b.startLine && a.startChar === b.startChar && a.endLine === b.endLine && a.endChar === b.endChar
-  )
-}
-
-function isPartEqual(partA: ContentPart, partB: ContentPart) {
-  switch (partA.type) {
-    case "text":
-      return partB.type === "text" && partA.content === partB.content
-    case "file":
-      return (
-        partB.type === "file" &&
-        partA.path === partB.path &&
-        partA.mime === partB.mime &&
-        partA.filename === partB.filename &&
-        isSelectionEqual(partA.selection, partB.selection)
-      )
-    case "agent":
-      return partB.type === "agent" && partA.name === partB.name
-    case "image":
-      return partB.type === "image" && partA.id === partB.id
-  }
-}
-
-export function isPromptEqual(promptA: Prompt, promptB: Prompt): boolean {
-  if (promptA.length !== promptB.length) return false
-  for (let i = 0; i < promptA.length; i++) {
-    if (!isPartEqual(promptA[i], promptB[i])) return false
-  }
-  return true
-}
-
-function cloneSelection(selection?: FileSelection) {
-  if (!selection) return undefined
-  return { ...selection }
-}
-
-function clonePart(part: ContentPart): ContentPart {
-  if (part.type === "text") return { ...part }
-  if (part.type === "image") return { ...part }
-  if (part.type === "agent") return { ...part }
-  return {
-    ...part,
-    selection: cloneSelection(part.selection),
-  }
-}
-
-function clonePrompt(prompt: Prompt): Prompt {
-  return prompt.map(clonePart)
-}
-
-function contextItemKey(item: ContextItem) {
-  if (item.type !== "file") return item.type
-  const start = item.selection?.startLine
-  const end = item.selection?.endLine
-  const key = `${item.type}:${item.path}:${start}:${end}`
-
-  if (item.commentID) {
-    return `${key}:c=${item.commentID}`
-  }
-
-  const comment = item.comment?.trim()
-  if (!comment) return key
-  const digest = checksum(comment) ?? comment
-  return `${key}:c=${digest.slice(0, 8)}`
-}
-
-function isCommentItem(item: ContextItem | (ContextItem & { key: string })) {
-  return item.type === "file" && !!item.comment?.trim()
-}
-
-function createPromptActions(
-  setStore: SetStoreFunction<{
-    prompt: Prompt
-    cursor?: number
-    context: {
-      items: (ContextItem & { key: string })[]
-    }
-  }>,
-) {
-  return {
-    set(prompt: Prompt, cursorPosition?: number) {
-      const next = clonePrompt(prompt)
-      batch(() => {
-        setStore("prompt", next)
-        if (cursorPosition !== undefined) setStore("cursor", cursorPosition)
-      })
-    },
-    reset() {
-      batch(() => {
-        setStore("prompt", clonePrompt(DEFAULT_PROMPT))
-        setStore("cursor", 0)
-      })
-    },
-  }
-}
+export {
+  createPromptReady,
+  createPromptSession,
+  createPromptState,
+  DEFAULT_PROMPT,
+  isPromptEqual,
+} from "./prompt-state"
+export type {
+  AgentPart,
+  ContentPart,
+  ContextItem,
+  FileAttachmentPart,
+  FileContextItem,
+  ImageAttachmentPart,
+  Prompt,
+  PromptModel,
+  PromptScope,
+  PromptSession,
+  TextPart,
+} from "./prompt-state"
 
 const WORKSPACE_KEY = "__workspace__"
 const MAX_PROMPT_SESSIONS = 20
 
-type PromptSession = ReturnType<typeof createPromptSession>
-
-type PromptStore = {
-  prompt: Prompt
-  cursor?: number
-  context: {
-    items: (ContextItem & { key: string })[]
-  }
-}
-
-type Scope = { draftID: string } | { dir: string; id?: string }
-
-export function selectPromptTab(tabs: Tab[], scope: Scope, server: ServerConnection.Key) {
+export function selectPromptTab(tabs: Tab[], scope: PromptScope, server: ServerConnection.Key) {
   if ("draftID" in scope) return tabs.find((tab) => tab.type === "draft" && tab.draftID === scope.draftID)
   if (!scope.id) return
   return (
@@ -189,7 +52,7 @@ export function selectPromptTab(tabs: Tab[], scope: Scope, server: ServerConnect
   )
 }
 
-function scopeKey(scope: Scope) {
+function scopeKey(scope: PromptScope) {
   if ("draftID" in scope) return `draft:${scope.draftID}`
   return `${scope.dir}:${scope.id ?? WORKSPACE_KEY}`
 }
@@ -199,91 +62,6 @@ type PromptCacheEntry = {
   dispose: VoidFunction
 }
 
-function promptTarget(serverScope: ServerScope, scope: Scope) {
-  if ("draftID" in scope) return Persist.draft(scope.draftID, "prompt")
-  const legacy = `${scope.dir}/prompt${scope.id ? "/" + scope.id : ""}.v2`
-  return Persist.serverScoped(serverScope, scope.dir, scope.id, "prompt", [legacy])
-}
-
-export function createPromptSession(serverScope: ServerScope, scope: Scope) {
-  const [store, setStore, _, ready] = persisted(
-    promptTarget(serverScope, scope),
-    createStore<PromptStore>(promptStore()),
-  )
-
-  return { ready, ...createPromptStateValue(store, setStore) }
-}
-
-export function createPromptReady(session: Accessor<PromptSession>) {
-  return Object.defineProperty(() => session().ready(), "promise", {
-    get: () => session().ready.promise,
-  }) as (() => boolean) & { readonly promise: Promise<unknown> | undefined }
-}
-
-function promptStore(): PromptStore {
-  return {
-    prompt: clonePrompt(DEFAULT_PROMPT),
-    cursor: undefined,
-    context: {
-      items: [],
-    },
-  }
-}
-
-function createPromptStateValue(store: PromptStore, setStore: SetStoreFunction<PromptStore>) {
-  const actions = createPromptActions(setStore)
-
-  const value = {
-    current: () => store.prompt,
-    cursor: createMemo(() => store.cursor),
-    dirty: () => !isPromptEqual(store.prompt, DEFAULT_PROMPT),
-    context: {
-      items: createMemo(() => store.context.items),
-      add(item: ContextItem) {
-        const key = contextItemKey(item)
-        if (store.context.items.find((x) => x.key === key)) return
-        setStore("context", "items", (items) => [...items, { key, ...item }])
-      },
-      remove(key: string) {
-        setStore("context", "items", (items) => items.filter((x) => x.key !== key))
-      },
-      removeComment(path: string, commentID: string) {
-        setStore("context", "items", (items) =>
-          items.filter((item) => !(item.type === "file" && item.path === path && item.commentID === commentID)),
-        )
-      },
-      updateComment(path: string, commentID: string, next: Partial<FileContextItem> & { comment?: string }) {
-        setStore("context", "items", (items) =>
-          items.map((item) => {
-            if (item.type !== "file" || item.path !== path || item.commentID !== commentID) return item
-            const value = { ...item, ...next }
-            return { ...value, key: contextItemKey(value) }
-          }),
-        )
-      },
-      replaceComments(items: FileContextItem[]) {
-        setStore("context", "items", (current) => [
-          ...current.filter((item) => !isCommentItem(item)),
-          ...items.map((item) => ({ ...item, key: contextItemKey(item) })),
-        ])
-      },
-    },
-    set: actions.set,
-    reset: actions.reset,
-    capture: () => value,
-  }
-  return value
-}
-
-export function createPromptState() {
-  const [store, setStore] = createStore<PromptStore>(promptStore())
-  const ready = Object.assign(() => true, { promise: Promise.resolve(true) })
-  return {
-    ready,
-    ...createPromptStateValue(store, setStore),
-  }
-}
-
 export const createTabPromptState = (
   tabs: ReturnType<typeof useTabs>,
   tab: Tab,
@@ -303,9 +81,7 @@ export const { use: usePrompt, provider: PromptProvider } = createSimpleContext(
     const cache = new Map<string, PromptCacheEntry>()
 
     const disposeAll = () => {
-      for (const entry of cache.values()) {
-        entry.dispose()
-      }
+      for (const entry of cache.values()) entry.dispose()
       cache.clear()
     }
 
@@ -324,13 +100,11 @@ export const { use: usePrompt, provider: PromptProvider } = createSimpleContext(
     const owner = getOwner()
     const serverKey = () =>
       params.serverKey ? requireServerKey(params.serverKey) : ServerConnection.key(serverSDK().server)
-    const scope = () =>
+    const scope = (): PromptScope =>
       search.draftId ? { draftID: search.draftId } : { dir: base64Encode(sdk().directory), id: params.id }
-    const load = (scope: Scope) => {
+    const load = (scope: PromptScope) => {
       const current = settings.general.newLayoutDesigns() ? selectPromptTab(tabs.store, scope, serverKey()) : undefined
-      if (current) {
-        return createTabPromptState(tabs, current, serverSDK().scope, scope)
-      }
+      if (current) return createTabPromptState(tabs, current, serverSDK().scope, scope)
 
       const key = scopeKey(scope)
       const existing = cache.get(key)
@@ -354,15 +128,19 @@ export const { use: usePrompt, provider: PromptProvider } = createSimpleContext(
     }
 
     const session = createMemo(() => load(scope()))
-    const pick = (scope?: Scope) => (scope ? load(scope) : session())
+    const pick = (scope?: PromptScope) => (scope ? load(scope) : session())
     const ready = createPromptReady(session)
 
     return {
       ready,
-      capture: (scope?: Scope) => pick(scope).capture(),
+      capture: (scope?: PromptScope) => pick(scope).capture(),
       current: () => session().current(),
       cursor: () => session().cursor(),
       dirty: () => session().dirty(),
+      model: {
+        current: () => session().model.current(),
+        set: (model: PromptModel | undefined) => session().model.set(model),
+      },
       context: {
         items: () => session().context.items(),
         add: (item: ContextItem) => session().context.add(item),
@@ -372,8 +150,8 @@ export const { use: usePrompt, provider: PromptProvider } = createSimpleContext(
           session().context.updateComment(path, commentID, next),
         replaceComments: (items: FileContextItem[]) => session().context.replaceComments(items),
       },
-      set: (prompt: Prompt, cursorPosition?: number, scope?: Scope) => pick(scope).set(prompt, cursorPosition),
-      reset: (scope?: Scope) => pick(scope).reset(),
+      set: (prompt: Prompt, cursorPosition?: number, scope?: PromptScope) => pick(scope).set(prompt, cursorPosition),
+      reset: (scope?: PromptScope) => pick(scope).reset(),
     }
   },
 })

packages/app/src/context/tab-memory.ts

@@ -16,6 +16,9 @@ export function createTabMemory(owner: Owner | null) {
   }
 
   return {
+    get<T>(key: string, name: string) {
+      return entries.get(key)?.get(name)?.value as T | undefined
+    },
     ensure<T>(key: string, name: string, init: () => T) {
       const state = entries.get(key) ?? new Map<string, Entry>()
       if (!entries.has(key)) entries.set(key, state)

packages/app/src/context/tabs.test.ts

@@ -22,6 +22,8 @@ describe("tab memory", () => {
       })
 
       expect(memory.ensure("tab", "prompt", () => ({ value: "other" }))).toBe(first)
+      expect(memory.get<typeof first>("tab", "prompt")).toBe(first)
+      expect(memory.get("missing", "prompt")).toBeUndefined()
       expect(memory.ensure("other", "prompt", () => ({ value: "other" }))).not.toBe(first)
 
       memory.remove("tab")

packages/app/src/context/tabs.tsx

@@ -11,6 +11,7 @@ import { SessionTabsRemovedDetail } from "@/components/titlebar-session-events"
 import { sessionHref } from "@/utils/session-route"
 import { createTabMemory } from "./tab-memory"
 import { nextTabAfterClose, pushClosedTab, removeClosedTabs, takeClosedTab, type ClosedTab } from "./closed-tabs"
+import { createDraftPromptSession, type PromptModel } from "./prompt-state"
 
 export type SessionTab = {
   type: "session"
@@ -207,15 +208,17 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
         if (!tab || tab.type !== "draft") throw new Error(`Draft not found: ${draftID}`)
         return tab
       },
-      newDraft(draft: Omit<DraftTab, "type" | "draftID">, prompt?: string) {
+      newDraft(draft: Omit<DraftTab, "type" | "draftID">, prompt?: string, model?: PromptModel) {
         const draftID = uuid()
+        const tab = { type: "draft" as const, draftID, ...draft }
+        memory.ensure(tabKey(tab), "prompt", () => createDraftPromptSession(draftID, { prompt, model }))
         void startTransition(() => {
           setStore(
             produce((tabs) => {
-              tabs.push({ type: "draft", draftID, ...draft })
+              tabs.push(tab)
             }),
           )
-          navigate(prompt ? `${draftHref(draftID)}&prompt=${encodeURIComponent(prompt)}` : draftHref(draftID))
+          navigate(draftHref(draftID))
         })
       },
       updateDraft(draftID: string, draft: Partial<Omit<DraftTab, "type" | "draftID">>) {
@@ -373,6 +376,9 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
       state<T>(tab: Tab, name: string, init: () => T) {
         return memory.ensure(tabKey(tab), name, init)
       },
+      stateValue<T>(tab: Tab, name: string) {
+        return memory.get<T>(tabKey(tab), name)
+      },
     }
 
     return { ...actions, store, info, ready, recentReady }

packages/app/src/i18n/en.ts

@@ -65,8 +65,8 @@ export const dict = {
   "command.message.next.description": "Go to the next user message",
   "command.model.choose": "Choose model",
   "command.model.choose.description": "Select a different model",
-  "command.mcp.toggle": "Toggle MCPs",
-  "command.mcp.toggle.description": "Toggle MCPs",
+  "command.mcp.toggle": "Manage MCP servers",
+  "command.mcp.toggle.description": "Enable or disable MCP servers",
   "command.agent.cycle": "Cycle agent",
   "command.agent.cycle.description": "Switch to the next agent",
   "command.agent.cycle.reverse": "Cycle agent backwards",
@@ -307,9 +307,9 @@ export const dict = {
   "prompt.toast.promptSendFailed.title": "Failed to send prompt",
   "prompt.toast.promptSendFailed.description": "Unable to retrieve session",
 
-  "dialog.mcp.title": "MCPs",
+  "dialog.mcp.title": "MCP servers",
   "dialog.mcp.description": "{{enabled}} of {{total}} enabled",
-  "dialog.mcp.empty": "No MCPs configured",
+  "dialog.mcp.empty": "No MCP servers configured",
 
   "dialog.lsp.empty": "LSPs auto-detected from file types",
   "dialog.plugins.empty": "Plugins configured in opencode.json",

packages/app/src/pages/new-session.tsx

@@ -26,10 +26,13 @@ import { useComposerCommands } from "@/pages/session/use-composer-commands"
 import { NEW_SESSION_CONTENT_WIDTH } from "@/pages/session/new-session-layout"
 import { PromptWorkspaceSelector } from "@/components/prompt-workspace-selector"
 import { useTitlebarRightMount } from "@/components/titlebar"
+import { useCommand } from "@/context/command"
 import { useProviders } from "@/hooks/use-providers"
 import { useSettingsDialog } from "@/components/settings-dialog"
 import { Persist, persisted } from "@/utils/persist"
 import createPresence from "solid-presence"
+import { useLocal } from "@/context/local"
+import { createPromptModelSelection } from "@/pages/session/composer/prompt-model-selection"
 
 const workspaceBarEnabled = import.meta.env.VITE_OPENCODE_CHANNEL !== "prod"
 const providerTipDismissalDuration = 30 * 24 * 60 * 60 * 1000
@@ -48,12 +51,15 @@ export default function NewSessionPage() {
   const comments = useComments()
   const language = useLanguage()
   const settings = useSettings()
+  const command = useCommand()
   const providers = useProviders(() => sdk().directory)
   const openProviderSettings = useSettingsDialog("providers")
   const route = useSessionKey()
   const [searchParams, setSearchParams] = useSearchParams<{ draftId?: string; prompt?: string }>()
+  const local = useLocal()
+  const model = createPromptModelSelection({ agent: local.agent.current })
 
-  useComposerCommands()
+  useComposerCommands({ model })
 
   let inputRef: HTMLDivElement | undefined
 
@@ -61,6 +67,7 @@ export default function NewSessionPage() {
     sessionKey: route.sessionKey,
     sessionID: () => route.params.id,
     queryOptions: serverSync().queryOptions,
+    model,
   })
   const projectControls = createPromptProjectControls()
   const projectController = createPromptProjectController({
@@ -68,6 +75,16 @@ export default function NewSessionPage() {
     onDone: () => inputRef?.focus(),
   })
 
+  command.register("new-session", () => [
+    {
+      id: "input.focus",
+      title: language.t("command.input.focus"),
+      category: language.t("command.category.view"),
+      keybind: "ctrl+l",
+      onSelect: () => inputRef?.focus(),
+    },
+  ])
+
   const [store, setStore] = createStore<{ worktree?: string }>({})
   const rightMount = useTitlebarRightMount()
 

packages/app/src/pages/session.tsx

@@ -69,7 +69,7 @@ import { MessageTimeline } from "@/pages/session/timeline/message-timeline"
 import { createTimelineModel } from "@/pages/session/timeline/model"
 import { type DiffStyle, SessionReviewTab, type SessionReviewTabProps } from "@/pages/session/review-tab"
 import { useSessionLayout } from "@/pages/session/session-layout"
-import { syncSessionModel } from "@/pages/session/session-model-helpers"
+import { restorePromptModel, syncPromptModel, syncSessionModel } from "@/pages/session/session-model-helpers"
 import {
   clampSessionPanelWidth,
   SESSION_PANEL_WIDTH_MIN,
@@ -483,7 +483,7 @@ export default function Page() {
     if (desktopSessionResizeOpen()) return `${sessionPanelResizedWidth()}px`
     return `calc(100% - ${layout.fileTree.width()}px)`
   })
-  const centered = createMemo(() => isDesktop() && !desktopReviewOpen())
+  const centered = createMemo(() => isDesktop() && (newSessionDesign() || !desktopReviewOpen()))
   const desktopV2PanelLayout = createMemo(() =>
     sessionPanelLayout({
       review: desktopV2ReviewOpen(),
@@ -557,6 +557,17 @@ export default function Page() {
     ),
   )
 
+  let restoredModelSession: string | undefined
+  createEffect(() => {
+    const id = params.id
+    if (!id || !prompt.ready() || !local.session.ready()) return
+    if (restoredModelSession !== id) {
+      restoredModelSession = id
+      if (restorePromptModel(local, prompt)) return
+    }
+    syncPromptModel(local, prompt)
+  })
+
   createEffect(
     on(
       () => ({ dir: sdk().directory, id: params.id }),
@@ -1267,7 +1278,7 @@ export default function Page() {
   const reviewPanelV2Rendered = createMemo<boolean>((prev) => prev || !store.deferRender, false)
 
   const reviewPanelV2 = () => (
-    <div class="flex flex-col h-full overflow-hidden bg-background-stronger contain-strict">
+    <div class="flex flex-col h-full overflow-hidden bg-v2-background-bg-base contain-strict">
       <Show when={reviewPanelV2Rendered()}>
         <ReviewPanelV2 {...reviewPanelV2Props()} />
       </Show>

packages/app/src/pages/session/composer/prompt-model-selection.ts

@@ -0,0 +1,133 @@
+import { batch, createMemo, startTransition } from "solid-js"
+import { useModels } from "@/context/models"
+import type { ModelKey, ModelSelection } from "@/context/local"
+import { cycleModelVariant, getConfiguredAgentVariant, resolveModelVariant } from "@/context/model-variant"
+import { usePrompt } from "@/context/prompt"
+import { useSDK } from "@/context/sdk"
+import { useSync } from "@/context/sync"
+import { useProviders } from "@/hooks/use-providers"
+
+export function createPromptModelSelection(input: { agent: () => { model?: ModelKey; variant?: string } | undefined }) {
+  const sdk = useSDK()
+  const sync = useSync()
+  const models = useModels()
+  const prompt = usePrompt()
+  const providers = useProviders(() => sdk().directory)
+  const connected = createMemo(() => new Set(providers.connected().map((item) => item.id)))
+
+  const valid = (model: ModelKey) => {
+    const provider = providers.all().get(model.providerID)
+    return !!provider?.models[model.modelID] && connected().has(model.providerID)
+  }
+
+  const configured = () => {
+    const value = sync().data.config.model
+    if (!value) return
+    const [providerID, modelID] = value.split("/")
+    const model = { providerID, modelID }
+    if (valid(model)) return model
+  }
+
+  const recent = () => models.recent.list().find(valid)
+  const fallback = () => {
+    const defaults = providers.default()
+    return providers.connected().flatMap((provider) => {
+      const modelID = defaults[provider.id] ?? Object.values(provider.models)[0]?.id
+      return modelID ? [{ providerID: provider.id, modelID }] : []
+    })[0]
+  }
+
+  const current = () => {
+    const key = [prompt.model.current(), input.agent()?.model, configured(), recent(), fallback()].find(
+      (item): item is ModelKey => !!item && valid(item),
+    )
+    if (!key) return
+    return models.find(key)
+  }
+  const recentModels = createMemo(() =>
+    models.recent
+      .list()
+      .map(models.find)
+      .filter((item): item is NonNullable<typeof item> => !!item),
+  )
+
+  const selection = {
+    ready: models.ready,
+    current,
+    recent: recentModels,
+    list: models.list,
+    cycle(direction: 1 | -1) {
+      const items = recentModels()
+      const item = current()
+      if (!item) return
+      const index = items.findIndex((entry) => entry.provider.id === item.provider.id && entry.id === item.id)
+      if (index === -1) return
+      const next = items[(index + direction + items.length) % items.length]
+      if (next) selection.set({ providerID: next.provider.id, modelID: next.id })
+    },
+    set(item: ModelKey | undefined, options?: { recent?: boolean }) {
+      startTransition(() =>
+        batch(() => {
+          prompt.model.set(item ? { ...item, variant: prompt.model.current()?.variant } : undefined)
+          if (!item) return
+          models.setVisibility(item, true)
+          if (options?.recent) models.recent.push(item)
+        }),
+      )
+    },
+    visible: models.visible,
+    setVisibility: models.setVisibility,
+    variant: {
+      configured() {
+        const item = input.agent()
+        const model = current()
+        if (!item || !model) return
+        return getConfiguredAgentVariant({
+          agent: { model: item.model, variant: item.variant },
+          model: { providerID: model.provider.id, modelID: model.id, variants: model.variants },
+        })
+      },
+      selected() {
+        return prompt.model.current()?.variant
+      },
+      current() {
+        const resolved = resolveModelVariant({
+          variants: this.list(),
+          selected: this.selected(),
+          configured: this.configured(),
+        })
+        if (resolved) return resolved
+        const model = current()
+        if (!model) return
+        const saved = models.variant.get({ providerID: model.provider.id, modelID: model.id })
+        if (saved && this.list().includes(saved)) return saved
+      },
+      list() {
+        return Object.keys(current()?.variants ?? {})
+      },
+      set(value: string | undefined) {
+        startTransition(() =>
+          batch(() => {
+            const model = current()
+            if (!model) return
+            prompt.model.set({ providerID: model.provider.id, modelID: model.id, variant: value ?? null })
+            models.variant.set({ providerID: model.provider.id, modelID: model.id }, value)
+          }),
+        )
+      },
+      cycle() {
+        const variants = this.list()
+        if (variants.length === 0) return
+        this.set(
+          cycleModelVariant({
+            variants,
+            selected: this.selected(),
+            configured: this.configured(),
+          }),
+        )
+      },
+    },
+  } satisfies ModelSelection
+
+  return selection
+}

packages/app/src/pages/session/composer/session-composer-controls.ts

@@ -7,7 +7,7 @@ import type { PromptProjectControls } from "@/components/prompt-project-selector
 import { useDirectoryPicker } from "@/components/directory-picker"
 import { useGlobal } from "@/context/global"
 import { useLayout } from "@/context/layout"
-import { useLocal } from "@/context/local"
+import { useLocal, type ModelSelection } from "@/context/local"
 import type { QueryOptionsApi } from "@/context/server-sync"
 import { useServerSDK } from "@/context/server-sdk"
 import { serverName, ServerConnection, useServer } from "@/context/server"
@@ -22,6 +22,7 @@ export function createPromptInputController(input: {
   sessionKey: Accessor<string>
   sessionID: Accessor<string | undefined>
   queryOptions: Pick<QueryOptionsApi, "agents" | "providers">
+  model?: ModelSelection
 }) {
   const layout = useLayout()
   const local = useLocal()
@@ -44,7 +45,7 @@ export function createPromptInputController(input: {
       select: local.agent.set,
     },
     model: {
-      selection: local.model,
+      selection: input.model ?? local.model,
       paid: providers.paid().length > 0,
       loading: agentsQuery.isLoading || providersQuery.isLoading || globalProvidersQuery.isLoading,
     },

packages/app/src/pages/session/session-model-helpers.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import type { UserMessage } from "@opencode-ai/sdk/v2"
-import { resetSessionModel, syncSessionModel } from "./session-model-helpers"
+import { resetSessionModel, restorePromptModel, syncPromptModel, syncSessionModel } from "./session-model-helpers"
 
 const message = (input?: { agent?: string; model?: UserMessage["model"] }) =>
   ({
@@ -50,3 +50,102 @@ describe("resetSessionModel", () => {
     expect(calls).toEqual(["reset"])
   })
 })
+
+describe("syncPromptModel", () => {
+  test("stores the effective session model in prompt state", () => {
+    const calls: unknown[] = []
+
+    syncPromptModel(
+      {
+        model: {
+          current: () => ({ id: "claude-sonnet-4", provider: { id: "anthropic" } }),
+          set() {},
+          variant: { current: () => "high", set() {} },
+        },
+      },
+      {
+        model: {
+          current: () => undefined,
+          set: (model) => calls.push(model),
+        },
+      },
+    )
+
+    expect(calls).toEqual([{ providerID: "anthropic", modelID: "claude-sonnet-4", variant: "high" }])
+  })
+
+  test("does not rewrite an unchanged prompt model", () => {
+    const calls: unknown[] = []
+    const model = { providerID: "anthropic", modelID: "claude-sonnet-4", variant: "high" }
+
+    syncPromptModel(
+      {
+        model: {
+          current: () => ({ id: model.modelID, provider: { id: model.providerID } }),
+          set() {},
+          variant: { current: () => model.variant, set() {} },
+        },
+      },
+      {
+        model: {
+          current: () => model,
+          set: (value) => calls.push(value),
+        },
+      },
+    )
+
+    expect(calls).toEqual([])
+  })
+})
+
+describe("restorePromptModel", () => {
+  test("restores the persisted prompt model into session selection", () => {
+    const calls: unknown[] = []
+    const restored = restorePromptModel(
+      {
+        model: {
+          current: () => ({ id: "gpt", provider: { id: "openai" } }),
+          set: (model) => calls.push(model),
+          variant: {
+            current: () => undefined,
+            set: (variant) => calls.push(variant),
+          },
+        },
+      },
+      {
+        model: {
+          current: () => ({ providerID: "anthropic", modelID: "claude", variant: "high" }),
+          set() {},
+        },
+      },
+    )
+
+    expect(restored).toBe(true)
+    expect(calls).toEqual([{ providerID: "anthropic", modelID: "claude" }, "high"])
+  })
+
+  test("does nothing without a persisted prompt model", () => {
+    const calls: unknown[] = []
+    const restored = restorePromptModel(
+      {
+        model: {
+          current: () => ({ id: "gpt", provider: { id: "openai" } }),
+          set: (model) => calls.push(model),
+          variant: {
+            current: () => undefined,
+            set: (variant) => calls.push(variant),
+          },
+        },
+      },
+      {
+        model: {
+          current: () => undefined,
+          set() {},
+        },
+      },
+    )
+
+    expect(restored).toBe(false)
+    expect(calls).toEqual([])
+  })
+})

packages/app/src/pages/session/session-model-helpers.ts

@@ -7,6 +7,24 @@ type Local = {
   }
 }
 
+type ModelSelection = {
+  model: {
+    current(): { id: string; provider: { id: string } } | undefined
+    set(model: { providerID: string; modelID: string }): void
+    variant: {
+      current(): string | undefined
+      set(variant: string | undefined): void
+    }
+  }
+}
+
+type PromptState = {
+  model: {
+    current(): { providerID: string; modelID: string; variant?: string | null } | undefined
+    set(model: { providerID: string; modelID: string; variant?: string | null }): void
+  }
+}
+
 export const resetSessionModel = (local: Local) => {
   local.session.reset()
 }
@@ -14,3 +32,32 @@ export const resetSessionModel = (local: Local) => {
 export const syncSessionModel = (local: Local, msg: UserMessage) => {
   local.session.restore(msg)
 }
+
+export const syncPromptModel = (local: ModelSelection, prompt: PromptState) => {
+  const model = local.model.current()
+  if (!model) return
+  const next = {
+    providerID: model.provider.id,
+    modelID: model.id,
+    variant: local.model.variant.current(),
+  }
+  const current = prompt.model.current()
+  if (current?.providerID === next.providerID && current.modelID === next.modelID && current.variant === next.variant)
+    return
+  prompt.model.set(next)
+}
+
+export const restorePromptModel = (local: ModelSelection, prompt: PromptState) => {
+  const model = prompt.model.current()
+  if (!model) return false
+  const current = local.model.current()
+  if (
+    current?.provider.id === model.providerID &&
+    current.id === model.modelID &&
+    local.model.variant.current() === (model.variant ?? undefined)
+  )
+    return true
+  local.model.set({ providerID: model.providerID, modelID: model.modelID })
+  local.model.variant.set(model.variant ?? undefined)
+  return true
+}

packages/app/src/pages/session/session-side-panel.tsx

@@ -249,8 +249,10 @@ export function SessionSidePanel(props: {
         aria-label={language.t("session.panel.reviewAndFiles")}
         aria-hidden={!open()}
         inert={!open()}
-        class="relative min-w-0 flex overflow-hidden bg-background-base"
+        class="relative min-w-0 flex overflow-hidden"
         classList={{
+          "bg-v2-background-bg-base": settings.general.newLayoutDesigns(),
+          "bg-background-base": !settings.general.newLayoutDesigns(),
           "h-full shrink-0": !props.stacked,
           "h-full min-h-0": props.stacked,
           "pointer-events-none": !open(),
@@ -269,8 +271,20 @@ export function SessionSidePanel(props: {
             }}
           >
             <Show when={reviewOpen()}>
-              <div class="relative min-w-0 h-full flex-1 overflow-hidden bg-background-base">
-                <div class="size-full min-w-0 h-full bg-background-base">
+              <div
+                class="relative min-w-0 h-full flex-1 overflow-hidden"
+                classList={{
+                  "bg-v2-background-bg-base": settings.general.newLayoutDesigns(),
+                  "bg-background-base": !settings.general.newLayoutDesigns(),
+                }}
+              >
+                <div
+                  class="size-full min-w-0 h-full"
+                  classList={{
+                    "bg-v2-background-bg-base": settings.general.newLayoutDesigns(),
+                    "bg-background-base": !settings.general.newLayoutDesigns(),
+                  }}
+                >
                   <DragDropProvider
                     onDragStart={handleDragStart}
                     onDragEnd={handleDragEnd}
@@ -373,7 +387,13 @@ export function SessionSidePanel(props: {
                               )}
                             </For>
                           </SortableProvider>
-                          <div class="bg-background-stronger h-full shrink-0 sticky right-0 z-10 flex items-center justify-center pr-3">
+                          <div
+                            class="h-full shrink-0 sticky right-0 z-10 flex items-center justify-center pr-3"
+                            classList={{
+                              "bg-v2-background-bg-base": settings.general.newLayoutDesigns(),
+                              "bg-background-stronger": !settings.general.newLayoutDesigns(),
+                            }}
+                          >
                             <TooltipKeybind
                               title={language.t("command.file.open")}
                               keybind={command.keybind("file.open")}

packages/app/src/pages/session/terminal-panel-v2.tsx

@@ -195,7 +195,7 @@ export function TerminalPanelV2(props: { stacked?: boolean } = {}) {
       aria-label={language.t("terminal.title")}
       aria-hidden={!opened()}
       inert={!opened()}
-      class="relative shrink-0 overflow-hidden bg-background-stronger"
+      class="relative shrink-0 overflow-hidden bg-v2-background-bg-base"
       classList={{
         "w-full": !isDesktop() || stacked(),
         "min-w-0 h-full flex-1": isDesktop() && opened() && !stacked(),
@@ -237,7 +237,7 @@ export function TerminalPanelV2(props: { stacked?: boolean } = {}) {
           when={terminal.ready()}
           fallback={
             <div class="flex flex-col h-full pointer-events-none">
-              <div class="h-10 flex items-center gap-2 px-2 border-b border-border-weaker-base bg-background-stronger overflow-hidden">
+              <div class="h-10 flex items-center gap-2 px-2 border-b border-border-weaker-base bg-v2-background-bg-base overflow-hidden">
                 <For each={handoff()}>
                   {(title) => (
                     <div class="px-2 py-1 rounded-md bg-surface-base text-14-regular text-text-weak truncate max-w-40">

packages/app/src/pages/session/timeline/message-timeline.tsx

@@ -1243,12 +1243,13 @@ export function MessageTimeline(props: {
     const initialRow = timelineRowByKey().get(props.rowKey)!
     const item = createMemo(() => virtualItemByKey().get(props.rowKey) ?? initialItem)
     const row = createMemo(() => timelineRowByKey().get(props.rowKey) ?? initialRow)
-    const asyncFile = () => {
+    const tool = () => {
       const value = row()
-      if (value._tag !== "AssistantPart" || value.group.type !== "part") return false
+      if (value._tag !== "AssistantPart" || value.group.type !== "part") return
       const part = getMsgPart(value.group.ref.messageID, value.group.ref.partID)
-      return part?.type === "tool" && ["edit", "write", "patch", "apply_patch"].includes(part.tool)
+      if (part?.type === "tool") return part
     }
+    const asyncFile = () => ["edit", "write", "patch", "apply_patch"].includes(tool()?.tool ?? "")
     const [ready, setReady] = createSignal(initialItem.size <= timelineFallbackItemSize || !asyncFile())
     let contentMeasureFrame: number | undefined
 
@@ -1278,6 +1279,8 @@ export function MessageTimeline(props: {
           width: "100%",
           height: `${item().size}px`,
           overflow: "clip",
+          // Rounded virtual measurements can otherwise clip a framed row's outer paint.
+          "overflow-clip-margin": row()._tag === "TurnGap" ? undefined : "0.5px",
         }}
       >
         <div
@@ -1383,7 +1386,7 @@ export function MessageTimeline(props: {
               "w-full": true,
               "pb-4": true,
               "pr-3": true,
-              "pl-2": settings.general.newLayoutDesigns(),
+              "pl-2.5": settings.general.newLayoutDesigns(),
               "pl-2 md:pl-4": !settings.general.newLayoutDesigns(),
               "md:max-w-200 md:mx-auto 2xl:max-w-[1000px]": props.centered && !settings.general.newLayoutDesigns(),
             }}

packages/app/src/pages/session/use-composer-commands.tsx

@@ -1,6 +1,6 @@
 import { useCommand, type CommandOption } from "@/context/command"
 import { useLanguage } from "@/context/language"
-import { useLocal } from "@/context/local"
+import { useLocal, type ModelSelection } from "@/context/local"
 import { useSettings } from "@/context/settings"
 import { useDialog } from "@opencode-ai/ui/context/dialog"
 import { getCursorPosition, setCursorPosition } from "@/components/prompt-input/editor-dom"
@@ -14,7 +14,7 @@ const withCategory = (category: string) => {
   })
 }
 
-export const useComposerCommands = () => {
+export const useComposerCommands = (input: { model?: ModelSelection } = {}) => {
   const command = useCommand()
   const dialog = useDialog()
   const language = useLanguage()
@@ -22,6 +22,7 @@ export const useComposerCommands = () => {
   const settings = useSettings()
   const { sessionKey } = useSessionLayout()
   const sessionOwnership = createSessionOwnership(sessionKey)
+  const model = input.model ?? local.model
   const modelCommand = withCategory(language.t("command.category.model"))
   const agentCommand = withCategory(language.t("command.category.agent"))
 
@@ -43,7 +44,7 @@ export const useComposerCommands = () => {
     }
     const { DialogSelectModel } = await import("@/components/dialog-select-model")
     owner.run(() => {
-      void dialog.show(() => <DialogSelectModel model={local.model} />, restoreComposer)
+      void dialog.show(() => <DialogSelectModel model={model} />, restoreComposer)
     })
   }
 
@@ -61,7 +62,7 @@ export const useComposerCommands = () => {
       title: language.t("command.model.variant.cycle"),
       description: language.t("command.model.variant.cycle.description"),
       keybind: "shift+mod+d",
-      onSelect: () => local.model.variant.cycle(),
+      onSelect: () => model.variant.cycle(),
     }),
     agentCommand({
       id: "agent.cycle",

packages/app/src/pages/session/v2/session-file-browser-tab.tsx

@@ -46,6 +46,7 @@ export function SessionFileBrowserTab(props: {
   const resultsID = `session-file-browser-results-${createUniqueId()}`
   const [filter, setFilter] = createSignal("")
   const [explicitHighlight, setExplicitHighlight] = createSignal<string>()
+  const sidebarOpened = () => props.placeholder || props.state.sidebarOpened()
   const query = createMemo(() => filter().trim())
   const search = createQuery(() => {
     const value = query()
@@ -98,15 +99,15 @@ export function SessionFileBrowserTab(props: {
         toolbar
         toolbarStart={
           <>
-            <SessionReviewV2SidebarToggle opened={props.state.sidebarOpened()} onToggle={props.state.toggleSidebar} />
-            <Show when={!props.state.sidebarOpened()}>
+            <SessionReviewV2SidebarToggle opened={sidebarOpened()} onToggle={props.state.toggleSidebar} />
+            <Show when={!sidebarOpened()}>
               <SessionFilePanelV2Title>{title()}</SessionFilePanelV2Title>
             </Show>
           </>
         }
         sidebar={
           <SessionReviewV2Sidebar
-            open={props.state.sidebarOpened()}
+            open={sidebarOpened()}
             title={<span class="truncate">{title()}</span>}
             filter={filter()}
             onFilterChange={setFilter}

packages/app/src/utils/persist.ts

@@ -463,7 +463,7 @@ function localStorageDirect(): SyncStorage {
   }
 }
 
-const DRAFT_PERSISTED_KEYS = ["prompt", "comments", "model-selection", "file-view", "layout"]
+const DRAFT_PERSISTED_KEYS = ["prompt", "comments", "file-view", "layout"]
 
 export function draftPersistedKeys() {
   return DRAFT_PERSISTED_KEYS

packages/cli/bunfig.toml

@@ -1 +1,4 @@
 preload = ["@opentui/solid/preload"]
+
+[test]
+preload = ["@opentui/solid/preload"]

packages/cli/package.json

@@ -45,6 +45,7 @@
     "@parcel/watcher": "2.5.1",
     "effect": "catalog:",
     "fuzzysort": "catalog:",
+    "immer": "11.1.4",
     "jsonc-parser": "3.3.1",
     "open": "10.1.2",
     "opentui-spinner": "catalog:",

packages/cli/src/commands/handlers/default.ts

@@ -2,12 +2,13 @@ import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { Global } from "@opencode-ai/core/global"
 import { run } from "@opencode-ai/tui"
 import { loadBuiltinPlugins } from "@opencode-ai/tui/builtins"
-import { TuiConfig } from "@opencode-ai/tui/config"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
+import { Config } from "../../config"
 import { Effect, Option } from "effect"
 import { Server } from "../../services/server"
 import { Updater } from "../../services/updater"
+import { UpdatePreflight } from "../../services/update-preflight"
 
 export default Runtime.handler(Commands, (input) =>
   Effect.gen(function* () {
@@ -15,17 +16,38 @@ export default Runtime.handler(Commands, (input) =>
     if (requestedDirectory !== undefined) process.chdir(requestedDirectory)
     const updater = yield* Updater.Service
     yield* updater.check().pipe(Effect.forkScoped)
+    const preflight = UpdatePreflight.make()
+    yield* Effect.addFinalizer(() => Effect.promise(() => preflight.close()))
     const server = yield* Server.resolve({
       server: Option.getOrUndefined(input.server),
       standalone: input.standalone,
-    })
-    const config = TuiConfig.resolve({}, { terminalSuspend: false })
+      onStart: (reason, existing) => {
+        if (reason === "version-mismatch" && preflight.begin(existing?.version)) return
+        process.stderr.write(
+          reason === "version-mismatch"
+            ? "Restarting background server (version mismatch)...\n"
+            : "Starting background server...\n",
+        )
+      },
+    }).pipe(
+      Effect.tapError(() =>
+        Effect.promise(() => preflight.fail("OpenCode update could not start the new background service")),
+      ),
+    )
+    preflight.loading()
+    const config = yield* Config.Service
     let disposeSlots: (() => void) | undefined
-    const runFork = Effect.runForkWith(yield* Effect.context())
+    const context = yield* Effect.context()
+    const runFork = Effect.runForkWith(context)
+    const runPromise = Effect.runPromiseWith(context)
     yield* run({
       server,
       args: { continue: input.continue, sessionID: Option.getOrUndefined(input.session) },
-      config,
+      config: {
+        get: () => runPromise(config.get()),
+        update: (update) => runPromise(config.update(update)),
+      },
+      terminalHandoff: () => preflight.finish(),
       log: (level, message, tags) => {
         const effect =
           level === "debug"

packages/cli/src/config/config.ts

@@ -0,0 +1,109 @@
+export * as Config from "./config"
+
+import { Global } from "@opencode-ai/core/global"
+import { Context, Effect, FileSystem, Layer, Option, Schema, Semaphore } from "effect"
+import { produce, type Draft } from "immer"
+import { applyEdits, modify, parse, type ParseError } from "jsonc-parser"
+import path from "path"
+import { ConfigMigration } from "./migrate"
+import { Info } from "./schema"
+
+export * from "./schema"
+
+export interface Interface {
+  readonly path: string
+  readonly get: () => Effect.Effect<Info>
+  readonly update: (update: (draft: Draft<Info>) => void) => Effect.Effect<Info, Error>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/cli/config/Config") {}
+
+const decode = Schema.decodeUnknownOption(Info)
+const decodeRecord = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Any))
+const empty: Info = {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const global = yield* Global.Service
+    const file = path.join(global.config, "cli.json")
+    const lock = yield* Semaphore.make(1)
+
+    const readJson = Effect.fnUntraced(function* () {
+      const text = yield* fs.readFileString(file).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      if (text === undefined) return undefined
+      const errors: ParseError[] = []
+      const value: any = parse(text, errors, { allowTrailingComma: true })
+      if (errors.length) return undefined
+      return Option.getOrUndefined(decodeRecord(value))
+    })
+
+    const write = Effect.fnUntraced(function* (text: string) {
+      const temp = file + ".tmp"
+      yield* fs.makeDirectory(path.dirname(file), { recursive: true })
+      yield* fs.writeFileString(temp, text, { mode: 0o600 })
+      yield* fs.rename(temp, file)
+    })
+
+    const migrate = ConfigMigration.run({ file, config: global.config, state: global.state }).pipe(
+      Effect.provideService(FileSystem.FileSystem, fs),
+    )
+
+    const get = Effect.fn("cli.config.get")(function* () {
+      yield* migrate.pipe(Effect.catchCause((cause) => Effect.logWarning("failed to migrate cli config", { cause })))
+      return Option.getOrElse(decode(yield* readJson()), () => empty)
+    })
+
+    const update = Effect.fn("cli.config.update")((update: (draft: Draft<Info>) => void) =>
+      lock
+        .withPermits(1)(
+          Effect.gen(function* () {
+            yield* migrate
+            const current = Option.getOrElse(decode(yield* readJson()), () => empty)
+            const next = produce(current, update)
+            const edits = changes(current, next)
+            if (!edits.length) return current
+            const text = yield* fs.readFileString(file).pipe(Effect.catch(() => Effect.succeed("{}")))
+            const updated = edits.reduce(
+              (text, edit) =>
+                applyEdits(
+                  text,
+                  modify(text, edit.path, edit.value, { formattingOptions: { tabSize: 2, insertSpaces: true } }),
+                ),
+              text,
+            )
+            const errors: ParseError[] = []
+            const config = Option.getOrUndefined(decode(parse(updated, errors, { allowTrailingComma: true })))
+            if (errors.length || config === undefined) return yield* Effect.fail(new Error("Invalid CLI config update"))
+            yield* write(updated.endsWith("\n") ? updated : updated + "\n")
+            return config
+          }),
+        )
+        .pipe(Effect.mapError((cause) => new Error("Failed to update CLI config", { cause }))),
+    )
+
+    return Service.of({ path: file, get, update })
+  }),
+)
+
+type Edit = { readonly path: (string | number)[]; readonly value: any }
+
+function changes(before: any, after: any, path: (string | number)[] = []): Edit[] {
+  if (Object.is(before, after)) return []
+  if (
+    before !== null &&
+    after !== null &&
+    typeof before === "object" &&
+    typeof after === "object" &&
+    !Array.isArray(before) &&
+    !Array.isArray(after)
+  ) {
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap((key) => {
+      if (!(key in after)) return [{ path: [...path, key], value: undefined }]
+      if (!(key in before)) return [{ path: [...path, key], value: after[key] }]
+      return changes(before[key], after[key], [...path, key])
+    })
+  }
+  return [{ path, value: after }]
+}

packages/cli/src/config/index.ts

@@ -0,0 +1 @@
+export * as Config from "./config"

packages/cli/src/config/migrate.ts

@@ -0,0 +1,142 @@
+export * as ConfigMigration from "./migrate"
+
+import { TuiConfigV1 } from "@opencode-ai/tui/config/v1"
+import { Effect, FileSystem, Option, Schema } from "effect"
+import { parse, type ParseError } from "jsonc-parser"
+import path from "path"
+import type { Info } from "./schema"
+
+const decodeV1 = Schema.decodeUnknownOption(TuiConfigV1.Info)
+const decodeRecord = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Any))
+
+export const run = Effect.fn("cli.config.migrate")(function* (input: {
+  readonly file: string
+  readonly config: string
+  readonly state: string
+}) {
+  const fs = yield* FileSystem.FileSystem
+  if (yield* fs.exists(input.file).pipe(Effect.orElseSucceed(() => false))) return
+
+  const legacyValue = yield* readJson(path.join(input.config, "tui.json"))
+  const legacy = Option.getOrUndefined(decodeV1(legacyValue))
+  const kv = yield* readJson(path.join(input.state, "kv.json"))
+  const migrated = migrateV1(legacy, kv ?? {})
+  if (!Object.keys(migrated).length) return
+
+  const temp = input.file + ".tmp"
+  yield* fs.makeDirectory(path.dirname(input.file), { recursive: true })
+  yield* fs.writeFileString(temp, JSON.stringify(migrated, null, 2) + "\n", { mode: 0o600 })
+  yield* fs.rename(temp, input.file)
+  yield* Effect.logInfo("migrated cli config", {
+    from: [
+      legacyValue === undefined ? undefined : path.join(input.config, "tui.json"),
+      kv === undefined ? undefined : path.join(input.state, "kv.json"),
+    ].filter(Boolean),
+    to: input.file,
+  })
+})
+
+export function migrateV1(legacy: TuiConfigV1.Info | undefined, kv: Record<string, any>): Info {
+  const plugins = [
+    ...(legacy?.plugin?.map((plugin) =>
+      typeof plugin === "string" ? plugin : { package: plugin[0], options: plugin[1] },
+    ) ?? []),
+    ...Object.entries(legacy?.plugin_enabled ?? {}).map(([id, enabled]) => (enabled ? id : `-${id}`)),
+  ]
+  const themeName = legacy?.theme ?? kv.theme
+  const themeMode = kv.theme_mode_lock
+  const attentionSoundPack = kv.attention_sound_pack
+  const diffView = kv.diff_viewer_view ?? (legacy?.diff_style === "stacked" ? "unified" : undefined)
+  const thinking =
+    kv.thinking_mode ??
+    (kv.thinking_visibility === undefined ? undefined : kv.thinking_visibility ? "show" : "hide")
+
+  return {
+    ...(themeName !== undefined || themeMode !== undefined
+      ? { theme: { ...(themeName === undefined ? {} : { name: themeName }), ...(themeMode === undefined ? {} : { mode: themeMode }) } }
+      : {}),
+    ...(legacy?.keybinds === undefined ? {} : { keybinds: legacy.keybinds }),
+    ...(plugins.length ? { plugins } : {}),
+    ...(legacy?.leader_timeout === undefined ? {} : { leader: { timeout: legacy.leader_timeout } }),
+    ...(legacy?.scroll_speed === undefined && legacy?.scroll_acceleration?.enabled === undefined
+      ? {}
+      : {
+          scroll: {
+            ...(legacy.scroll_speed === undefined ? {} : { speed: legacy.scroll_speed }),
+            ...(legacy.scroll_acceleration?.enabled === undefined
+              ? {}
+              : { acceleration: legacy.scroll_acceleration.enabled }),
+          },
+        }),
+    ...(legacy?.attention === undefined && attentionSoundPack === undefined
+      ? {}
+      : {
+          attention: {
+            ...legacy?.attention,
+            ...(attentionSoundPack === undefined ? {} : { sound_pack: attentionSoundPack }),
+          },
+        }),
+    ...(legacy?.diff_style === undefined &&
+    kv.diff_wrap_mode === undefined &&
+    kv.diff_viewer_show_file_tree === undefined &&
+    kv.diff_viewer_single_patch === undefined &&
+    diffView === undefined
+      ? {}
+      : {
+          diffs: {
+            ...(kv.diff_wrap_mode === undefined ? {} : { wrap: kv.diff_wrap_mode }),
+            ...(kv.diff_viewer_show_file_tree === undefined ? {} : { tree: kv.diff_viewer_show_file_tree }),
+            ...(kv.diff_viewer_single_patch === undefined ? {} : { single: kv.diff_viewer_single_patch }),
+            ...(diffView === undefined ? {} : { view: diffView }),
+          },
+        }),
+    ...(kv.terminal_title_enabled === undefined ? {} : { terminal: { title: kv.terminal_title_enabled } }),
+    ...(kv.file_context_enabled === undefined && kv.paste_summary_enabled === undefined
+      ? {}
+      : {
+          prompt: {
+            ...(kv.file_context_enabled === undefined ? {} : { editor: kv.file_context_enabled }),
+            ...(kv.paste_summary_enabled === undefined
+              ? {}
+              : { paste: kv.paste_summary_enabled ? ("compact" as const) : ("full" as const) }),
+          },
+        }),
+    ...(kv.sidebar === undefined &&
+    kv.scrollbar_visible === undefined &&
+    thinking === undefined &&
+    kv.exploration_grouping === undefined
+      ? {}
+      : {
+          session: {
+            ...(kv.sidebar === undefined ? {} : { sidebar: kv.sidebar }),
+            ...(kv.scrollbar_visible === undefined ? {} : { scrollbar: kv.scrollbar_visible }),
+            ...(thinking === undefined ? {} : { thinking }),
+            ...(kv.exploration_grouping === undefined
+              ? {}
+              : { grouping: kv.exploration_grouping ? ("auto" as const) : ("none" as const) }),
+          },
+        }),
+    ...(kv.tips_hidden === undefined && kv.dismissed_getting_started === undefined
+      ? {}
+      : {
+          hints: {
+            ...(kv.tips_hidden === undefined ? {} : { tips: !kv.tips_hidden }),
+            ...(kv.dismissed_getting_started === undefined
+              ? {}
+              : { onboarding: !kv.dismissed_getting_started }),
+          },
+        }),
+    ...(kv.animations_enabled === undefined ? {} : { animations: kv.animations_enabled }),
+    ...(legacy?.mouse === undefined ? {} : { mouse: legacy.mouse }),
+  }
+}
+
+const readJson = Effect.fnUntraced(function* (target: string) {
+  const fs = yield* FileSystem.FileSystem
+  const text = yield* fs.readFileString(target).pipe(Effect.catch(() => Effect.succeed(undefined)))
+  if (text === undefined) return undefined
+  const errors: ParseError[] = []
+  const value: any = parse(text, errors, { allowTrailingComma: true })
+  if (errors.length) return undefined
+  return Option.getOrUndefined(decodeRecord(value))
+})

packages/cli/src/config/schema.ts

@@ -0,0 +1,5 @@
+import { Config } from "@opencode-ai/tui/config"
+import { Schema } from "effect"
+
+export const Info = Schema.Struct({ ...Config.Info.fields })
+export type Info = Schema.Schema.Type<typeof Info>

packages/cli/src/framework/runtime.ts

@@ -3,6 +3,7 @@ import { Command } from "effect/unstable/cli"
 import { Spec } from "./spec"
 import { Global } from "@opencode-ai/core/global"
 import { Updater } from "../services/updater"
+import { Config } from "../config"
 
 export type Input<Value> =
   Value extends Spec.Node<infer _Name, infer Command, infer _Commands>
@@ -13,18 +14,26 @@ export type Input<Value> =
 
 type RuntimeHandler = (
   input: unknown,
-) => Effect.Effect<void, unknown, FileSystem.FileSystem | Global.Service | Updater.Service | Scope.Scope>
+) => Effect.Effect<
+  void,
+  unknown,
+  FileSystem.FileSystem | Global.Service | Updater.Service | Config.Service | Scope.Scope
+>
 type Loader<Node extends Spec.Any> = () => Promise<{
   default: (
     input: Input<Node>,
-  ) => Effect.Effect<void, any, FileSystem.FileSystem | Global.Service | Updater.Service | Scope.Scope>
+  ) => Effect.Effect<
+    void,
+    any,
+    FileSystem.FileSystem | Global.Service | Updater.Service | Config.Service | Scope.Scope
+  >
 }>
 type ProvidedCommand = Command.Command<
   string,
   unknown,
   unknown,
   unknown,
-  FileSystem.FileSystem | Global.Service | Updater.Service | Scope.Scope
+  FileSystem.FileSystem | Global.Service | Updater.Service | Config.Service | Scope.Scope
 >
 
 export type Handlers<Node extends Spec.Any> = keyof Node["commands"] extends never

packages/cli/src/index.ts

@@ -11,6 +11,7 @@ import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Global } from "@opencode-ai/core/global"
 import { AppProcess } from "@opencode-ai/core/process"
+import { Config } from "./config"
 
 const Handlers = Runtime.handlers(Commands, {
   $: () => import("./commands/handlers/default"),
@@ -51,6 +52,7 @@ Effect.logInfo("cli starting", {
 }).pipe(
   Effect.flatMap(() => Runtime.run(Commands, Handlers, { version: InstallationVersion })),
   Effect.annotateLogs({ role: "cli" }),
+  Effect.provide(Config.layer),
   Effect.provide(Updater.layer),
   Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node]))),
   Effect.provide(Observability.layer),

packages/cli/src/mini/footer.prompt.tsx

@@ -778,19 +778,26 @@ export function createPromptState(input: PromptInput): PromptState {
     if (!area || area.isDestroyed) return false
 
     const endOffset = Bun.stringWidth(area.plainText)
-    if (dir === -1 && area.visualCursor.visualRow === 0) {
-      area.cursorOffset = 0
+    if (dir === -1) {
+      if (area.cursorOffset === 0) return false
+      if (area.visualCursor.visualRow === 0) {
+        area.cursorOffset = 0
+        return
+      }
+      area.moveCursorUp()
+      return
     }
 
     const end =
       typeof area.height === "number" && Number.isFinite(area.height) && area.height > 0
         ? area.height - 1
         : Math.max(0, (area.virtualLineCount ?? 1) - 1)
-    if (dir === 1 && area.visualCursor.visualRow === end) {
+    if (area.cursorOffset === endOffset) return false
+    if (area.visualCursor.visualRow === end) {
       area.cursorOffset = endOffset
+      return
     }
-
-    return false
+    area.moveCursorDown()
   }
 
   const requestExit = () => {
@@ -1037,6 +1044,7 @@ export function createPromptState(input: PromptInput): PromptState {
   }))
 
   useBindings(() => ({
+    priority: 1,
     mode: OPENCODE_BASE_MODE,
     enabled: input.prompt() && !visible(),
     commands: [

packages/cli/src/mini/footer.ts

@@ -627,7 +627,6 @@ export class RunFooter implements FooterApi {
 
     this.themes.splice(index, 1)
     theme.block.syntax?.destroy()
-    theme.block.subtleSyntax?.destroy()
   }
 
   public close(): void {
@@ -1023,7 +1022,6 @@ export class RunFooter implements FooterApi {
     void resolveRunTheme(this.renderer).then((theme) => {
       if (this.isGone) {
         theme.block.syntax?.destroy()
-        theme.block.subtleSyntax?.destroy()
         return
       }
 

packages/cli/src/mini/runtime.boot.ts

@@ -6,7 +6,7 @@
 // history ring. All are async because they read config or hit the SDK, but
 // none block each other.
 import { Context, Effect, Layer } from "effect"
-import { resolve } from "@opencode-ai/tui/config"
+import { resolve } from "@opencode-ai/tui/config/v1"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { makeGlobalNode } from "@opencode-ai/core/effect/app-node"
 import { makeRuntime } from "@opencode-ai/core/effect/runtime"

packages/cli/src/mini/scrollback.shared.ts

@@ -6,11 +6,7 @@ function syntax(style?: SyntaxStyle): SyntaxStyle {
   return style ?? SyntaxStyle.fromTheme([])
 }
 
-export function entrySyntax(commit: StreamCommit, theme: RunTheme): SyntaxStyle {
-  if (commit.kind === "reasoning") {
-    return syntax(theme.block.subtleSyntax ?? theme.block.syntax)
-  }
-
+export function entrySyntax(theme: RunTheme): SyntaxStyle {
   return syntax(theme.block.syntax)
 }
 

packages/cli/src/mini/scrollback.surface.ts

@@ -143,7 +143,7 @@ export class RunScrollbackStream {
     }
 
     active.renderable.fg = entryColor(active.commit, theme)
-    active.renderable.syntaxStyle = entrySyntax(active.commit, theme)
+    active.renderable.syntaxStyle = entrySyntax(theme)
   }
 
   private createEntry(commit: StreamCommit, body: ActiveBody): ActiveEntry {
@@ -165,7 +165,7 @@ export class RunScrollbackStream {
           ? new CodeRenderable(surface.renderContext, {
               content: "",
               filetype: body.filetype,
-              syntaxStyle: entrySyntax(commit, this.theme),
+              syntaxStyle: entrySyntax(this.theme),
               width: "100%",
               wrapMode: "word",
               drawUnstyledText: false,
@@ -175,7 +175,7 @@ export class RunScrollbackStream {
             })
           : new MarkdownRenderable(surface.renderContext, {
               content: "",
-              syntaxStyle: entrySyntax(commit, this.theme),
+              syntaxStyle: entrySyntax(this.theme),
               width: "100%",
               streaming: true,
               internalBlockMode: "top-level",

packages/cli/src/mini/scrollback.writer.tsx

@@ -84,7 +84,7 @@ export function RunEntryContent(props: {
   const theme = createMemo(() => props.theme ?? RUN_THEME_FALLBACK)
   const body = createMemo(() => props.body ?? entryBody(props.commit))
   const style = createMemo(() => entryLook(props.commit, theme().entry))
-  const syntax = createMemo(() => entrySyntax(props.commit, theme()))
+  const syntax = createMemo(() => entrySyntax(theme()))
   const color = createMemo(() => entryColor(props.commit, theme()))
   const suppressBackgrounds = createMemo(() => props.opts?.suppressBackgrounds === true)
   const diffBg = (color: ColorInput) => (suppressBackgrounds() ? transparent : color)

packages/cli/src/mini/theme.ts

@@ -47,7 +47,6 @@ export type RunBlockTheme = {
   text: ColorInput
   muted: ColorInput
   syntax?: SyntaxStyle
-  subtleSyntax?: SyntaxStyle
   diffAdded: ColorInput
   diffRemoved: ColorInput
   diffAddedBg: ColorInput
@@ -172,42 +171,10 @@ function tint(base: RGBA, overlay: RGBA, value: number): RGBA {
   )
 }
 
-function blend(color: RGBA, bg: RGBA): RGBA {
-  if (color.a >= 1) {
-    return color
-  }
-
-  return RGBA.fromValues(
-    bg.r + (color.r - bg.r) * color.a,
-    bg.g + (color.g - bg.g) * color.a,
-    bg.b + (color.b - bg.b) * color.a,
-    1,
-  )
-}
-
 function chroma(color: RGBA) {
   return Math.max(color.r, color.g, color.b) - Math.min(color.r, color.g, color.b)
 }
 
-function opaqueSyntaxStyle(style: SyntaxStyle | undefined, bg: RGBA): SyntaxStyle | undefined {
-  if (!style) {
-    return undefined
-  }
-
-  return SyntaxStyle.fromStyles(
-    Object.fromEntries(
-      [...style.getAllStyles()].map(([name, value]) => [
-        name,
-        {
-          ...value,
-          fg: value.fg ? blend(value.fg, bg) : value.fg,
-          bg: value.bg ? blend(value.bg, bg) : value.bg,
-        },
-      ]),
-    ),
-  )
-}
-
 function indexedPalette(colors: TerminalColors, size: number = Math.max(colors.palette.length, 16)): RGBA[] {
   return Array.from({ length: size }, (_, index) => {
     const value = colors.palette[index]
@@ -502,10 +469,7 @@ function map(
   scrollbackTheme: TuiThemeCurrent,
   splash: RunSplashTheme,
   syntax?: SyntaxStyle,
-  subtleSyntax?: SyntaxStyle,
 ): RunTheme {
-  const opaqueSubtleSyntax = opaqueSyntaxStyle(subtleSyntax, scrollbackTheme.background)
-  subtleSyntax?.destroy()
   const footerBackground = alpha(footerTheme.background, 1)
   const footerMode = mode(footerBackground)
   const shade = fade(footerTheme.backgroundMenu, footerTheme.background, 0.12, 0.56, 0.72)
@@ -566,7 +530,6 @@ function map(
       text: scrollbackTheme.text,
       muted: scrollbackTheme.textMuted,
       syntax,
-      subtleSyntax: opaqueSubtleSyntax,
       diffAdded: scrollbackTheme.diffAdded,
       diffRemoved: scrollbackTheme.diffRemoved,
       diffAddedBg: transparent,
@@ -677,13 +640,7 @@ export async function resolveRunTheme(renderer: CliRenderer): Promise<RunTheme>
       _hasSelectedListItemText: true,
     }
     const syntax = shared.generateSyntax(syntaxTheme)
-    return map(
-      footerTheme,
-      scrollbackTheme,
-      splashTheme(scrollbackTheme, indexed),
-      syntax,
-      shared.generateSubtleSyntax(syntaxTheme),
-    )
+    return map(footerTheme, scrollbackTheme, splashTheme(scrollbackTheme, indexed), syntax)
   } catch {
     return RUN_THEME_FALLBACK
   }

packages/cli/src/mini/types.ts

@@ -13,7 +13,7 @@
 //         → OpenTUI split-footer renderer writes to terminal
 import type { OpenCodeClient, ReferenceListOutput } from "@opencode-ai/client/promise"
 import type { FilePart, PermissionRequest, QuestionRequest, ToolPart } from "@opencode-ai/sdk/v2"
-import type { TuiConfig } from "@opencode-ai/tui/config"
+import type { TuiConfig } from "@opencode-ai/tui/config/v1"
 
 export type RunFilePart = {
   type: "file"

packages/cli/src/services/server.ts

@@ -11,6 +11,7 @@ export type Args = {
   readonly server?: string
   readonly standalone?: boolean
   readonly mismatch?: "replace" | "ignore" | "error"
+  readonly onStart?: Service.StartOptions["onStart"]
 }
 
 export type Resolved = {
@@ -46,7 +47,7 @@ export const resolve = Effect.fn("cli.server.resolve")(function* (args: Args) {
   }
 
   const options = yield* ServiceConfig.options()
-  const endpoint = yield* resolveManaged(options, args.mismatch ?? "replace")
+  const endpoint = yield* resolveManaged({ ...options, onStart: args.onStart }, args.mismatch ?? "replace")
   const reconnectOptions = { ...options, version: undefined }
   return {
     endpoint,
@@ -70,7 +71,7 @@ export const resolve = Effect.fn("cli.server.resolve")(function* (args: Args) {
 })
 
 const resolveManaged = Effect.fnUntraced(function* (
-  options: Service.Options,
+  options: Service.StartOptions,
   mismatch: NonNullable<Args["mismatch"]>,
 ) {
   if (mismatch === "replace") return yield* Service.start(options)

packages/cli/src/services/update-preflight.tsx

@@ -0,0 +1,494 @@
+/** @jsxImportSource @opentui/solid */
+// Split-footer status shown while a freshly launched CLI replaces a
+// version-mismatched background service before the TUI attaches.
+import { createCliRenderer, RGBA, TextAttributes, type CliRenderer, type ThemeMode } from "@opentui/core"
+import { render, useTerminalDimensions } from "@opentui/solid"
+import { InstallationVersion } from "@opencode-ai/core/installation/version"
+import { registerOpencodeSpinner } from "@opencode-ai/tui/component/register-spinner"
+import { SPINNER_FRAMES } from "@opencode-ai/tui/component/spinner"
+import { go } from "@opencode-ai/tui/logo"
+import {
+  batch,
+  createEffect,
+  createMemo,
+  createSignal,
+  For,
+  Index,
+  on,
+  onCleanup,
+  onMount,
+  Show,
+  untrack,
+} from "solid-js"
+
+const stages = ["Keeping your session safe", "Starting the new background service", "Loading OpenCode"] as const
+const stageFloor = 480
+const transitionDuration = 420
+const completionHold = 650
+
+export type Handle = {
+  readonly begin: (from?: string) => boolean
+  readonly loading: () => void
+  readonly finish: () => Promise<Handoff | undefined>
+  readonly fail: (message: string) => Promise<void>
+  readonly close: () => Promise<void>
+}
+
+export type Handoff = {
+  readonly renderer: CliRenderer
+  readonly mode: ThemeMode | null
+  readonly complete: () => void
+}
+
+export const make = (): Handle => {
+  let session: Promise<Session | undefined> | undefined
+  return {
+    begin: (from) => {
+      if (!process.stdout.isTTY || !process.stdin.isTTY) return false
+      session ??= open(from).catch(() => {
+        process.stderr.write("Restarting background server (version mismatch)...\n")
+        return undefined
+      })
+      return true
+    },
+    loading: () => {
+      void session?.then((active) => active?.loading())
+    },
+    finish: async () => {
+      const active = await session
+      return active?.finish()
+    },
+    fail: async (message) => {
+      const active = await session
+      await active?.fail(message)
+    },
+    close: async () => {
+      const active = await session
+      await active?.close()
+    },
+  }
+}
+
+type Session = {
+  readonly loading: () => Promise<void>
+  readonly finish: () => Promise<Handoff>
+  readonly fail: (message: string) => Promise<void>
+  readonly close: () => Promise<void>
+}
+
+async function open(from?: string): Promise<Session> {
+  registerOpencodeSpinner()
+  const [active, setActive] = createSignal(0)
+  const [outcome, setOutcome] = createSignal<"running" | "success" | "failure">("running")
+  const [failure, setFailure] = createSignal("")
+  const [animating, setAnimating] = createSignal(true)
+  const [visible, setVisible] = createSignal(true)
+  let resolveOutcome: (() => void) | undefined
+  const renderer = await createCliRenderer({
+    stdin: process.stdin,
+    useMouse: false,
+    autoFocus: false,
+    openConsoleOnError: false,
+    exitOnCtrlC: false,
+    screenMode: "split-footer",
+    footerHeight: 4,
+    targetFps: 60,
+    useKittyKeyboard: {},
+    consoleOptions: {
+      keyBindings: [{ name: "y", ctrl: true, action: "copy-selection" }],
+    },
+    externalOutputMode: "capture-stdout",
+    consoleMode: "disabled",
+  })
+  const terminalMode = renderer.waitForThemeMode(1000).catch(() => null)
+  await render(
+    () => (
+      <Show when={visible()}>
+        <UpdateFooter
+          from={from}
+          active={active}
+          outcome={outcome}
+          failure={failure}
+          animating={animating}
+          renderer={renderer}
+          onOutcomeSettled={() => resolveOutcome?.()}
+        />
+      </Show>
+    ),
+    renderer,
+  ).catch((error) => {
+    if (!renderer.isDestroyed) renderer.destroy()
+    throw error
+  })
+  let shownAt = performance.now()
+  const waitForStage = async () => {
+    const remaining = stageFloor - (performance.now() - shownAt)
+    if (remaining > 0) await Bun.sleep(remaining)
+  }
+  const advance = async (stage: number) => {
+    await waitForStage()
+    if (outcome() !== "running") return
+    setActive(stage)
+    shownAt = performance.now()
+  }
+  // Service.start currently exposes only its start boundary, so this first
+  // transition is time-based. Finer lifecycle callbacks remain follow-up work.
+  const auto = advance(1)
+  const transitionTo = async (next: "success" | "failure", hold: number) => {
+    const settled = Promise.withResolvers<void>()
+    resolveOutcome = settled.resolve
+    setOutcome(next)
+    const completed = await Promise.race([
+      settled.promise.then(() => true),
+      Bun.sleep(transitionDuration + 500).then(() => false),
+    ])
+    resolveOutcome = undefined
+    setAnimating(false)
+    if (completed) await Bun.sleep(hold)
+  }
+  let closing: Promise<void> | undefined
+  let transferred = false
+  const close = () =>
+    (closing ??= (async () => {
+      if (transferred) return
+      setAnimating(false)
+      if (renderer.isDestroyed) return
+      renderer.pause()
+      await Promise.race([renderer.idle(), Bun.sleep(500)])
+      renderer.destroy()
+    })())
+  let loading: Promise<void> | undefined
+  const load = () =>
+    (loading ??= (async () => {
+      await auto
+      await advance(2)
+    })())
+  let settled: Promise<void> | undefined
+  const settle = (task: () => Promise<void>) => (settled ??= task())
+  return {
+    loading: load,
+    finish: async () => {
+      await settle(async () => {
+        await load()
+        await waitForStage()
+        await transitionTo("success", completionHold)
+      })
+      const mode = await terminalMode
+      renderer.externalOutputMode = "passthrough"
+      renderer.screenMode = "alternate-screen"
+      renderer.consoleMode = "console-overlay"
+      renderer.requestRender()
+      await Promise.race([renderer.idle(), Bun.sleep(500)])
+      transferred = true
+      return {
+        renderer,
+        mode,
+        complete: () => setVisible(false),
+      }
+    },
+    fail: (message) =>
+      settle(async () => {
+        setFailure(message)
+        await transitionTo("failure", 250)
+        await close()
+      }),
+    close,
+  }
+}
+
+const colors = {
+  accent: RGBA.fromHex("#a6b8ff"),
+  accentBright: RGBA.fromHex("#eef1ff"),
+  accentDim: RGBA.fromHex("#596998"),
+  error: RGBA.fromHex("#ff8192"),
+  muted: RGBA.fromHex("#808080"),
+  success: RGBA.fromHex("#8bd5a5"),
+  text: RGBA.fromHex("#eeeeee"),
+}
+
+const monogram = go.right.slice(1)
+const sweepBlend = 8
+const textDim = RGBA.fromHex("#4c4c4c")
+const rampSteps = 32
+
+const blend = (from: RGBA, to: RGBA, amount: number) =>
+  RGBA.fromValues(
+    from.r + (to.r - from.r) * amount,
+    from.g + (to.g - from.g) * amount,
+    from.b + (to.b - from.b) * amount,
+  )
+const ramp = (from: RGBA, to: RGBA) =>
+  Array.from({ length: rampSteps + 1 }, (_, step) => blend(from, to, step / rampSteps))
+const railRamp = ramp(colors.accentDim, colors.accentBright)
+const monogramRamp = ramp(colors.muted, colors.accent)
+const rampCache = new Map<RGBA, ReadonlyArray<RGBA>>()
+const rampFor = (color: RGBA) => {
+  const cached = rampCache.get(color)
+  if (cached) return cached
+  const result = ramp(textDim, color)
+  rampCache.set(color, result)
+  return result
+}
+const shade = (palette: ReadonlyArray<RGBA>, brightness: number) =>
+  palette[Math.round(Math.max(0, Math.min(1, brightness)) * rampSteps)]
+
+type Cell = { readonly char: string; readonly color: RGBA; readonly bold?: boolean }
+const styled = (text: string, color: RGBA, bold?: boolean): Cell[] =>
+  Array.from(text).map((char) => ({ char, color, bold }))
+const phrase = (...segments: ReadonlyArray<readonly [string, RGBA, boolean?]>): Cell[] =>
+  segments.flatMap((segment, index) => [
+    ...(index > 0 ? styled(" ", colors.muted) : []),
+    ...styled(segment[0], segment[1], segment[2]),
+  ])
+
+function Monogram(props: { ink: () => RGBA }) {
+  const shadow = createMemo(() => {
+    const ink = props.ink()
+    return RGBA.fromValues(ink.r * 0.25, ink.g * 0.25, ink.b * 0.25)
+  })
+  return (
+    <box flexDirection="column">
+      <For each={monogram}>
+        {(line) => (
+          <box flexDirection="row">
+            <For each={Array.from(line)}>
+              {(char) =>
+                char === "_" ? (
+                  <text bg={shadow()} selectable={false}>
+                    {" "}
+                  </text>
+                ) : (
+                  <text fg={props.ink()} selectable={false}>
+                    {char}
+                  </text>
+                )
+              }
+            </For>
+          </box>
+        )}
+      </For>
+    </box>
+  )
+}
+
+type CellTransition = { from: Cell[]; to: Cell[]; done?: () => void }
+
+function createTransition(render: (transition: CellTransition, progress: number) => Cell[]) {
+  const [state, setState] = createSignal<{ from: Cell[]; to: Cell[]; done?: () => void } | undefined>()
+  const [progress, setProgress] = createSignal(0)
+  let elapsed = 0
+  const cells = createMemo(() => {
+    const transition = state()
+    if (!transition) return undefined
+    return render(transition, progress())
+  })
+  return {
+    start(from: Cell[], to: Cell[], done?: () => void) {
+      elapsed = 0
+      setProgress(0)
+      setState({ from, to, done })
+    },
+    tick(deltaTime: number) {
+      const transition = state()
+      if (!transition) return
+      elapsed = Math.min(transitionDuration, elapsed + deltaTime)
+      setProgress(elapsed / transitionDuration)
+      if (elapsed < transitionDuration) return
+      setState(undefined)
+      transition.done?.()
+    },
+    cells,
+    progress,
+  }
+}
+
+const createSweep = () =>
+  createTransition((transition, progress) => {
+    const length = Math.max(transition.from.length, transition.to.length)
+    const front = smoothstep(progress) * (length + 2 * sweepBlend) - sweepBlend
+    return Array.from({ length }, (_, index) => {
+      const passed = Math.max(0, Math.min(1, (front - index) / sweepBlend))
+      const brightness = smoothstep(Math.abs(passed * 2 - 1))
+      const cell = (passed >= 0.5 ? transition.to[index] : transition.from[index]) ?? {
+        char: " ",
+        color: colors.text,
+      }
+      return { ...cell, color: shade(rampFor(cell.color), brightness) }
+    })
+  })
+
+const createFade = () =>
+  createTransition((transition, progress) => {
+    const entering = progress >= 0.5
+    const brightness = smoothstep(entering ? progress * 2 - 1 : 1 - progress * 2)
+    return (entering ? transition.to : transition.from).map((cell) => ({
+      ...cell,
+      color: shade(rampFor(cell.color), brightness),
+    }))
+  })
+
+const smoothstep = (value: number) => value * value * (3 - 2 * value)
+const frameDone = Promise.resolve()
+
+function UpdateFooter(props: {
+  from?: string
+  active: () => number
+  outcome: () => "running" | "success" | "failure"
+  failure: () => string
+  animating: () => boolean
+  renderer: CliRenderer
+  onOutcomeSettled: () => void
+}) {
+  const term = useTerminalDimensions()
+  const [position, setPosition] = createSignal(0)
+  const [pulse, setPulse] = createSignal(0)
+  const headerFade = createFade()
+  const statusSweep = createSweep()
+  const runningHeader = () =>
+    phrase(
+      ["OpenCode", colors.muted, true],
+      ["is updating", colors.muted],
+      ...(props.from
+        ? ([
+            ["from", colors.muted],
+            [props.from, colors.accentDim],
+          ] as const)
+        : []),
+      ["to", colors.muted],
+      [InstallationVersion, colors.accent],
+    )
+  const completedHeader = phrase(
+    ["OpenCode", colors.muted, true],
+    ["updated to", colors.muted],
+    [InstallationVersion, colors.accent],
+  )
+  const pausedHeader = phrase(["OpenCode", colors.muted, true], ["update paused", colors.muted])
+  const outcomeStatus = () =>
+    props.outcome() === "success"
+      ? [...styled("✓", colors.success), ...styled(" Ready", colors.text)]
+      : [...styled("!", colors.error), ...styled(" " + props.failure(), colors.text)]
+  let previousStage: string = stages[0]
+  createEffect(
+    on(props.active, (index) => {
+      if (props.outcome() !== "running") return
+      const next = stages[index]
+      if (next === previousStage) return
+      statusSweep.start(styled(previousStage, colors.text), styled(next, colors.text))
+      previousStage = next
+    }),
+  )
+  createEffect(
+    on(
+      props.outcome,
+      (outcome) => {
+        if (outcome === "running") return
+        const visibleStatus = untrack(statusSweep.cells) ?? styled(previousStage, colors.text)
+        headerFade.start(runningHeader(), outcome === "success" ? completedHeader : pausedHeader)
+        statusSweep.start([...styled("  ", colors.text), ...visibleStatus], outcomeStatus(), props.onOutcomeSettled)
+      },
+      { defer: true },
+    ),
+  )
+  const header = createMemo(
+    () =>
+      headerFade.cells() ??
+      (props.outcome() === "success"
+        ? completedHeader
+        : props.outcome() === "failure"
+          ? pausedHeader
+          : runningHeader()),
+  )
+  const monogramInk = createMemo(() =>
+    props.outcome() === "success" ? shade(monogramRamp, smoothstep(headerFade.progress())) : colors.muted,
+  )
+  const rail = createMemo(() => {
+    const width = Math.max(0, Math.min(30, term().width - 39))
+    if (width === 0) return []
+    const filled = Math.round(position() * width)
+    const glowRadius = 6
+    const span = Math.max(1, filled + glowRadius * 2)
+    const center = pulse() * span - glowRadius
+    const success = props.outcome() === "success"
+    const completion = smoothstep(headerFade.progress())
+    return Array.from({ length: width }, (_, index) => {
+      const color =
+        index >= filled
+          ? colors.muted
+          : shade(railRamp, Math.max(0, 1 - Math.abs(index - center) / glowRadius) ** 2)
+      return {
+        char: success || index < filled ? "━" : "·",
+        color: success ? blend(color, colors.accent, completion) : color,
+      }
+    })
+  })
+
+  onMount(() => {
+    let value = 0
+    let velocity = 0
+    let phase = 0
+    const frame = (deltaTime: number) => {
+      if (!props.animating()) return frameDone
+      const elapsed = Math.min(0.032, deltaTime / 1_000)
+      const stiffness = 110
+      const damping = 2 * Math.sqrt(stiffness)
+      const target = props.outcome() === "success" ? 1 : (props.active() + 1) / stages.length
+      velocity += (stiffness * (target - value) - damping * velocity) * elapsed
+      value += velocity * elapsed
+      phase = (phase + deltaTime / 900) % 1
+      batch(() => {
+        setPosition(Math.max(0, Math.min(1, value)))
+        setPulse(phase)
+      })
+      headerFade.tick(deltaTime)
+      statusSweep.tick(deltaTime)
+      return frameDone
+    }
+    props.renderer.setFrameCallback(frame)
+    onCleanup(() => props.renderer.removeFrameCallback(frame))
+  })
+
+  return (
+    <box width="100%" height={4} flexDirection="row" gap={1} live={props.animating()}>
+      <Monogram ink={monogramInk} />
+      <box flexDirection="column" flexGrow={1} overflow="hidden">
+        <CellLine cells={header()} />
+        <Show
+          when={props.outcome() === "running"}
+          fallback={<CellLine cells={statusSweep.cells() ?? outcomeStatus()} />}
+        >
+          <box flexDirection="row" gap={1}>
+            <spinner frames={SPINNER_FRAMES} interval={80} color={colors.accent} />
+            <CellLine cells={statusSweep.cells() ?? styled(stages[props.active()], colors.text)} />
+          </box>
+        </Show>
+        <box flexDirection="row" gap={1}>
+          <CellLine cells={rail()} />
+          <text fg={colors.muted}>
+            {props.outcome() === "success" ? stages.length : props.active() + 1}/{stages.length}
+          </text>
+        </box>
+      </box>
+    </box>
+  )
+}
+
+function CellLine(props: { cells: ReadonlyArray<Cell> }) {
+  return (
+    <text truncate>
+      <Index each={props.cells}>
+        {(cell) => (
+          <span
+            style={{
+              fg: cell().color,
+              attributes: cell().bold ? TextAttributes.BOLD : TextAttributes.NONE,
+            }}
+          >
+            {cell().char}
+          </span>
+        )}
+      </Index>
+    </text>
+  )
+}
+
+export * as UpdatePreflight from "./update-preflight"

packages/cli/test/config.test.ts

@@ -0,0 +1,144 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { Global } from "@opencode-ai/core/global"
+import { Effect } from "effect"
+import { expect, test } from "bun:test"
+import path from "path"
+import { Config } from "../src/config"
+
+function run<A, E>(directory: string, effect: Effect.Effect<A, E, Config.Service>) {
+  return Effect.runPromise(
+    effect.pipe(
+      Effect.provide(Config.layer),
+      Effect.provide(Global.layerWith({ config: directory, state: directory })),
+      Effect.provide(NodeFileSystem.layer),
+    ),
+  )
+}
+
+test("migrates tui and kv config into cli.json", async () => {
+  const directory = await Bun.$`mktemp -d`.text().then((value) => value.trim())
+  await Bun.write(
+    path.join(directory, "tui.json"),
+    JSON.stringify({
+      theme: "legacy",
+      keybinds: { leader: "ctrl+o" },
+      plugin: [["example", { mode: "safe" }]],
+      plugin_enabled: { disabled: false },
+      leader_timeout: 500,
+      scroll_speed: 2,
+      scroll_acceleration: { enabled: true },
+      diff_style: "stacked",
+      mouse: false,
+    }),
+  )
+  await Bun.write(
+    path.join(directory, "kv.json"),
+    JSON.stringify({
+      theme_mode_lock: "light",
+      attention_sound_pack: "custom.pack",
+      diff_wrap_mode: "none",
+      diff_viewer_show_file_tree: false,
+      diff_viewer_single_patch: true,
+      diff_viewer_view: "split",
+      terminal_title_enabled: false,
+      file_context_enabled: false,
+      paste_summary_enabled: false,
+      sidebar: "hide",
+      scrollbar_visible: true,
+      thinking_mode: "show",
+      exploration_grouping: false,
+      tips_hidden: true,
+      dismissed_getting_started: true,
+      animations_enabled: false,
+      skipped_version: "9.9.9",
+      which_key_layout: "overlay",
+    }),
+  )
+
+  try {
+    const config = await run(
+      directory,
+      Effect.gen(function* () {
+        const service = yield* Config.Service
+        return yield* service.get()
+      }),
+    )
+
+    expect(config).toMatchObject({
+      theme: { name: "legacy", mode: "light" },
+      keybinds: { leader: "ctrl+o" },
+      plugins: [{ package: "example", options: { mode: "safe" } }, "-disabled"],
+      leader: { timeout: 500 },
+      scroll: { speed: 2, acceleration: true },
+      attention: { sound_pack: "custom.pack" },
+      diffs: { wrap: "none", tree: false, single: true, view: "split" },
+      terminal: { title: false },
+      prompt: { editor: false, paste: "full" },
+      session: { sidebar: "hide", scrollbar: true, thinking: "show", grouping: "none" },
+      hints: { tips: false, onboarding: false },
+      animations: false,
+      mouse: false,
+    })
+    expect(config).not.toHaveProperty("skipped_version")
+    expect(config).not.toHaveProperty("which_key")
+    expect((await Bun.file(path.join(directory, "cli.json")).json()).keybinds).toEqual({ leader: "ctrl+o" })
+    expect(await Bun.file(path.join(directory, "cli.json")).exists()).toBe(true)
+    expect(await Bun.file(path.join(directory, "tui.json")).exists()).toBe(true)
+    expect(await Bun.file(path.join(directory, "kv.json")).exists()).toBe(true)
+  } finally {
+    await Bun.$`rm -rf ${directory}`
+  }
+})
+
+test("migrates before the first update and does not remigrate afterward", async () => {
+  const directory = await Bun.$`mktemp -d`.text().then((value) => value.trim())
+  await Bun.write(path.join(directory, "tui.json"), JSON.stringify({ theme: "legacy" }))
+
+  try {
+    const config = await run(
+      directory,
+      Effect.gen(function* () {
+        const service = yield* Config.Service
+        yield* service.update((draft) => {
+          draft.animations = false
+          draft.mouse = false
+        })
+        yield* Effect.promise(() =>
+          Bun.write(path.join(directory, "tui.json"), JSON.stringify({ theme: "changed" })),
+        )
+        return yield* service.get()
+      }),
+    )
+
+    expect(config).toEqual({ theme: { name: "legacy" }, animations: false, mouse: false })
+    expect(await Bun.file(path.join(directory, "cli.json")).json()).toEqual({
+      theme: { name: "legacy" },
+      animations: false,
+      mouse: false,
+    })
+  } finally {
+    await Bun.$`rm -rf ${directory}`
+  }
+})
+
+test("updates a config draft while preserving JSONC comments", async () => {
+  const directory = await Bun.$`mktemp -d`.text().then((value) => value.trim())
+  await Bun.write(path.join(directory, "cli.json"), "{\n  // Keep this comment\n  \"animations\": true\n}\n")
+
+  try {
+    const config = await run(
+      directory,
+      Effect.gen(function* () {
+        const service = yield* Config.Service
+        return yield* service.update((draft) => {
+          draft.prompt = { paste: "compact" }
+        })
+      }),
+    )
+
+    expect(config).toEqual({ animations: true, prompt: { paste: "compact" } })
+    expect(await Bun.file(path.join(directory, "cli.json")).text()).toContain("// Keep this comment")
+  } finally {
+    await Bun.$`rm -rf ${directory}`
+  }
+})

packages/cli/test/footer-keymap.test.tsx

@@ -0,0 +1,106 @@
+/** @jsxImportSource @opentui/solid */
+import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
+import { testRender, useRenderer } from "@opentui/solid"
+import { OpencodeKeymapProvider, registerOpencodeKeymap } from "@opencode-ai/tui/keymap"
+import { resolve } from "@opencode-ai/tui/config/v1"
+import { expect, test } from "bun:test"
+import { createComponent, createSignal } from "solid-js"
+import { RunFooterView } from "../src/mini/footer.view"
+import { RUN_THEME_FALLBACK } from "../src/mini/theme"
+import type { FooterState, FooterSubagentState, FooterView } from "../src/mini/types"
+
+test("down opens subagents from an empty prompt", async () => {
+  const [state] = createSignal<FooterState>({
+    phase: "idle",
+    status: "",
+    queue: 0,
+    model: "gpt-5",
+    duration: "",
+    usage: "",
+    first: false,
+    interrupt: 0,
+    exit: 0,
+  })
+  const [view] = createSignal<FooterView>({ type: "prompt" })
+  const [subagents] = createSignal<FooterSubagentState>({
+    tabs: [
+      {
+        sessionID: "subagent-1",
+        partID: "part-1",
+        callID: "call-1",
+        label: "Explore",
+        description: "Inspect the keymap",
+        status: "running",
+        lastUpdatedAt: 1,
+      },
+    ],
+    details: {},
+    permissions: [],
+    questions: [],
+  })
+  const config = resolve(
+    { keybinds: { editor_open: "none", session_queued_prompts: "none" } },
+    { terminalSuspend: true },
+  )
+  let offKeymap: (() => void) | undefined
+
+  function Harness() {
+    const renderer = useRenderer()
+    const keymap = createDefaultOpenTuiKeymap(renderer)
+    offKeymap = registerOpencodeKeymap(keymap, renderer, config)
+
+    return createComponent(OpencodeKeymapProvider, {
+      keymap,
+      get children() {
+        return (
+          <RunFooterView
+            directory="/tmp"
+            findFiles={async () => []}
+            agents={() => []}
+            references={() => []}
+            commands={() => []}
+            providers={() => undefined}
+            currentModel={() => undefined}
+            variants={() => []}
+            currentVariant={() => undefined}
+            state={state}
+            view={view}
+            subagent={subagents}
+            theme={() => RUN_THEME_FALLBACK}
+            tuiConfig={config}
+            agent="opencode"
+            onSubmit={() => true}
+            onPermissionReply={() => {}}
+            onQuestionReply={() => {}}
+            onQuestionReject={() => {}}
+            onCycle={() => {}}
+            onInterrupt={() => false}
+            onEditorOpen={async () => undefined}
+            onInputClear={() => {}}
+            onExit={() => {}}
+            onModelSelect={() => {}}
+            onVariantSelect={() => {}}
+            onRows={() => {}}
+            onLayout={() => {}}
+            onStatus={() => {}}
+            onQueuedRemove={async () => true}
+          />
+        )
+      },
+    })
+  }
+
+  const app = await testRender(() => <Harness />, { width: 100, height: 8, kittyKeyboard: true })
+  try {
+    await app.renderOnce()
+    expect(app.renderer.currentFocusedEditor?.plainText).toBe("")
+    app.mockInput.pressArrow("down")
+    await app.renderOnce()
+    expect(app.captureCharFrame()).toContain("Select subagent")
+  } finally {
+    app.renderer.currentFocusedRenderable?.blur()
+    app.renderer.currentFocusedEditor?.blur()
+    offKeymap?.()
+    app.renderer.destroy()
+  }
+})

packages/client/package.json

@@ -16,6 +16,7 @@
     "dist"
   ],
   "exports": {
+    ".": "./src/promise/index.ts",
     "./promise": "./src/promise/index.ts",
     "./promise/api": "./src/promise/api.ts",
     "./effect": "./src/effect/index.ts",

packages/client/src/effect/api/api.ts

@@ -476,18 +476,16 @@ export interface IntegrationApi<E = never> {
 type Endpoint11_0Request = Parameters<RawClient["server.mcp"]["mcp.list"]>[0]
 export type Endpoint11_0Input = { readonly location?: Endpoint11_0Request["query"]["location"] }
 export type Endpoint11_0Output = EffectValue<ReturnType<RawClient["server.mcp"]["mcp.list"]>>
-export type ServerMcpListOperation<E = never> = (input?: Endpoint11_0Input) => Effect.Effect<Endpoint11_0Output, E>
+export type McpListOperation<E = never> = (input?: Endpoint11_0Input) => Effect.Effect<Endpoint11_0Output, E>
 
 type Endpoint11_1Request = Parameters<RawClient["server.mcp"]["mcp.resource.catalog"]>[0]
 export type Endpoint11_1Input = { readonly location?: Endpoint11_1Request["query"]["location"] }
 export type Endpoint11_1Output = EffectValue<ReturnType<RawClient["server.mcp"]["mcp.resource.catalog"]>>
-export type ServerMcpResourceCatalogOperation<E = never> = (
-  input?: Endpoint11_1Input,
-) => Effect.Effect<Endpoint11_1Output, E>
+export type McpResourceCatalogOperation<E = never> = (input?: Endpoint11_1Input) => Effect.Effect<Endpoint11_1Output, E>
 
-export interface ServerMcpApi<E = never> {
-  readonly list: ServerMcpListOperation<E>
-  readonly resource: { readonly catalog: ServerMcpResourceCatalogOperation<E> }
+export interface McpApi<E = never> {
+  readonly list: McpListOperation<E>
+  readonly resource: { readonly catalog: McpResourceCatalogOperation<E> }
 }
 
 type Endpoint12_0Request = Parameters<RawClient["server.credential"]["credential.update"]>[0]
@@ -550,9 +548,7 @@ export type Endpoint14_2Input = {
   readonly id?: Endpoint14_2Request["payload"]["id"]
   readonly title: Endpoint14_2Request["payload"]["title"]
   readonly metadata?: Endpoint14_2Request["payload"]["metadata"]
-  readonly mode: Endpoint14_2Request["payload"]["mode"]
-  readonly fields?: Endpoint14_2Request["payload"]["fields"]
-  readonly url?: Endpoint14_2Request["payload"]["url"]
+  readonly fields: Endpoint14_2Request["payload"]["fields"]
 }
 export type Endpoint14_2Output = EffectValue<ReturnType<RawClient["server.form"]["session.form.create"]>>["data"]
 export type FormCreateOperation<E = never> = (input: Endpoint14_2Input) => Effect.Effect<Endpoint14_2Output, E>
@@ -957,7 +953,7 @@ export interface AppApi<E = never> {
   readonly generate: GenerateApi<E>
   readonly provider: ProviderApi<E>
   readonly integration: IntegrationApi<E>
-  readonly "server.mcp": ServerMcpApi<E>
+  readonly mcp: McpApi<E>
   readonly credential: CredentialApi<E>
   readonly project: ProjectApi<E>
   readonly form: FormApi<E>

packages/client/src/effect/generated/client.ts

@@ -655,21 +655,12 @@ type Endpoint14_2Input = {
   readonly id?: Endpoint14_2Request["payload"]["id"]
   readonly title: Endpoint14_2Request["payload"]["title"]
   readonly metadata?: Endpoint14_2Request["payload"]["metadata"]
-  readonly mode: Endpoint14_2Request["payload"]["mode"]
-  readonly fields?: Endpoint14_2Request["payload"]["fields"]
-  readonly url?: Endpoint14_2Request["payload"]["url"]
+  readonly fields: Endpoint14_2Request["payload"]["fields"]
 }
 const Endpoint14_2 = (raw: RawClient["server.form"]) => (input: Endpoint14_2Input) =>
   raw["session.form.create"]({
     params: { sessionID: input["sessionID"] },
-    payload: {
-      id: input["id"],
-      title: input["title"],
-      metadata: input["metadata"],
-      mode: input["mode"],
-      fields: input["fields"],
-      url: input["url"],
-    },
+    payload: { id: input["id"], title: input["title"], metadata: input["metadata"], fields: input["fields"] },
   }).pipe(
     Effect.mapError(mapClientError),
     Effect.map((value) => value.data),
@@ -1143,7 +1134,7 @@ const adaptClient = (raw: RawClient) => ({
   generate: adaptGroup8(raw["server.generate"]),
   provider: adaptGroup9(raw["server.provider"]),
   integration: adaptGroup10(raw["server.integration"]),
-  "server.mcp": adaptGroup11(raw["server.mcp"]),
+  mcp: adaptGroup11(raw["server.mcp"]),
   credential: adaptGroup12(raw["server.credential"]),
   project: adaptGroup13(raw["server.project"]),
   form: adaptGroup14(raw["server.form"]),

packages/client/src/effect/service.ts

@@ -32,6 +32,15 @@ export type Options = {
   readonly command?: ReadonlyArray<string>
 }
 
+export type StartReason = "missing" | "version-mismatch"
+
+export type StartOptions = Options & {
+  // Called once when start() decides it must spawn: either no service was
+  // found, or a healthy service with a different version is being replaced.
+  // `existing` carries the registration of the service being replaced.
+  readonly onStart?: (reason: StartReason, existing?: Info) => void
+}
+
 // Read-only lookup: registration file plus health check and version gate.
 // Never spawns; escalation to start() is the caller's policy.
 export const discover = Effect.fn("service.discover")(function* (options: Options = {}) {
@@ -47,11 +56,14 @@ const discoverLocal = Effect.fnUntraced(function* (options: Options) {
 
 // Idempotent ensure-running: reuses a healthy compatible server, replaces a
 // version-mismatched one, and otherwise spawns the service command detached.
-export const start = Effect.fn("service.start")(function* (options: Options = {}) {
+export const start = Effect.fn("service.start")(function* (options: StartOptions = {}) {
   const compatible = yield* discover(options)
   if (compatible !== undefined) return compatible
-  const mismatched = yield* find(options)
-  if (mismatched !== undefined) yield* kill(mismatched.info, options).pipe(Effect.ignore)
+  const existing = yield* find(options)
+  if (existing?.version !== undefined && (options.version === undefined || existing.version === options.version))
+    return existing.endpoint
+  yield* Effect.sync(() => options.onStart?.(existing === undefined ? "missing" : "version-mismatch", existing?.info))
+  if (existing !== undefined) yield* kill(existing.info, options).pipe(Effect.ignore)
 
   const [command, ...args] = options.command ?? ["opencode", "serve", "--service"]
   if (command === undefined) return yield* Effect.fail(new Error("Missing service command"))
@@ -126,6 +138,7 @@ const read = Effect.fnUntraced(function* (file?: string) {
 type LocalService = {
   readonly info: Info
   readonly endpoint: Endpoint
+  readonly version?: string
 }
 
 const probe = Effect.fnUntraced(function* (info: Info, version?: string, allowLegacy = false) {
@@ -149,7 +162,7 @@ const probe = Effect.fnUntraced(function* (info: Info, version?: string, allowLe
     if (health.value.pid !== info.pid) return undefined
     if (info.version !== undefined && health.value.version !== info.version) return undefined
     if (version !== undefined && health.value.version !== version) return undefined
-    return { info, endpoint } satisfies LocalService
+    return { info, endpoint, version: health.value.version } satisfies LocalService
   }
   if (
     !allowLegacy ||

packages/client/src/promise/api.ts

@@ -1,43 +1,15 @@
-import type {
-  AgentApi as EffectAgentApi,
-  CommandApi as EffectCommandApi,
-  EventApi as EffectEventApi,
-  IntegrationApi as EffectIntegrationApi,
-  ModelApi as EffectModelApi,
-  PluginApi as EffectPluginApi,
-  ProviderApi as EffectProviderApi,
-  ReferenceApi as EffectReferenceApi,
-  SessionApi as EffectSessionApi,
-  SkillApi as EffectSkillApi,
-} from "../effect/api/api.js"
-import type { Effect, Stream } from "effect"
+type Client = ReturnType<typeof import("./generated/client.js").make>
 
-type PromisifyOperation<Operation> = Operation extends (
-  ...args: infer Args
-) => Effect.Effect<infer Success, unknown, unknown>
-  ? (...args: Args) => Promise<Success>
-  : Operation extends (...args: infer Args) => Stream.Stream<infer Success, unknown, unknown>
-    ? (...args: Args) => AsyncIterable<Success>
-    : Operation extends (...args: infer _Args) => unknown
-      ? Operation
-      : Operation extends object
-        ? PromisifyApi<Operation>
-        : Operation
-
-type PromisifyApi<Api> = {
-  readonly [Name in keyof Api]: PromisifyOperation<Api[Name]>
-}
-
-export type AgentApi = PromisifyApi<EffectAgentApi<unknown>>
-export type CommandApi = PromisifyApi<EffectCommandApi<unknown>>
-export type EventApi = PromisifyApi<EffectEventApi<unknown>>
-export type IntegrationApi = PromisifyApi<EffectIntegrationApi<unknown>>
-export type ModelApi = PromisifyApi<EffectModelApi<unknown>>
-export type PluginApi = PromisifyApi<EffectPluginApi<unknown>>
-export type ProviderApi = PromisifyApi<EffectProviderApi<unknown>>
-export type ReferenceApi = PromisifyApi<EffectReferenceApi<unknown>>
-export type SessionApi = PromisifyApi<EffectSessionApi<unknown>>
-export type SkillApi = PromisifyApi<EffectSkillApi<unknown>>
+export type AgentApi = Client["agent"]
+export type CommandApi = Client["command"]
+export type EventApi = Client["event"]
+export type IntegrationApi = Client["integration"]
+export type ModelApi = Client["model"]
+export type PluginApi = Client["plugin"]
+export type ProviderApi = Client["provider"]
+export type ReferenceApi = Client["reference"]
+export type SessionApi = Client["session"]
+export type SkillApi = Client["skill"]
 
 export interface CatalogApi {
   readonly provider: ProviderApi

packages/client/src/promise/generated/client-error.ts

@@ -1,4 +1,9 @@
-export type ClientErrorReason = "Transport" | "UnexpectedStatus" | "UnsupportedContentType" | "MalformedResponse"
+export type ClientErrorReason =
+  | "Transport"
+  | "UnexpectedStatus"
+  | "UnsupportedContentType"
+  | "MalformedResponse"
+  | "SseEventTooLarge"
 
 export class ClientError extends Error {
   override readonly name = "ClientError"

packages/client/src/promise/generated/client.ts

@@ -90,10 +90,10 @@ import type {
   IntegrationAttemptCompleteOutput,
   IntegrationAttemptCancelInput,
   IntegrationAttemptCancelOutput,
-  ServerMcpListInput,
-  ServerMcpListOutput,
-  ServerMcpResourceCatalogInput,
-  ServerMcpResourceCatalogOutput,
+  McpListInput,
+  McpListOutput,
+  McpResourceCatalogInput,
+  McpResourceCatalogOutput,
   CredentialUpdateInput,
   CredentialUpdateOutput,
   CredentialRemoveInput,
@@ -193,12 +193,12 @@ import { ClientError } from "./client-error"
 export interface ClientOptions {
   readonly baseUrl: string
   readonly fetch?: typeof globalThis.fetch
-  readonly headers?: HeadersInit
+  readonly headers?: RequestInit["headers"]
 }
 
 export interface RequestOptions {
   readonly signal?: AbortSignal
-  readonly headers?: HeadersInit
+  readonly headers?: RequestInit["headers"]
 }
 
 interface RequestDescriptor {
@@ -213,6 +213,8 @@ interface RequestDescriptor {
   readonly binary?: true
 }
 
+const maxSseEventBytes = 16 * 1024 * 1024
+
 export function make(options: ClientOptions) {
   const fetch = options.fetch ?? globalThis.fetch
 
@@ -289,7 +291,7 @@ export function make(options: ClientOptions) {
             throw new ClientError("Transport", { cause })
           }
           buffer += decoder.decode(next.value, { stream: !next.done })
-          if (buffer.length > 1_048_576) throw new ClientError("MalformedResponse")
+          if (buffer.length > maxSseEventBytes) throw new ClientError("SseEventTooLarge")
           const trailingCarriageReturn = !next.done && buffer.endsWith("\r")
           if (trailingCarriageReturn) buffer = buffer.slice(0, -1)
           buffer = buffer.replaceAll("\r\n", "\n").replaceAll("\r", "\n")
@@ -701,7 +703,7 @@ export function make(options: ClientOptions) {
                 path: `/api/session/${encodeURIComponent(input.sessionID)}/instructions/entries/${encodeURIComponent(input.key)}`,
                 body: { value: input["value"] },
                 successStatus: 204,
-                declaredStatuses: [404, 400, 401],
+                declaredStatuses: [404, 413, 400, 401],
                 empty: true,
               },
               requestOptions,
@@ -939,9 +941,9 @@ export function make(options: ClientOptions) {
           ),
       },
     },
-    "server.mcp": {
-      list: (input?: ServerMcpListInput, requestOptions?: RequestOptions) =>
-        request<ServerMcpListOutput>(
+    mcp: {
+      list: (input?: McpListInput, requestOptions?: RequestOptions) =>
+        request<McpListOutput>(
           {
             method: "GET",
             path: `/api/mcp`,
@@ -953,8 +955,8 @@ export function make(options: ClientOptions) {
           requestOptions,
         ),
       resource: {
-        catalog: (input?: ServerMcpResourceCatalogInput, requestOptions?: RequestOptions) =>
-          request<ServerMcpResourceCatalogOutput>(
+        catalog: (input?: McpResourceCatalogInput, requestOptions?: RequestOptions) =>
+          request<McpResourceCatalogOutput>(
             {
               method: "GET",
               path: `/api/mcp/resource`,
@@ -1056,14 +1058,7 @@ export function make(options: ClientOptions) {
           {
             method: "POST",
             path: `/api/session/${encodeURIComponent(input.sessionID)}/form`,
-            body: {
-              id: input["id"],
-              title: input["title"],
-              metadata: input["metadata"],
-              mode: input["mode"],
-              fields: input["fields"],
-              url: input["url"],
-            },
+            body: { id: input["id"], title: input["title"], metadata: input["metadata"], fields: input["fields"] },
             successStatus: 200,
             declaredStatuses: [404, 409, 400, 401],
             empty: false,

packages/client/test/fixture/service.ts

@@ -0,0 +1,39 @@
+import { rename, writeFile } from "node:fs/promises"
+
+const [registration, mode] = process.argv.slice(2)
+if (registration === undefined || mode === undefined) throw new Error("Missing service fixture arguments")
+
+let requests = 0
+const server = Bun.serve({
+  port: 0,
+  async fetch(request) {
+    if (new URL(request.url).pathname !== "/api/health") return new Response(null, { status: 404 })
+    requests += 1
+    if (mode === "modern" && requests === 1) {
+      await writeFile(registration + ".first-request", "")
+      while (!(await Bun.file(registration + ".release").exists())) await Bun.sleep(5)
+      return new Response(null, { status: 503 })
+    }
+    if (mode === "legacy") return Response.json({ healthy: true })
+    return Response.json({ healthy: true, version: "test", pid: process.pid })
+  },
+})
+
+await writeFile(
+  registration + ".tmp",
+  JSON.stringify({
+    id: crypto.randomUUID(),
+    version: mode === "legacy" ? undefined : "test",
+    url: server.url.toString(),
+    pid: process.pid,
+  }),
+  { mode: 0o600 },
+)
+await rename(registration + ".tmp", registration)
+
+const shutdown = () => {
+  server.stop(true)
+  process.exit()
+}
+process.on("SIGTERM", shutdown)
+process.on("SIGINT", shutdown)

packages/client/test/import-boundaries.test.ts

@@ -12,7 +12,7 @@ const server = resolve(import.meta.dir, "../../server")
 
 describe("public import boundaries", () => {
   test("isolates each public entrypoint", async () => {
-    const root = await bundleInputs("@opencode-ai/client/promise", "browser")
+    const root = await bundleInputs("@opencode-ai/client", "browser")
 
     expect(within(root, effect)).toEqual([])
     expect(within(root, schema)).toEqual([])

packages/client/test/promise.test.ts

@@ -284,6 +284,43 @@ test("event.subscribe terminates on malformed Promise SSE data", async () => {
   })
 })
 
+test("event.subscribe accepts a fragmented SSE event below the size limit", async () => {
+  const event = { id: "evt_large", type: "test.large", data: { output: "x".repeat(12 * 1024 * 1024) } }
+  const encoded = new TextEncoder().encode(`data: ${JSON.stringify(event)}\n\n`)
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async () =>
+      new Response(
+        new ReadableStream({
+          start(controller) {
+            for (let offset = 0; offset < encoded.length; offset += 64 * 1024) {
+              controller.enqueue(encoded.slice(offset, offset + 64 * 1024))
+            }
+            controller.close()
+          },
+        }),
+        { headers: { "content-type": "text/event-stream" } },
+      ),
+  })
+
+  await expect(client.event.subscribe()[Symbol.asyncIterator]().next()).resolves.toEqual({ done: false, value: event })
+})
+
+test("event.subscribe rejects an SSE event above the size limit", async () => {
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async () =>
+      new Response(`data: ${JSON.stringify({ output: "x".repeat(16 * 1024 * 1024) })}`, {
+        headers: { "content-type": "text/event-stream" },
+      }),
+  })
+
+  await expect(client.event.subscribe()[Symbol.asyncIterator]().next()).rejects.toMatchObject({
+    name: "ClientError",
+    reason: "SseEventTooLarge",
+  })
+})
+
 test("session methods use the public HTTP contract", async () => {
   const requests: Array<{ url: string; init?: RequestInit }> = []
   const client = OpenCode.make({

packages/client/test/service.test.ts

@@ -0,0 +1,91 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { afterEach, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { Service } from "../src/effect/index"
+
+const fixture = join(import.meta.dir, "fixture/service.ts")
+const processes: Bun.Subprocess[] = []
+const directories: string[] = []
+
+afterEach(async () => {
+  processes.forEach((process) => process.kill("SIGTERM"))
+  await Promise.all(processes.splice(0).map((process) => process.exited))
+  await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })))
+})
+
+test("a concurrent same-version start cannot invalidate a resolved endpoint", async () => {
+  const directory = await temp()
+  const registration = join(directory, "service.json")
+  spawn(registration, "modern")
+  await waitForFile(registration)
+  const original = await Bun.file(registration).json()
+
+  const starts: Service.StartReason[] = []
+  const first = run(
+    Service.start({
+      file: registration,
+      version: "test",
+      command: [],
+      onStart: (reason) => starts.push(reason),
+    }),
+  )
+  await waitForFile(registration + ".first-request")
+
+  const resolved = await run(Service.start({ file: registration, version: "test" }))
+  expect(resolved.url).toBe(original.url)
+
+  await writeFile(registration + ".release", "")
+  await first
+
+  expect(starts).toEqual([])
+  expect(await Bun.file(registration).json()).toEqual(original)
+  expect(await health(resolved.url)).toEqual({ healthy: true, version: "test", pid: original.pid })
+})
+
+test("a legacy health response is still replaced", async () => {
+  const directory = await temp()
+  const registration = join(directory, "service.json")
+  const existing = spawn(registration, "legacy")
+  await waitForFile(registration)
+
+  const starts: Service.StartReason[] = []
+  const result = run(Service.start({ file: registration, command: [], onStart: (reason) => starts.push(reason) }))
+
+  await expect(result).rejects.toThrow("Missing service command")
+  expect(starts).toEqual(["version-mismatch"])
+  await existing.exited
+})
+
+function run<A, E>(effect: Effect.Effect<A, E, never>) {
+  return Effect.runPromise(effect.pipe(Effect.provide(NodeFileSystem.layer)))
+}
+
+function spawn(registration: string, mode: string, ...args: string[]) {
+  const subprocess = Bun.spawn([process.execPath, fixture, registration, mode, ...args], {
+    stdout: "ignore",
+    stderr: "inherit",
+  })
+  processes.push(subprocess)
+  return subprocess
+}
+
+async function temp() {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-client-service-"))
+  directories.push(directory)
+  return directory
+}
+
+async function waitForFile(file: string) {
+  for (let attempt = 0; attempt < 600; attempt++) {
+    if (await Bun.file(file).exists()) return
+    await Bun.sleep(5)
+  }
+  throw new Error(`Timed out waiting for ${file}`)
+}
+
+async function health(url: string) {
+  return fetch(new URL("/api/health", url), { signal: AbortSignal.timeout(1_000) }).then((response) => response.json())
+}

packages/codemode/AGENTS.md

@@ -4,7 +4,7 @@
 - Do not add a speculative generic permission or approval policy. A host omits tools it does not expose and enforces domain authorization inside each provided tool.
 - Keep Code Mode unaware of host session, channel, and conversation models. The hosting application supplies trusted execution scope around it.
 - Tool schemas are the model-facing Interface. Keep arguments minimal and natural to the operation; never add unrelated IDs as ambient capability tokens.
-- When interpreter behavior or support changes, update `interpreter-support.md` and direct tests in the same PR. Update `codemode.md` when the package design, integration status, or rationale changes.
+- When interpreter behavior or support changes, update `interpreter-support.md` and direct tests in the same PR.
 
 ## OpenAPI
 

packages/codemode/README.md

@@ -1,37 +1,40 @@
 # @opencode-ai/codemode
 
-Effect-native confined code execution over explicit, schema-described tools.
+This is our take on code mode. Programs are written in a lightweight, JavaScript-like DSL and run in the package's
+own interpreter. They never execute as actual JavaScript, so there is no runtime to escape into. The interpreter
+itself can reach nothing; every effect a program has goes through a tool you explicitly supplied. The tradeoff is a
+bounded language rather than full JavaScript: the [interpreter support checklist](./interpreter-support.md) documents
+exactly what is supported.
 
-CodeMode lets a model write a small JavaScript program that can call only the tools supplied by the host. The program can sequence calls, transform plain data, branch, loop, and run independent calls in parallel without receiving ambient filesystem, process, network, module, or application authority.
+[Cloudflare's post](https://blog.cloudflare.com/code-mode/) introduced the idea. Their implementation executes
+generated code in isolate sandboxes. We took a lighter route: a pure interpreter that runs wherever your application
+runs, no sandbox required.
 
-The package is currently private to this workspace. Its API is designed around one-shot and reusable execution:
+## How it differs from JavaScript
 
-```ts
-// One execution
-yield * CodeMode.execute({ tools, code })
+The deliberate differences:
 
-// A reusable runtime
-const runtime = CodeMode.make({ tools, limits })
-yield * runtime.execute(code)
-```
+- **No ambient authority.** No `fetch`, `process`, filesystem, timers, or host globals - only the allowlisted standard
+  library and the `tools` tree.
+- **No dynamic code.** No `eval`, `Function`, or module loading.
+- **Plain-data boundaries.** Tool arguments and program results are JSON-like data. Dates become ISO strings, RegExp,
+  Map, and Set serialize as `{}`, and promises, functions, and runtime references cannot cross the boundary.
+- **Eager, supervised promises.** Tool calls and async functions start immediately when called. Whatever is still
+  running when the program returns is interrupted - race losers and fire-and-forget calls alike - so a program must
+  await every call whose completion matters. Rejections that settle un-awaited become `warnings` on the result instead
+  of crashing the run.
+- **REPL-style results.** An omitted `return` yields the final top-level expression; `undefined` normalizes to `null`.
 
-## Install
-
-Within this workspace:
-
-```json
-{
-  "dependencies": {
-    "@opencode-ai/codemode": "workspace:*"
-  }
-}
-```
-
-Hosts interact with CodeMode through `effect` (tool `run` implementations, `Effect`-typed results), so they should depend on `effect` themselves.
+Beyond these, the language is a growing subset rather than a divergent one: unsupported syntax returns an
+`UnsupportedSyntax` diagnostic with a source location, and current gaps (for example thenable assimilation, classes,
+generators, and full sparse-array parity) are tracked as unchecked items in the
+[interpreter support checklist](./interpreter-support.md).
 
 ## Quick Start
 
-Define tools with Effect Schema, then place them in the object tree exposed to programs as `tools`:
+The package is workspace-private (`"@opencode-ai/codemode": "workspace:*"`). Hosts interact with it through `effect`
+and should depend on `effect` themselves. Define tools with Effect Schema, then place them in the object tree exposed
+to programs as `tools`:
 
 ```ts
 import { CodeMode, Tool } from "@opencode-ai/codemode"
@@ -60,69 +63,53 @@ const result =
 `)
 ```
 
-`result` is always a `CodeMode.Result`. Program, validation, limit, and tool failures are returned as diagnostics rather than failing the Effect. Host interruption remains interruption.
-
-Successful result values are JSON-safe data. An explicit `return` produces the program result; when it is omitted, the final executable top-level expression is returned as a model-friendly REPL convenience. Otherwise reaching the end produces `null`. Returned `undefined` and nested `undefined` values are normalized to `null` as well.
+`result` is always a `CodeMode.Result`. Program, validation, limit, and tool failures are returned as diagnostics
+rather than failing the Effect; host interruption remains interruption.
 
 ## API
 
 ### `Tool.make`
 
-```ts
-const tool = Tool.make({
-  description,
-  input, // Effect Schema (validating) or JSON Schema (render-only)
-  output, // optional; same choice
-  run,
-})
-```
+`input` and `output` each accept a validating Effect Schema or a render-only JSON Schema document. Effect Schema input
+is decoded before `run` is invoked; an Effect Schema `output` is decoded and copied before the program sees it. JSON
+Schemas only shape the model-visible signature. Without `output` the signature advertises `Promise<unknown>`.
+Descriptions and schemas are model-visible contract; keep authorization in `run`.
 
-`input` and `output` each accept a validating Effect Schema or a render-only JSON Schema document (the natural shape for adapter-provided tools whose schemas arrive as JSON Schema, e.g. MCP definitions). Effect Schema input is decoded before `run` is invoked, and `run` returns the encoded representation of an Effect Schema `output`, which CodeMode decodes and copies before exposing it to the program. JSON Schemas only shape the model-visible signature; values pass through unvalidated (they still cross the plain-data boundary).
+### `CodeMode.execute` and `CodeMode.make`
 
-`output` is optional. Without it the tool's signature advertises `Promise<unknown>` and the host result is exposed as-is.
-
-The description and schemas are part of the model-visible tool contract. Keep descriptions concrete and put authorization in `run` or in the service it calls.
-
-Public tool types are grouped under the same namespace: `Tool.Definition`, `Tool.Options`, `Tool.SchemaType`, and `Tool.JsonSchema`.
-
-### `CodeMode.execute`
-
-Use `CodeMode.execute` for a single execution:
+`CodeMode.execute({ ...options, code })` runs once and is equivalent to `CodeMode.make(options).execute(code)`. A
+runtime from `make` reuses the tool set and policy:
 
 ```ts
-const result =
-  yield *
-  CodeMode.execute({
-    tools: { orders: { lookup: lookupOrder } },
-    code: `return await tools.orders.lookup({ id: "order_42" })`,
-    limits: { maxToolCalls: 10 },
-    onToolCallStart: (call) => Effect.logDebug("CodeMode tool started", call),
-    onToolCallEnd: (call) => Effect.logDebug("CodeMode tool settled", call),
-  })
-```
-
-The Effect environment is inferred from the supplied tools. CodeMode does not erase service requirements introduced by tool implementations.
-
-### `CodeMode.make`
-
-Use `CodeMode.make` when the tool set and execution policy are reused:
-
-```ts
-const runtime = CodeMode.make({
-  tools: { orders: { lookup: lookupOrder } },
-  limits: { timeoutMs: 30_000 },
-})
+const runtime = CodeMode.make({ tools, limits: { timeoutMs: 30_000 } })
 
 runtime.catalog() // structured tool descriptions
 runtime.instructions() // model-facing syntax and tool guide
 runtime.execute(source) // CodeMode.Result
 ```
 
-`CodeMode.Input`, `CodeMode.Result`, `CodeMode.Success`, `CodeMode.Failure`, `CodeMode.Diagnostic`, and `CodeMode.DiagnosticKind` are both Effect schemas and their inferred TypeScript types. Hosts can combine `CodeMode.Input` and `CodeMode.Result` with `runtime.instructions()` and `runtime.execute()` when constructing a framework-specific agent tool.
+The Effect environment is inferred from the supplied tools; service requirements are not erased. Optional
+`onToolCallStart` / `onToolCallEnd` hooks observe admitted calls with decoded input, outcome, and duration; both are
+Effect-returning and must not fail.
 
-All other CodeMode types use the same namespace: `CodeMode.Options`, `CodeMode.ExecuteOptions`, `CodeMode.Runtime`, `CodeMode.ExecutionLimits`, `CodeMode.DiscoveryOptions`, `CodeMode.DataValue`, `CodeMode.ToolDescription`, and the `CodeMode.ToolCall*` observation types.
+### OpenAPI tools
 
-### Results
+`OpenAPI.fromSpec` turns an OpenAPI 3.x document into a tool subtree - one tool per operation, namespaced by dotted
+`operationId`:
+
+```ts
+const api = OpenAPI.fromSpec({ spec, auth: { resolve } })
+const runtime = CodeMode.make({ tools: { opencode: api.tools } })
+```
+
+It is synchronous and returns `{ tools, skipped }`: operations with unsupported encodings, non-JSON bodies, binary
+responses, or streaming land in `skipped` instead of producing broken tools. Auth is resolved host-side and never
+model-visible; generated tools require `HttpClient.HttpClient` in the environment. See the option docstrings in
+`src/openapi/types.ts` for full semantics.
+
+## Outputs
+
+Every execution returns a `CodeMode.Result`:
 
 ```ts
 type Result = Success | Failure
@@ -130,6 +117,7 @@ type Result = Success | Failure
 interface Success {
   readonly ok: true
   readonly value: CodeMode.DataValue
+  readonly warnings?: ReadonlyArray<CodeMode.Diagnostic>
   readonly logs?: ReadonlyArray<string>
   readonly truncated?: boolean
   readonly toolCalls: ReadonlyArray<CodeMode.ToolCall>
@@ -144,216 +132,65 @@ interface Failure {
 }
 ```
 
-`toolCalls` contains the names of calls admitted by the runtime in call order. It is retained on failure so hosts can audit partial execution without exposing inputs or host failures. `truncated` is present when the value or logs were cut to fit `maxOutputBytes` (see Execution Limits).
+`value` is JSON-safe data. `warnings` are non-fatal diagnostics alongside a valid value (un-awaited rejections,
+timeout cleanup after the return). `logs` holds program console output, `truncated` marks any output-budget cut, and
+`toolCalls` lists admitted calls in order - retained on failure for auditing.
 
-### Tool-call hooks
+Failure `error` and success `warnings` share one diagnostic vocabulary:
 
-`onToolCallStart` receives `{ index, name, input }` after input decoding and before tool execution. The input is decoded host-side data and may include values produced by schema transformations; applications should avoid logging sensitive tool arguments indiscriminately.
+| Kind                    | Meaning                                                                                                   |
+| ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `ParseError`            | Source is empty or cannot be parsed.                                                                      |
+| `UnsupportedSyntax`     | Parsed JavaScript is outside the supported subset.                                                        |
+| `UnknownTool`           | A program referenced a tool the host did not provide.                                                     |
+| `InvalidToolInput`      | Tool input failed schema decoding or safe-data copying.                                                   |
+| `InvalidToolOutput`     | Tool output failed schema decoding or safe-data copying.                                                  |
+| `InvalidDataValue`      | Program data violated the plain-data contract (depth, circularity, blocked properties, non-data values).  |
+| `ToolCallLimitExceeded` | Calls exceeded `maxToolCalls`.                                                                            |
+| `TimeoutExceeded`       | Execution exceeded `timeoutMs`; as a warning, background work was interrupted after the program returned. |
+| `ToolFailure`           | A tool refused or failed.                                                                                 |
+| `ExecutionFailure`      | The program threw or another execution error occurred.                                                    |
+| `Truncated`             | Warning-only marker: additional warnings were omitted by `maxOutputBytes`.                                |
 
-`onToolCallEnd` receives `{ index, name, input, durationMs, outcome, message? }` when an admitted call settles. `outcome` is `"success"` or `"failure"`; `message` is the model-safe failure message and is present only on failure. Interrupted calls (for example when the execution timeout fires) do not produce an end event. Both hooks are Effect-returning and must not fail.
-
-### OpenAPI tools
-
-`OpenAPI.fromSpec` turns an OpenAPI 3.x document into a tool subtree - one tool per operation. Dotted `operationId` values form namespaces such as `v2.session.get`. Missing IDs receive a flat method/path fallback such as `getUsersById`; names are sanitized and deduplicated. The host places the subtree under a key in its `tools` tree; that key is the model-visible namespace.
-
-```ts
-import { CodeMode, OpenAPI } from "@opencode-ai/codemode"
-import { Effect } from "effect"
-import { FetchHttpClient } from "effect/unstable/http"
-
-const api = OpenAPI.fromSpec({
-  spec: await Bun.file("openapi.json").json(), // parsed document (no YAML)
-  auth: {
-    resolve: ({ name, scopes, operation }) =>
-      name === "BearerAuth" ? Effect.succeed({ type: "bearer", token }) : Effect.succeed(undefined),
-  },
-})
-
-const runtime = CodeMode.make({ tools: { opencode: api.tools } })
-const result = await Effect.runPromise(runtime.execute(code).pipe(Effect.provide(FetchHttpClient.layer)))
-```
-
-`fromSpec` is synchronous and returns `{ tools, skipped }`. The initial adapter supports query `form`/`deepObject`, path/header `simple`, JSON request bodies, JSON responses, and text responses; unsupported parameter encodings, non-JSON request bodies, binary responses, and streaming operations land in `skipped` instead of producing broken tools. Operation and path servers take precedence over document servers unless `baseUrl` explicitly overrides all of them. Tool inputs flatten path, query, header, and closed object-body fields into one model-facing object while retaining their HTTP locations internally. Cross-location name collisions receive a location prefix such as `path_id` and `query_id`; composed, nullable, dictionary, conditionally-required, and non-object JSON bodies remain under `body`. Auth is never model-visible. Responses are limited to 50 MiB, and non-2xx responses become safe tool failures carrying the status and a size-capped body summary. Deferred capabilities are tracked in `src/openapi/TODO.md`.
-
-Supported bearer, basic, header, and query authentication follows OpenAPI `security` semantics and is resolved host-side via `auth.resolve` - credential storage, OAuth flows, and token refresh never enter the compiler. Cookie authentication alternatives are discarded; an operation is skipped when it has no supported alternative. See the option docstrings in `src/openapi/types.ts` for the full semantics. Generated tools require `HttpClient.HttpClient` (from `effect/unstable/http`) in the Effect environment - provide `FetchHttpClient.layer` or a custom/test client layer at execution. The supplied client owns redirect policy; credentialed hosts should reject redirects or strip credentials when the origin changes.
+Unknown host failures, defects, and invalid outputs are sanitized. `toolError("safe message")` is the explicit channel
+for a model-visible refusal; its optional cause never crosses the boundary.
 
 ## Discovery
 
-The agent-tool instructions use a budgeted catalog. Every tool namespace is always listed with its tool count regardless of budget, and as many complete, JSDoc-annotated tool signatures (each with a one-line description) as fit an estimated-token budget are inlined. Schema field descriptions and tags are part of each signature's measured cost. Selection is round-robin across namespaces for fairness: in each round (namespaces alphabetical), every namespace still holding un-inlined tools attempts to place its next-cheapest signature against the shared budget, and a namespace whose next signature does not fit drops out while the others keep going - so every namespace gets some representation before any namespace gets everything. The instructions state exactly how comprehensive the list is, both overall (`COMPLETE list` vs `PARTIAL - N of M shown`) and per namespace (`(3 tools)`, `(3 tools, 1 shown)`, `(3 tools, none shown)`).
-
-The catalog-entry budget defaults to 2,000 estimated tokens (characters / 4, the same heuristic OpenCode uses). It applies only to full tool entries shown in the catalog; fixed instructions and namespace summaries are not counted. Override it when constructing a runtime:
-
-```ts
-const runtime = CodeMode.make({
-  tools,
-  discovery: { catalogBudget: 6_000 },
-})
-```
-
-The budget must be a non-negative safe integer.
-
-The runtime search tool is always registered - including when the catalog is fully inlined - so a speculative `tools.$codemode.search` call never fails as an unknown tool. It is only advertised in the instructions when the inlined list is partial:
-
-```ts
-const matches = await tools.$codemode.search({
-  query: "order status",
-  namespace: "orders", // optional: scope to one top-level namespace
-  limit: 10,
-  offset: 0,
-})
-```
-
-`search` performs deterministic, additive field-weighted matching. The query is tokenized (camelCase boundaries split; every non-alphanumeric character is a separator; empties and `*` are dropped), and each term scores every tool: exact path or path-segment match (20), path substring (8), description substring (4), and searchable-text substring (2). Each term also carries naive singular variants (trailing `s`/`es` stripped), and a field check passes when the term or any variant matches - so a plural query term (`issues`) still finds a tool whose text only says `issue`, without changing the weights. The searchable text also includes the input schema's property names and their description strings, so a query naming a parameter finds its tool, and substring matching means partial words match. Scores sum across terms; matches are sorted by score (ties broken alphabetically by path), then sliced from the zero-based `offset` (default 0) to the configured `limit` (default 10). `remaining` counts matches after the current page. `next` is `{ offset }` when another page exists and `null` on the final page; spread it into the original request to preserve its query, namespace, and limit.
-
-```ts
-const request = { query: "order status", namespace: "orders", limit: 10 }
-const page = await tools.$codemode.search(request)
-const nextPage = page.next ? await tools.$codemode.search({ ...request, ...page.next }) : undefined
-```
-
-Each result contains the path, description, and the same generated TypeScript signature used by the inline catalog, so no second lookup is needed. Signatures use the JSDoc-annotated multiline form: each described input/output field carries its schema `description` as a `/** ... */` comment, and constraints TypeScript cannot express ride along as tags (`@deprecated`, `@default`, `@format`, `@minItems`, `@maxItems`).
-
-```ts
-tools.github.list_issues(input: {
-  /** Repository owner */
-  owner: string,
-  /** Cursor from the previous response's pageInfo */
-  after?: string,
-  /**
-   * Results per page
-   * @default 30
-   */
-  perPage?: number,
-}): Promise<unknown>
-```
-
-Result paths are rendered as JavaScript expressions rooted at `tools` (`tools.orders.lookup`, or `tools.context7["resolve-library-id"]` for non-identifier segments), so each `path` is directly usable as the call site. An empty query browses the catalog alphabetically by path; combined with `namespace` (`{ query: "", namespace: "orders" }`) it lists everything in that namespace. A query that names one tool path exactly (canonical path, `tools.`-prefixed path, or rendered JavaScript expression) is treated as a lookup and returns that tool alone.
-
-The instructions are structured markdown, ordered so the workflow sits at the top and the catalog at the bottom: a `## Workflow` section with numbered steps (find a tool via search when the catalog is partial, or pick from the inlined list when it is complete; call the exact path as-is; return only the needed fields), a `## Rules` section holding only guidance the workflow does not already cover (only listed/search-result Code Mode tools and internal runtime tools exist inside `tools`; filter and aggregate collections in code; narrow `Promise<unknown>` results at runtime; run independent calls through `Promise.all`; enumerate `tools` with `Object.keys`/`for...in`; browse a namespace and paginate search results when search is advertised), a short `## Language` section that identifies the runtime as a restricted JavaScript orchestration language and names its major unavailable capabilities, and the budgeted `## Available tools` catalog. Example call forms use explicit `<namespace>.<tool>`/`<field>` placeholders - never a real or fabricated tool name.
-
-A host cannot define its own `$codemode` top-level namespace.
-
-## Supported Programs
-
-CodeMode executes a deliberately bounded JavaScript subset. See the
-[interpreter support checklist](./interpreter-support.md) for the complete, checkable language and standard-library
-matrix, known semantic gaps, and intentional exclusions.
-
-At a high level, it supports:
-
-- Plain data, property access and assignment, destructuring, functions, conditionals, loops, spread, optional chaining,
-  and structured error handling.
-- Allowlisted Array, String, Number, Object, Math, JSON, console, Date, RegExp, Map, Set, URL, and URLSearchParams APIs.
-- Eager supervised tool promises, direct `await`, and the supported `Promise` combinators for concurrent work.
-- Live standard-library values inside the sandbox and predictable JSON-like serialization at tool/result boundaries.
-- Actionable diagnostics for unsupported syntax, invalid data, tool failures, limits, and execution failures.
-
-It does not expose ambient host authority or arbitrary JavaScript execution. Unsupported syntax returns an
-`UnsupportedSyntax` diagnostic with a source location when available.
-
-CodeMode is an orchestration language, not a general JavaScript runtime.
+The generated instructions inline a budgeted catalog (default 2,000 estimated tokens, override with
+`discovery: { catalogBudget }`): every namespace is always listed with its tool count, signatures are selected
+round-robin so every namespace gets representation, and the instructions state whether the list is complete or
+partial. Programs also get a global `search(...)` built-in - always available, advertised when the list is partial:
+synchronous, deterministic field-weighted substring matching that returns directly callable paths with full
+signatures, supports namespace scoping and pagination, and treats an empty query as browsing and an exact path as
+lookup. Search counts as an admitted tool call.
 
 ## Execution Limits
 
-The limits are exactly three knobs:
+| Limit            |              Default | Bounds                                               |
+| ---------------- | -------------------: | ---------------------------------------------------- |
+| `timeoutMs`      |    none - no timeout | Wall-clock execution time.                           |
+| `maxToolCalls`   |     none - unlimited | Tool calls admitted during the execution.            |
+| `maxOutputBytes` | none - no truncation | Retained result value and logs; warnings separately. |
 
-| Limit            |              Default | Bounds                                                               |
-| ---------------- | -------------------: | -------------------------------------------------------------------- |
-| `timeoutMs`      |    none - no timeout | Wall-clock execution time.                                           |
-| `maxToolCalls`   |     none - unlimited | Tool calls admitted during the execution.                            |
-| `maxOutputBytes` | none - no truncation | Model-facing output: the serialized result value plus captured logs. |
+No limit has a default, on purpose: execution budgets are host policy. A host without its own truncation or
+interruption should set `maxOutputBytes` and `timeoutMs`. Limits are safe integers; invalid configuration throws a
+`RangeError` at construction. Exceeding `maxOutputBytes` never fails the execution - oversized output is truncated
+with an in-band marker. The timeout interrupts in-flight tool fibers and pure busy loops alike; a value the program
+already returned survives a cleanup timeout as a success with a `TimeoutExceeded` warning. CodeMode does not limit
+tool-call concurrency. Data nesting at boundaries is limited to 32 levels.
 
-No limit has a default, on purpose: execution budgets are host policy, not library policy - a host that wants a bound sets one; a host that can interrupt the execution fiber (as OpenCode does on user cancel) may set no timeout, and a host with its own tool-output truncation (as OpenCode has) may leave `maxOutputBytes` unset. A host with neither should set `maxOutputBytes`, or oversized results silently flood model context.
+## Boundaries and Non-Goals
 
-Pass only the overrides you need:
+The host owns authentication, authorization, tool selection, credentials, persistence, approval, and logging policy.
+CodeMode owns interpretation, schema and plain-data boundaries, resource limits, diagnostics, and discovery. A program
+can only exercise authority already present in the supplied tools - do not expose a broad tool and expect the prompt
+to restrict it.
 
-```ts
-const runtime = CodeMode.make({
-  tools,
-  limits: {
-    maxToolCalls: 20,
-    timeoutMs: 60_000,
-  },
-})
-```
-
-Limits are safe integers. `timeoutMs` must be at least `1`; the others may be `0`. Invalid configuration throws a `RangeError` when `CodeMode.make` or `CodeMode.execute` is called. An explicitly `undefined` value is the same as leaving the limit unset.
-
-Exceeding a configured `maxOutputBytes` never fails the execution. An oversized result value is replaced by its truncated serialized text plus an explanatory marker, logs are kept from the start until the remaining budget is exhausted (with a final marker line noting the cut), and the result carries `truncated: true`.
-
-When configured, the timeout interrupts in-flight tool Effects, including eagerly started calls the program has not awaited (their fibers are supervised by the execution). The interpreter yields cooperatively between steps, so the timeout also interrupts pure busy loops (`while (true) {}`) - no separate work budget exists. Tool implementations remain responsible for making their external operations interruptible or independently bounded.
-
-Two interpreter internals are fixed constants rather than knobs: at most 8 tool calls run concurrently, and values crossing a data boundary may nest at most 32 levels deep (deeper values fail as `InvalidDataValue`, which reads better than a native stack-overflow error). Neither is part of the public contract.
-
-## Diagnostics
-
-Failures are data:
-
-| Kind                    | Meaning                                                                                                  |
-| ----------------------- | -------------------------------------------------------------------------------------------------------- |
-| `ParseError`            | Source is empty or cannot be parsed.                                                                     |
-| `UnsupportedSyntax`     | Parsed JavaScript is outside the supported subset.                                                       |
-| `UnknownTool`           | A program referenced a tool the host did not provide.                                                    |
-| `InvalidToolInput`      | Tool input failed schema decoding or safe-data copying.                                                  |
-| `InvalidToolOutput`     | Tool output failed schema decoding or safe-data copying.                                                 |
-| `InvalidDataValue`      | Program data violated the plain-data contract (depth, circularity, blocked properties, non-data values). |
-| `ToolCallLimitExceeded` | Calls exceeded `maxToolCalls`.                                                                           |
-| `TimeoutExceeded`       | Execution exceeded `timeoutMs`.                                                                          |
-| `ToolFailure`           | A tool refused or failed.                                                                                |
-| `ExecutionFailure`      | The program threw or another execution error occurred.                                                   |
-
-Unknown host failures, defects, invalid outputs, and copying failures are sanitized. To return a safe operational refusal, fail with `toolError`:
-
-```ts
-import { toolError } from "@opencode-ai/codemode"
-
-run: ({ id }) => (authorized(id) ? loadOrder(id) : Effect.fail(toolError("Order is unavailable")))
-```
-
-Only the supplied message is model-visible. The optional cause is never returned in `CodeMode.Result`; hosts should perform any required internal logging before crossing this boundary.
-
-## Authority Boundary
-
-CodeMode confines programs to the supplied tool tree, but it does not decide what those tools may do.
-
-The host owns:
-
-- Authentication and authorization.
-- Tool selection and immutable scope.
-- Credentials and network clients.
-- Persistence, idempotency, approval, and durable side effects.
-- Logging and redaction policy.
-
-CodeMode owns:
-
-- Parsing and interpreting the supported subset without `eval`.
-- Schema boundaries around tool calls.
-- Plain-data copying and blocked prototype members.
-- Resource limits, call accounting, and normalized diagnostics.
-- Model-facing tool discovery and instructions.
-
-A program cannot gain authority through prose or generated code. It can only exercise authority already present in the supplied tools. Do not expose a broad tool and expect the prompt to restrict it.
-
-## Laws
-
-The public contract is guided by these equivalences:
-
-- `CodeMode.execute({ ...options, code })` is equivalent to `CodeMode.make(options).execute(code)`.
-- A tool implementation is not invoked unless its input has decoded successfully.
-- A tool result is not visible to the program unless its output has decoded and crossed the plain-data boundary successfully.
-- Unknown host failures do not become model-visible diagnostics; `ToolError` is the explicit safe-message channel.
-- Host interruption remains interruption rather than a `CodeMode.Failure`.
-
-## Non-Goals
-
-- Generic permission prompts or approval workflows.
-- Durable pause/resume, replay, or storage adapters.
-- Exactly-once external side effects.
-- Application authorization or product policy.
-- A filesystem or process sandbox for arbitrary JavaScript.
-- Compatibility with the full JavaScript language or npm ecosystem.
-
-Applications that need approval or durable consequences should model those above CodeMode and expose only the currently authorized tools.
+Non-goals: permission prompts and approval workflows, durable pause/resume or replay, exactly-once side effects,
+application authorization policy, sandboxing arbitrary JavaScript, and compatibility with the full language or npm
+ecosystem. Applications that need approval or durable consequences should model those above CodeMode and expose only
+the currently authorized tools.
 
 ## Testing
 
@@ -363,5 +200,3 @@ From the package directory:
 bun test
 bun run typecheck
 ```
-
-The direct suite covers public projections, discovery, schema boundaries, diagnostic sanitization, resource limits, tool-call observation, and interruption.

packages/codemode/codemode.md

@@ -1,145 +0,0 @@
-# CodeMode Design and Status
-
-This is the living design and status document for `@opencode-ai/codemode` and its existing V2 OpenCode adapter.
-It records current behavior, intentional boundaries, durable rationale, and material remaining work.
-
-Completed implementation history, branch names, test counts, and closed findings belong in git, not here. Remove
-completed work instead of preserving checked-off chronology.
-
-Detailed package API documentation lives in [README.md](./README.md), and the checkable language/runtime matrix lives
-in [interpreter-support.md](./interpreter-support.md). OpenAPI-specific follow-ups live in
-[src/openapi/TODO.md](./src/openapi/TODO.md).
-
-## How CodeMode Works
-
-### Purpose
-
-CodeMode gives a model one `execute` tool backed by a confined JavaScript interpreter. Inside the program, the model
-can call an explicit tree of schema-described tools, sequence dependent work, run independent calls concurrently,
-and filter or aggregate results before returning them to the agent loop.
-
-The goals are:
-
-- Reduce model context consumed by large tool catalogs.
-- Avoid an agent round-trip between every dependent tool call.
-- Keep large intermediate results inside the program instead of sending them through model context.
-- Give generated code only the authority explicitly supplied by the host.
-
-CodeMode is an orchestration language, not a general JavaScript runtime or an application authorization system.
-
-### Runtime
-
-The generic runtime lives in `packages/codemode` and is host-neutral:
-
-1. The host builds a tree of `Tool.make(...)` definitions and calls `CodeMode.make(...)` or `CodeMode.execute(...)`.
-2. CodeMode generates model instructions, a budgeted inline catalog, and the internal `$codemode.search` tool.
-3. TypeScript syntax is transpiled away, Acorn parses the resulting JavaScript, and an owned tree-walking interpreter
-   executes it without `eval`.
-4. Tool inputs and outputs cross schema and plain-data boundaries before they become visible on either side.
-5. Execution returns `CodeMode.Result`. Expected program and tool failures are diagnostic data; host interruption
-   remains Effect interruption.
-
-Effect Schemas validate and transform tool inputs and outputs. JSON Schemas render model-facing signatures but do not
-validate values; adapter-provided values still cross the plain-data boundary. A tool without an output schema is
-advertised as `Promise<unknown>`.
-
-### Discovery and model workflow
-
-The model sees a token-budgeted catalog. Every namespace remains visible, and complete signatures are selected
-round-robin across namespaces so one large namespace cannot starve the others. `$codemode.search` is always callable
-and is advertised when the inline catalog is partial.
-
-The intended workflow is:
-
-1. Pick an exact signature from the inline catalog, or return `$codemode.search(...)` results and use a selected path
-   in the next execution.
-2. Call the exact returned path without guessing or normalizing segments.
-3. Narrow `Promise<unknown>` results before reading fields.
-4. Start independent calls together and await them with `Promise.all`.
-5. Filter and aggregate inside the program, then return only the data needed by the model.
-
-Search returns directly usable JavaScript paths, descriptions, and complete TypeScript signatures. It supports exact
-path lookup, namespace browsing, deterministic ranking, and pagination.
-
-### Tool execution
-
-Calling a tool starts its Effect eagerly on a supervised fiber. The returned sandbox promise is run-once and can be
-awaited directly or through the supported `Promise` combinators. At most eight tool calls execute concurrently.
-Unfinished calls are drained before successful program completion, and an unhandled call failure becomes a diagnostic.
-
-The public execution-policy knobs are `timeoutMs`, `maxToolCalls`, and `maxOutputBytes`. The package supplies no
-defaults because budgets are host policy. The interpreter also enforces fixed internal boundaries for tool-call
-concurrency and data nesting depth.
-
-### Data, files, and failures
-
-Program results and tool arguments are JSON-like data. Dates become ISO strings at host boundaries; RegExp, Map, and
-Set values become `{}` as they do under JSON serialization. Promise and runtime reference values cannot cross the
-boundary.
-
-Unknown host failures and invalid outputs are sanitized. `ToolError` is the explicit channel for a safe message that a
-tool wants the model to see. Diagnostic categories distinguish parsing, unsupported syntax, unknown tools, invalid
-data, tool failures, limits, timeouts, and execution failures.
-
-Files and other attachment content stay outside the interpreter. A host may collect them while child tools execute and
-attach them to the outer result, but the program receives only the structured tool output.
-
-### V2 OpenCode adapter
-
-CodeMode is integrated into V2 through `packages/core/src/tool/registry.ts` and
-`packages/core/src/tool/execute.ts`:
-
-- Core has one canonical `Tool` representation. Location-scoped producers register direct or deferred tools through
-  `Tools.Service`.
-- Each model step snapshots effective registrations, applies catalog visibility filtering, and exposes direct tools
-  normally.
-- When visible deferred tools exist, Core reserves and materializes one `execute` tool. Grouped deferred tools become
-  CodeMode namespaces instead of flattened model-facing names.
-- Each nested call checks that its captured registration is still current before dispatching it.
-- Authorization and side-effect ordering remain responsibilities of the leaf tool. Catalog visibility is not execution
-  authorization.
-- Structured child output enters the interpreter. File parts are collected host-side and attached to the outer result.
-- Nested call statuses are returned as final `execute` metadata for the TUI.
-- `execute` is the one model-facing tool invocation. Nested calls reuse its invocation context and do not independently
-  run registry hooks or model-output bounding; this keeps complete intermediate structured values available for
-  in-program filtering. The outer `execute` settlement is the single model-output bounding boundary.
-- Core supplies no CodeMode timeout or tool-call limit. User cancellation interrupts the outer invocation and its
-  supervised children; the outer settlement applies Core's normal output-retention policy.
-
-MCP tools use this canonical path: they register as grouped tools and are deferred while CodeMode is enabled. Existing
-output schemas are preserved in generated signatures. Direct Core tools remain direct and are not ambient globals
-inside CodeMode.
-
-## Intentionally Unsupported
-
-These are product boundaries rather than DSL backlog:
-
-- Ambient filesystem, process, environment, network, credential, or application access. External work must go through
-  supplied tools.
-- Modules, imports, dynamic imports, `eval`, arbitrary host globals, npm packages, and prototype mutation.
-- Generic permission prompts, authorization policy, durable pause/resume, replay, storage, or exactly-once external
-  side effects. Hosts and tools own those concerns.
-- Heuristic parsing of text tool results as JSON. A result should not silently change type based on its contents.
-
-The OpenAPI adapter may gain more transports and encodings, but it must continue skipping operations it cannot
-represent accurately rather than guessing semantics.
-
-## Decisions and Rationale
-
-| Decision | Rationale |
-| --- | --- |
-| Keep an owned tree-walking interpreter. | The product need is bounded tool orchestration, not arbitrary JavaScript. Owning the language surface keeps authority and behavior explicit. |
-| Treat schemas as the model-facing interface. | Signatures drive correct calls; Effect Schema also provides the runtime validation boundary, while JSON Schema supports adapter interoperability. |
-| Keep authority host-owned. | CodeMode can only confine programs to supplied tools. The host chooses those tools, and each tool enforces its own authorization and side-effect policy. |
-| Use progressive catalog disclosure plus search. | Large tool sets should not consume the prompt, but every namespace must remain discoverable and speculative search calls should remain valid. |
-| Start tool promises eagerly and supervise them. | This preserves normal call-time parallelism while giving each call run-once settlement and interruption safety. |
-| Keep files outside the sandbox value space. | Models should compose structured data without routing binary payloads through generated code or context. |
-| Treat `execute` as the model-facing invocation boundary. | Nested calls are implementation details of one orchestration program. Reusing the outer context and bounding only the final result preserves complete intermediate data without inventing durable child-call identities. |
-| Return expected failures as data. | Models need actionable diagnostics without exposing private host causes; host interruption and defects must still propagate correctly. |
-| Leave execution-limit defaults to hosts. | Appropriate budgets depend on the surrounding product and its own cancellation, retention, and output-bounding policies. |
-| Skip unsupported OpenAPI operations. | Incorrect parameter encoding, authentication, or transport behavior is worse than a precise `skipped` reason. |
-
-## Remaining Work
-
-The [interpreter support checklist](./interpreter-support.md) owns concrete DSL, standard-library, semantic-correctness,
-diagnostic, and data-boundary work. OpenAPI adapter work remains in [src/openapi/TODO.md](./src/openapi/TODO.md).

packages/codemode/interpreter-support.md

@@ -22,7 +22,9 @@ ultimate source of truth.
 - [x] JSON-like host boundaries with `undefined` and non-finite numbers normalized to `null`.
 - [x] Live Date, RegExp, Map, Set, URL, and URLSearchParams values inside the sandbox.
 - [x] Tool calls through the host-provided `tools` tree only.
-- [x] Cooperative timeout, tool-call accounting, output bounding, and a maximum of eight concurrent tool calls.
+- [x] The global `search(...)` built-in: synchronous tool discovery that counts as an admitted tool call and is
+      shadowable by program declarations like other globals.
+- [x] Cooperative timeout, an optional total tool-call limit, output bounding, and unrestricted tool-call concurrency.
 - [ ] Full JavaScript or TypeScript compatibility. CodeMode is a bounded orchestration language.
 
 ## Values and literals
@@ -92,8 +94,9 @@ ultimate source of truth.
 - [x] Optional property access and optional calls.
 - [x] Function/tool calls and spread arguments.
 - [x] Sequence expressions (the comma operator).
-- [x] `await` for sandbox promises; awaiting a plain value is a no-op.
-- [x] `new` for Error types, Date, RegExp, Map, Set, URL, and URLSearchParams.
+- [x] `await` for sandbox promises; a plain value passes through unchanged, though every `await` still defers its
+      continuation one reaction turn.
+- [x] `new` for Error types, Date, RegExp, Map, Set, URL, URLSearchParams, and Promise.
 - [x] Arithmetic operators: `+`, `-`, `*`, `/`, `%`, and `**`.
 - [x] Equality and ordering: `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, and `>=`.
 - [x] Bitwise operators: `&`, `|`, `^`, `~`, `<<`, `>>`, and `>>>`.
@@ -102,25 +105,41 @@ ultimate source of truth.
 - [x] Prefix and postfix `++` and `--`.
 - [x] Plain, arithmetic, bitwise, and logical assignment operators.
 - [ ] Unary `void` and `delete`.
-- [ ] Arbitrary constructors and `new Promise(...)`.
+- [ ] Arbitrary constructors.
 
 ## Promises and tools
 
 - [x] Tool calls start eagerly and return supervised, run-once sandbox promises.
 - [x] Direct `await`, repeated awaits, and implicit resolution when a promise is returned from a function/program.
 - [x] `Promise.resolve` and `Promise.reject`.
-- [x] `Promise.all`, `Promise.allSettled`, and `Promise.race` over supported collections containing promises and plain
-      values.
-- [x] `Promise.all` preserves result order and rejects on the first observed failure.
+- [x] `Promise.all`, `Promise.allSettled`, `Promise.race`, and `Promise.any` over supported collections containing
+      promises and plain values.
+- [x] `Promise.all` preserves result order and rejects on the first observed failure without cancelling siblings.
 - [x] `Promise.allSettled` returns plain fulfilled/rejected outcome records.
-- [x] `Promise.race` interrupts losing in-flight tool calls.
-- [x] Un-awaited calls are drained before execution ends; unhandled failures become diagnostics.
+- [x] `Promise.race` settles from the first result without cancelling losers at settlement time.
+- [x] Real promise values from `Promise.all`, `Promise.allSettled`, and `Promise.race`; separately constructed
+      combinator batches overlap as in normal JavaScript.
+- [x] Promise chaining with `.then`, `.catch`, and `.finally`: handlers run deferred in attach order, returned
+      promises are adopted, handler throws reject the derived promise, `.finally` preserves the original settlement
+      unless its cleanup fails, and direct self-resolution rejects with a `TypeError`.
+- [x] Every `await` (including of plain values and already-settled promises) defers its continuation one reaction
+      turn, so concurrent async functions interleave at await points as in JavaScript.
+- [x] Combinators settle one reaction turn after their deciding member (V8-observable ordering): reactions already
+      attached to members run first, and an aggregate cannot beat a plain value settling in the same turn into a
+      `Promise.race`. Exact microtask-count parity beyond this observable ordering is not a documented guarantee.
+- [x] All still-pending work (race losers, fail-fast `Promise.all` stragglers, and un-awaited calls alike) is
+      interrupted when the program returns; rejections that settled un-awaited become `Success.warnings`
+      diagnostics. A combinator abandoned inside its final settlement turn counts as pending and is interrupted
+      without a warning.
 - [x] `try`/`catch` can handle awaited tool and promise failures.
-- [ ] Real promise values from `Promise.all`, `Promise.allSettled`, and `Promise.race`. These calls currently settle
-      before returning, so separately constructed combinator batches do not overlap as normal JavaScript promises do.
-- [ ] `Promise.any`.
-- [ ] Promise chaining with `.then`, `.catch`, and `.finally`.
-- [ ] Custom promise construction with `new Promise(...)`.
+- [x] `Promise.any`: first fulfillment wins; all-rejected rejects with an `AggregateError` whose `errors` array holds
+      the catch-normalized reasons in input order, and empty input rejects with an empty `AggregateError`.
+- [x] `new Promise((resolve, reject) => ...)`: the executor runs synchronously and receives first-class resolve/reject
+      callables that settle the promise exactly once (they may escape the executor and settle later); an executor
+      throw rejects unless the promise already settled, resolving with a promise adopts it, and resolving with the
+      promise itself rejects with a `TypeError`. Resolver callables work as `.then`/`.catch` handlers and collection
+      callbacks but remain opaque references that cannot cross the data boundary.
+- [ ] Thenable assimilation (objects with a `then` method are plain data, not promises).
 - [ ] Async iterables, host streams, and stream consumption.
 
 ## Objects and properties
@@ -151,15 +170,14 @@ ultimate source of truth.
 - [ ] The mapper and `thisArg` forms of `Array.from`.
 - [ ] `Array.prototype.toSpliced`.
 - [ ] Canonical index handling: a key such as `"01"` must not alias index `1`.
-- [ ] Complete sparse-array parity.
-- [ ] Correct `findLast` return behavior when its predicate mutates the examined element.
+- [ ] Complete sparse-array parity. Promise combinators do consume holes as `undefined` members, as in JS.
 
 ## Strings
 
 - [x] Case/normalization: `toLowerCase`, `toUpperCase`, `normalize`.
-- [x] Trimming: `trim`, `trimStart`, `trimEnd`, `trimLeft`, and `trimRight`.
+- [x] Trimming: `trim`, `trimStart`, and `trimEnd`.
 - [x] Searching/tests: `includes`, `startsWith`, `endsWith`, `indexOf`, `lastIndexOf`, and `search`.
-- [x] Slicing/access: `slice`, `substring`, `substr`, `at`, `charAt`, `charCodeAt`, and `codePointAt`.
+- [x] Slicing/access: `slice`, `substring`, `at`, `charAt`, `charCodeAt`, and `codePointAt`.
 - [x] Construction/transformation: `split`, `concat`, `repeat`, `padStart`, `padEnd`, `replace`, and `replaceAll`.
 - [x] Regular-expression integration: `match`, materialized `matchAll`, `replace`, `replaceAll`, `split`, and `search`.
 - [x] `localeCompare`; locale and options arguments are currently ignored.
@@ -256,6 +274,8 @@ ultimate source of truth.
 
 - [x] `Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, and `URIError`, callable with
       or without `new`.
+- [x] `AggregateError` with the `(errors, message?)` signature and an own `errors` array, constructed directly or by
+      an all-rejected `Promise.any`.
 - [x] Error `name`/`message`, error inheritance through `instanceof`, and plain-data serialization.
 - [x] `instanceof` for Date, RegExp, Map, Set, URL, URLSearchParams, Array, Object, Promise, and Error types.
 - [x] Catchable interpreter failures and awaited tool failures.
@@ -269,8 +289,7 @@ ultimate source of truth.
 
 These are actionable implementation items. Check them off only when behavior and direct tests land.
 
-- [ ] Return real promises from `Promise.all`, `Promise.allSettled`, and `Promise.race`.
-- [ ] Bound pending tool-call admission/allocation in addition to execution concurrency.
+- [x] Return real promises from `Promise.all`, `Promise.allSettled`, and `Promise.race`.
 - [ ] Guarantee every advertised tool path is executable, including dotted and blocked path segments.
 - [ ] Define safe outbound handling for non-finite numbers and `undefined` so invalid values cannot silently become
       `null` in render-only or OpenAPI tool calls.

packages/codemode/src/codemode.ts

@@ -1,11 +1,6 @@
 import { Effect, Schema } from "effect"
-import { executeWithLimits } from "./interpreter/runtime.js"
-import {
-  type HostTools,
-  type Services,
-  type ToolDescription,
-  ToolRuntime,
-} from "./tool-runtime.js"
+import { executeWithLimits } from "./interpreter/execute.js"
+import { type HostTools, type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js"
 import type { Definition } from "./tool.js"
 
 /** A tool call admitted during an execution. */
@@ -13,11 +8,17 @@ export type { ToolCall, ToolCallEnded, ToolCallHooks, ToolCallStarted, ToolDescr
 
 /** Resource budgets enforced independently during each CodeMode program execution. */
 export type ExecutionLimits = {
-  /** Maximum wall-clock execution time in milliseconds. No default: absent means no timeout. */
+  /**
+   * Wall-clock milliseconds before interruption. Result delivery waits for tool cleanup.
+   * No default: absent means no timeout.
+   */
   readonly timeoutMs?: number
   /** Maximum number of tool calls admitted by the runtime. No default: absent means unlimited. */
   readonly maxToolCalls?: number
-  /** Maximum UTF-8 bytes of model-facing output. No default: absent means no truncation. */
+  /**
+   * Maximum UTF-8 bytes retained from the result and logs. Warnings have a separate equal budget;
+   * truncation notices and host formatting are additional.
+   */
   readonly maxOutputBytes?: number
 }
 
@@ -75,8 +76,9 @@ export const DiagnosticKind = Schema.Literals([
   "TimeoutExceeded",
   "ToolFailure",
   "ExecutionFailure",
+  "Truncated",
 ])
-/** Stable categories produced by program, schema, tool, and limit failures. */
+/** Stable categories produced by program, schema, tool, limit, and truncation diagnostics. */
 export type DiagnosticKind = typeof DiagnosticKind.Type
 
 export const Diagnostic = Schema.Struct({
@@ -92,6 +94,7 @@ const ToolCallSchema = Schema.Struct({ name: Schema.String })
 export const Success = Schema.Struct({
   ok: Schema.Literal(true),
   value: Schema.Json,
+  warnings: Schema.optionalKey(Schema.Array(Diagnostic)),
   logs: Schema.optionalKey(Schema.Array(Schema.String)),
   truncated: Schema.optionalKey(Schema.Boolean),
   toolCalls: Schema.Array(ToolCallSchema),
@@ -121,11 +124,7 @@ export type Runtime<R = never> = {
   readonly execute: (code: string) => Effect.Effect<Result, never, R>
 }
 
-const validateLimit = <Value extends number | undefined>(
-  name: keyof ExecutionLimits,
-  value: Value,
-  minimum: number,
-): Value => {
+const validateLimit = (name: keyof ExecutionLimits, value: number | undefined, minimum: number): number | undefined => {
   if (value !== undefined && (!Number.isSafeInteger(value) || value < minimum)) {
     throw new RangeError(`${name} must be a safe integer greater than or equal to ${minimum}.`)
   }
@@ -143,7 +142,6 @@ export const execute = <const Tools extends Record<string, unknown>>(
   options: ExecuteOptions<Tools>,
 ): Effect.Effect<Result, never, Services<Tools>> => {
   const tools = (options.tools ?? {}) as HostTools<Services<Tools>>
-  ToolRuntime.assertValidTools(tools)
   return executeWithLimits(options, resolveExecutionLimits(options.limits), ToolRuntime.searchIndex(tools))
 }
 
@@ -152,7 +150,6 @@ export const make = <const Tools extends Record<string, unknown> = {}>(
   options: Options<Tools> = {} as Options<Tools>,
 ): Runtime<Services<Tools>> => {
   const tools = (options.tools ?? {}) as HostTools<Services<Tools>>
-  ToolRuntime.assertValidTools(tools)
   const limits = resolveExecutionLimits(options.limits)
   const prepared = ToolRuntime.prepare(tools, options.discovery?.catalogBudget)
 

packages/codemode/src/interpreter/errors.ts

@@ -0,0 +1,93 @@
+import type { Diagnostic } from "../codemode.js"
+import { ToolError } from "../tool-error.js"
+import { copyOut, ToolRuntimeError, type SafeObject } from "../tool-runtime.js"
+import { type AstNode, formatLocation, InterpreterRuntimeError, ProgramThrow, sourceLocation } from "./model.js"
+import { containsRuntimeReference } from "./references.js"
+import { spreadItems } from "../stdlib/collections.js"
+import { coerceToString, createAggregateErrorValue, createErrorValue, errorConstructors } from "../stdlib/value.js"
+
+export const normalizeError = (error: unknown): Diagnostic => {
+  if (error instanceof InterpreterRuntimeError) {
+    return {
+      kind: error.kind,
+      message: `${error.message}${formatLocation(error.node)}`,
+      ...(error.node?.loc ? { location: sourceLocation(error.node) } : {}),
+      ...(error.suggestions ? { suggestions: error.suggestions } : {}),
+    }
+  }
+
+  if (error instanceof ToolRuntimeError) {
+    return {
+      kind: error.kind,
+      message: error.message,
+      ...(error.suggestions.length > 0 ? { suggestions: error.suggestions } : {}),
+    }
+  }
+
+  if (error instanceof ToolError) {
+    return { kind: "ToolFailure", message: error.message }
+  }
+
+  if (error instanceof ProgramThrow) {
+    const value = error.value
+    let message: string
+    if (containsRuntimeReference(value)) {
+      // Never expose runtime reference internals through thrown values.
+      message = "a non-data value"
+    } else if (typeof value === "string") {
+      message = value
+    } else if (
+      value !== null &&
+      typeof value === "object" &&
+      typeof (value as { message?: unknown }).message === "string"
+    ) {
+      message = (value as { message: string }).message
+    } else {
+      try {
+        message = JSON.stringify(copyOut(value)) ?? String(value)
+      } catch {
+        message = String(value)
+      }
+    }
+    return { kind: "ExecutionFailure", message: `Uncaught: ${message}` }
+  }
+
+  if (error instanceof RangeError && /call stack|recursion/i.test(error.message)) {
+    return {
+      kind: "ExecutionFailure",
+      message: "Execution exceeded the maximum nesting depth.",
+    }
+  }
+
+  if (error instanceof Error) {
+    return {
+      kind: error.name === "SyntaxError" ? "ParseError" : "ExecutionFailure",
+      message: error.message,
+    }
+  }
+
+  return {
+    kind: "ExecutionFailure",
+    message: String(error),
+  }
+}
+
+export const caughtErrorValue = (thrown: unknown): unknown => {
+  if (thrown instanceof ProgramThrow) return thrown.value
+  if (thrown instanceof InterpreterRuntimeError) return createErrorValue(thrown.errorName, thrown.message)
+  const name = thrown instanceof Error && errorConstructors.has(thrown.name) ? thrown.name : "Error"
+  return createErrorValue(name, normalizeError(thrown).message)
+}
+
+export const constructErrorValue = (name: string, args: Array<unknown>, node: AstNode): SafeObject => {
+  if (name !== "AggregateError") return createErrorValue(name, args[0] === undefined ? "" : coerceToString(args[0]))
+  const errors = spreadItems(args[0])
+  if (errors === undefined) {
+    throw new InterpreterRuntimeError(
+      "new AggregateError(...) expects an array of errors (e.g. new AggregateError(errors, message?)).",
+      node,
+    ).as("TypeError")
+  }
+  // Error values must not alias caller-owned arrays.
+  return createAggregateErrorValue([...errors], args[1] === undefined ? "" : coerceToString(args[1]))
+}

packages/codemode/src/interpreter/execute.ts

@@ -0,0 +1,224 @@
+import { parse } from "acorn"
+import { Cause, Effect, Scope } from "effect"
+import { DiagnosticCategory, ModuleKind, ScriptTarget, flattenDiagnosticMessageText, transpileModule } from "typescript"
+import type { DataValue, Diagnostic, ExecuteOptions, ResolvedExecutionLimits, Result } from "../codemode.js"
+import { copyIn, copyOut, ToolRuntime, type HostTools, type Services } from "../tool-runtime.js"
+import { normalizeError } from "./errors.js"
+import { InterpreterRuntimeError, isRecord, type ProgramNode } from "./model.js"
+import { PromiseRuntime } from "./promises.js"
+import { Interpreter } from "./runtime.js"
+
+export const executeWithLimits = <const Tools extends Record<string, unknown>>(
+  options: ExecuteOptions<Tools>,
+  limits: ResolvedExecutionLimits,
+  searchIndex: ToolRuntime.DiscoveryPlan["searchIndex"],
+): Effect.Effect<Result, never, Services<Tools>> => {
+  if (options.code.trim().length === 0) {
+    return Effect.succeed({
+      ok: false,
+      error: { kind: "ParseError", message: "Code cannot be empty." },
+      toolCalls: [],
+    })
+  }
+
+  // Allocate execution state inside suspension so reused Effects never share it.
+  return Effect.suspend(() => {
+    const tools = ToolRuntime.make(
+      (options.tools ?? {}) as HostTools<Services<Tools>>,
+      limits.maxToolCalls,
+      searchIndex,
+      {
+        onToolCallStart: options.onToolCallStart,
+        onToolCallEnd: options.onToolCallEnd,
+      },
+    )
+    const logs: Array<string> = []
+    const logged = () => (logs.length > 0 ? { logs: [...logs] } : {})
+    // Set only after copy-out so timeouts cannot report invalid values as completed.
+    let returned: { value: DataValue; promises: PromiseRuntime<Services<Tools>> } | undefined
+
+    const base = Effect.acquireUseRelease(
+      Scope.make("parallel"),
+      (scope) =>
+        Effect.gen(function* () {
+          const program = parseProgram(options.code)
+          const promises = new PromiseRuntime<Services<Tools>>(scope)
+          const interpreter = new Interpreter<Services<Tools>>(tools.invoke, tools.search, tools.keys, promises, logs)
+          const value = yield* interpreter.run(program)
+          const result = copyOut(copyIn(value, "Execution result"), true) as DataValue
+          returned = { value: result, promises }
+          const warnings = yield* promises.interrupt()
+          return {
+            ok: true,
+            value: result,
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...logged(),
+            toolCalls: tools.calls,
+          } satisfies Result
+        }),
+      (scope, exit) => Scope.close(scope, exit),
+    )
+    const timeoutMs = limits.timeoutMs
+    const operation =
+      timeoutMs === undefined
+        ? base
+        : base.pipe(
+            Effect.timeoutOrElse({
+              duration: timeoutMs,
+              orElse: () =>
+                Effect.sync(() => {
+                  if (returned === undefined) {
+                    return {
+                      ok: false,
+                      error: { kind: "TimeoutExceeded", message: `Execution timed out after ${timeoutMs}ms.` },
+                      ...logged(),
+                      toolCalls: tools.calls,
+                    } satisfies Result
+                  }
+                  // Keep the timeout warning first so truncation preserves it.
+                  return {
+                    ok: true,
+                    value: returned.value,
+                    warnings: [
+                      {
+                        kind: "TimeoutExceeded",
+                        message: `The program returned, but background work was still running at the ${timeoutMs}ms timeout and was interrupted. Await all started promises.`,
+                      },
+                      ...returned.promises.diagnostics(),
+                    ],
+                    ...logged(),
+                    toolCalls: tools.calls,
+                  } satisfies Result
+                }),
+            }),
+          )
+
+    return operation.pipe(
+      Effect.catchCause((cause) =>
+        Cause.hasInterruptsOnly(cause)
+          ? Effect.interrupt
+          : Effect.succeed({
+              ok: false,
+              error: normalizeError(Cause.squash(cause)),
+              ...logged(),
+              toolCalls: tools.calls,
+            } satisfies Result),
+      ),
+      Effect.map((result) =>
+        limits.maxOutputBytes === undefined ? result : boundOutput(result, limits.maxOutputBytes),
+      ),
+    )
+  })
+}
+
+const parseProgram = (code: string): ProgramNode => {
+  const transpiled = transpileModule(`async function __codemode__() {\n${code}\n}`, {
+    reportDiagnostics: true,
+    compilerOptions: {
+      target: ScriptTarget.ESNext,
+      module: ModuleKind.ESNext,
+    },
+  })
+  const diagnostic = transpiled.diagnostics?.find((item) => item.category === DiagnosticCategory.Error)
+
+  if (diagnostic) {
+    throw new InterpreterRuntimeError(
+      `Failed to parse TypeScript: ${flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`,
+      undefined,
+      "ParseError",
+    )
+  }
+
+  const bodyStart = transpiled.outputText.indexOf("{") + 1
+  const bodyEnd = transpiled.outputText.lastIndexOf("}")
+  const executableCode = transpiled.outputText.slice(bodyStart, bodyEnd)
+  const parsed = parse(executableCode, {
+    ecmaVersion: "latest",
+    sourceType: "script",
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+    locations: true,
+  }) as unknown
+
+  if (!isRecord(parsed) || parsed.type !== "Program" || !Array.isArray(parsed.body)) {
+    throw new InterpreterRuntimeError("Failed to parse script as a Program node.")
+  }
+
+  return parsed as ProgramNode
+}
+
+const utf8ByteLength = (value: string): number => new TextEncoder().encode(value).byteLength
+
+// Drop a replacement character produced by truncating inside a UTF-8 sequence.
+const utf8Truncate = (value: string, maxBytes: number): string => {
+  const bytes = new TextEncoder().encode(value)
+  if (bytes.byteLength <= maxBytes) return value
+  const text = new TextDecoder("utf-8").decode(bytes.slice(0, Math.max(0, maxBytes)))
+  return text.endsWith("\uFFFD") ? text.slice(0, -1) : text
+}
+
+// Warnings have a separate budget so result data cannot starve diagnostics.
+const boundOutput = (result: Result, maxOutputBytes: number): Result => {
+  let truncated = false
+
+  let value: DataValue = null
+  let valueBytes = 0
+  if (result.ok) {
+    const serialized = JSON.stringify(result.value) ?? "null"
+    const bytes = utf8ByteLength(serialized)
+    if (bytes > maxOutputBytes) {
+      truncated = true
+      value = `${utf8Truncate(serialized, maxOutputBytes)} [result truncated: ${bytes} bytes exceeds the ${maxOutputBytes}-byte output limit; return a smaller value]`
+      valueBytes = maxOutputBytes
+    } else {
+      value = result.value
+      valueBytes = bytes
+    }
+  }
+
+  const warnings = result.ok ? (result.warnings ?? []) : []
+  const keptWarnings: Array<Diagnostic> = []
+  let warningBytes = 0
+  for (const warning of warnings) {
+    const bytes = utf8ByteLength(JSON.stringify(warning)) + 1
+    if (warningBytes + bytes > maxOutputBytes) break
+    warningBytes += bytes
+    keptWarnings.push(warning)
+  }
+  if (keptWarnings.length < warnings.length) {
+    truncated = true
+    keptWarnings.push({
+      kind: "Truncated",
+      message: `${warnings.length - keptWarnings.length} additional warnings omitted by the output limit.`,
+    })
+  }
+
+  const logs = result.logs ?? []
+  const kept: Array<string> = []
+  const logBudget = Math.max(0, maxOutputBytes - valueBytes)
+  let logBytes = 0
+  for (const line of logs) {
+    const lineBytes = utf8ByteLength(line) + 1
+    if (logBytes + lineBytes > logBudget) break
+    logBytes += lineBytes
+    kept.push(line)
+  }
+  if (kept.length < logs.length) {
+    truncated = true
+    kept.push(`[logs truncated: showing ${kept.length} of ${logs.length} lines]`)
+  }
+
+  if (!truncated) return result
+  const warningsPart = keptWarnings.length > 0 ? { warnings: keptWarnings } : {}
+  const logsPart = kept.length > 0 ? { logs: kept } : {}
+  return result.ok
+    ? {
+        ok: true,
+        value,
+        ...warningsPart,
+        ...logsPart,
+        truncated: true,
+        toolCalls: result.toolCalls,
+      }
+    : { ok: false, error: result.error, ...logsPart, truncated: true, toolCalls: result.toolCalls }
+}

packages/codemode/src/interpreter/methods.ts

@@ -0,0 +1,820 @@
+import { Effect } from "effect"
+import {
+  type AstNode,
+  CodeModeFunction,
+  CoercionFunction,
+  GlobalMethodReference,
+  IntrinsicReference,
+  InterpreterRuntimeError,
+  PromiseCapabilityFunction,
+  supportedSyntaxMessage,
+  UriFunction,
+} from "./model.js"
+import { rejectCircularInsertion } from "./references.js"
+import { isBlockedMember, type SafeObject } from "../tool-runtime.js"
+import {
+  SandboxDate,
+  SandboxMap,
+  SandboxPromise,
+  SandboxRegExp,
+  SandboxSet,
+  SandboxURL,
+  SandboxURLSearchParams,
+} from "../values.js"
+import { invokeDateMethod, invokeDateStatic } from "../stdlib/date.js"
+import { invokeJsonMethod } from "../stdlib/json.js"
+import { invokeMathMethod } from "../stdlib/math.js"
+import { invokeNumberMethod, invokeNumberStatic } from "../stdlib/number.js"
+import { invokeObjectMethod } from "../stdlib/object.js"
+import { invokeRegExpMethod, matchToValue, toHostRegex } from "../stdlib/regexp.js"
+import { invokeStringStatic } from "../stdlib/string.js"
+import { invokeUriFunction, invokeURLMethod, invokeURLStatic, uriArgument } from "../stdlib/url.js"
+import { boundedData, coerceToNumber, coerceToString, invokeCoercion } from "../stdlib/value.js"
+
+export type CallbackRunner<R> = {
+  readonly invokeFunction: (fn: CodeModeFunction, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
+  readonly settlePromise: (promise: SandboxPromise) => Effect.Effect<unknown, unknown, never>
+}
+
+export const invokeIntrinsic = <R>(
+  runner: CallbackRunner<R>,
+  ref: IntrinsicReference,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  if (typeof ref.receiver === "string") {
+    if (
+      (ref.name === "replace" || ref.name === "replaceAll") &&
+      (args[1] instanceof CodeModeFunction || args[1] instanceof CoercionFunction || args[1] instanceof UriFunction)
+    ) {
+      return invokeStringReplacer(runner, ref.receiver, ref.name, args, node)
+    }
+    return Effect.succeed(invokeStringMethod(ref.receiver, ref.name, args, node))
+  }
+  if (typeof ref.receiver === "number") {
+    return Effect.succeed(invokeNumberMethod(ref.receiver, ref.name, args, node))
+  }
+  if (Array.isArray(ref.receiver)) {
+    return invokeArrayMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  if (ref.receiver instanceof SandboxDate) {
+    return Effect.succeed(invokeDateMethod(ref.receiver, ref.name, node))
+  }
+  if (ref.receiver instanceof SandboxRegExp) {
+    return Effect.succeed(invokeRegExpMethod(ref.receiver, ref.name, args, node))
+  }
+  if (ref.receiver instanceof SandboxMap) {
+    return invokeMapMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  if (ref.receiver instanceof SandboxSet) {
+    return invokeSetMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  if (ref.receiver instanceof SandboxURL) {
+    return Effect.succeed(invokeURLMethod(ref.receiver, ref.name, node))
+  }
+  if (ref.receiver instanceof SandboxURLSearchParams) {
+    return invokeURLSearchParamsMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  throw new InterpreterRuntimeError(`Method '${ref.name}' is not available in CodeMode.`, node)
+}
+
+export const invokeGlobalMethod = (ref: GlobalMethodReference, args: Array<unknown>, node: AstNode): unknown => {
+  if (ref.namespace === "console")
+    throw new InterpreterRuntimeError(`console.${ref.name} is not available in CodeMode.`, node)
+  if (ref.namespace === "Object") return invokeObjectMethod(ref.name, args, node)
+  if (ref.namespace === "Math") return invokeMathMethod(ref.name, args, node)
+  if (ref.namespace === "Array") return invokeArrayStatic(ref.name, args, node)
+  if (ref.namespace === "Number") return invokeNumberStatic(ref.name, args, node)
+  if (ref.namespace === "String") return invokeStringStatic(ref.name, args, node)
+  if (ref.namespace === "URL") return invokeURLStatic(ref.name, args, node)
+  if (ref.namespace === "Date") return invokeDateStatic(ref.name, args, node)
+  if (
+    ref.namespace === "RegExp" ||
+    ref.namespace === "Map" ||
+    ref.namespace === "Set" ||
+    ref.namespace === "URLSearchParams"
+  ) {
+    throw new InterpreterRuntimeError(`${ref.namespace}.${ref.name} is not available in CodeMode.`, node)
+  }
+  return invokeJsonMethod(ref.name, args, node)
+}
+
+const invokeStringMethod = (value: string, name: string, args: Array<unknown>, node: AstNode): unknown => {
+  const str = (index: number): string => {
+    const arg = args[index]
+    if (typeof arg !== "string")
+      throw new InterpreterRuntimeError(`String.${name} expects argument ${index + 1} to be a string.`, node)
+    return arg
+  }
+  const num = (index: number): number => {
+    const arg = args[index]
+    if (typeof arg !== "number")
+      throw new InterpreterRuntimeError(`String.${name} expects argument ${index + 1} to be a number.`, node)
+    return arg
+  }
+  const optNum = (index: number): number | undefined => (args[index] === undefined ? undefined : num(index))
+  const optStr = (index: number): string | undefined => (args[index] === undefined ? undefined : str(index))
+
+  let result: unknown
+  switch (name) {
+    case "toLowerCase":
+      result = value.toLowerCase()
+      break
+    case "toUpperCase":
+      result = value.toUpperCase()
+      break
+    case "trim":
+      result = value.trim()
+      break
+    case "trimStart":
+      result = value.trimStart()
+      break
+    case "trimEnd":
+      result = value.trimEnd()
+      break
+    // Locale/options are deliberately unsupported; comparison uses the host default locale.
+    case "localeCompare":
+      result = value.localeCompare(str(0))
+      break
+    case "normalize": {
+      const form = optStr(0)
+      try {
+        result = value.normalize(form)
+      } catch {
+        throw new InterpreterRuntimeError(
+          `String.normalize expects the form "NFC", "NFD", "NFKC", or "NFKD" (got ${JSON.stringify(form)}).`,
+          node,
+        ).as("RangeError")
+      }
+      break
+    }
+    case "split": {
+      if (args.length === 0) {
+        result = [value]
+        break
+      }
+      if (args[0] instanceof SandboxRegExp) {
+        result = value.split(args[0].regex, optNum(1))
+        break
+      }
+      const requestedLimit = optNum(1)
+      result = value.split(str(0), requestedLimit === undefined ? undefined : requestedLimit >>> 0)
+      break
+    }
+    case "slice":
+      result = value.slice(optNum(0), optNum(1))
+      break
+    case "includes":
+      result = value.includes(str(0), optNum(1))
+      break
+    case "startsWith":
+      result = value.startsWith(str(0), optNum(1))
+      break
+    case "endsWith":
+      result = value.endsWith(str(0), optNum(1))
+      break
+    case "indexOf":
+      result = value.indexOf(str(0), optNum(1))
+      break
+    case "lastIndexOf":
+      result = value.lastIndexOf(str(0), optNum(1))
+      break
+    case "replace":
+    case "replaceAll": {
+      if (args[0] instanceof SandboxRegExp) {
+        const pattern = args[0].regex
+        const replacement = str(1)
+        if (name === "replaceAll" && !pattern.global) {
+          throw new InterpreterRuntimeError(
+            `String.replaceAll requires a regular expression with the global (g) flag: write /${pattern.source}/${pattern.flags}g, or use String.replace to replace only the first match.`,
+            node,
+          )
+        }
+        result = name === "replace" ? value.replace(pattern, replacement) : value.replaceAll(pattern, replacement)
+        break
+      }
+      if (name === "replace") {
+        result = value.replace(str(0), str(1))
+        break
+      }
+      result = value.replaceAll(str(0), str(1))
+      break
+    }
+    case "match": {
+      const pattern = toHostRegex(args[0], name, node)
+      const matched = value.match(pattern)
+      if (matched === null) return null
+      // Preserve the own `index` and `groups` properties on non-global matches.
+      if (pattern.global) return boundedData(matched, "String.match result")
+      return matchToValue(matched)
+    }
+    case "matchAll": {
+      const pattern = toHostRegex(args[0], name, node, "g")
+      if (!pattern.global) {
+        throw new InterpreterRuntimeError(
+          `String.matchAll requires a regular expression with the global (g) flag: write /${pattern.source}/${pattern.flags}g, or use String.match for a single match.`,
+          node,
+        )
+      }
+      return Array.from(value.matchAll(pattern), matchToValue)
+    }
+    case "search": {
+      result = value.search(toHostRegex(args[0], name, node))
+      break
+    }
+    case "repeat": {
+      const count = num(0)
+      if (!Number.isFinite(count) || count < 0)
+        throw new InterpreterRuntimeError("String.repeat expects a finite non-negative count.", node)
+      result = value.repeat(count)
+      break
+    }
+    case "padStart":
+      result = value.padStart(num(0), optStr(1))
+      break
+    case "padEnd":
+      result = value.padEnd(num(0), optStr(1))
+      break
+    case "charAt":
+      result = value.charAt(optNum(0) ?? 0)
+      break
+    case "at":
+      result = value.at(optNum(0) ?? 0)
+      break
+    case "substring":
+      result = value.substring(optNum(0) ?? 0, optNum(1))
+      break
+    case "charCodeAt":
+      result = value.charCodeAt(optNum(0) ?? 0)
+      break
+    case "codePointAt":
+      result = value.codePointAt(optNum(0) ?? 0)
+      break
+    case "toString":
+      result = value
+      break
+    case "concat": {
+      result = value.concat(...args.map((_, index) => str(index)))
+      break
+    }
+    default:
+      throw new InterpreterRuntimeError(`String method '${name}' is not available in CodeMode.`, node)
+  }
+  return boundedData(result, `String.${name} result`)
+}
+
+const invokeArrayStatic = (name: string, args: Array<unknown>, node: AstNode): unknown => {
+  switch (name) {
+    case "isArray":
+      return Array.isArray(args[0])
+    case "of":
+      return [...args]
+    case "from": {
+      if (args.length > 1) {
+        throw new InterpreterRuntimeError(
+          "Array.from(...) does not support a map function in CodeMode; call .map() on the result instead.",
+          node,
+          "UnsupportedSyntax",
+          [supportedSyntaxMessage],
+        )
+      }
+      if (args[0] instanceof SandboxMap) return Array.from(args[0].map.entries(), ([key, item]) => [key, item])
+      if (args[0] instanceof SandboxSet) return Array.from(args[0].set.values())
+      if (args[0] instanceof SandboxURLSearchParams) {
+        return Array.from(args[0].params.entries(), ([key, value]) => [key, value])
+      }
+      const source = args[0]
+      if (source instanceof SandboxPromise) {
+        throw new InterpreterRuntimeError(
+          "Array.from received an un-awaited Promise; await it before creating the array.",
+          node,
+          "InvalidDataValue",
+        )
+      }
+      if (typeof source === "string") return Array.from(source)
+      if (Array.isArray(source)) return [...source]
+      if (
+        source !== null &&
+        typeof source === "object" &&
+        (Object.getPrototypeOf(source) === Object.prototype || Object.getPrototypeOf(source) === null) &&
+        typeof (source as { length?: unknown }).length === "number"
+      ) {
+        return Array.from(source as ArrayLike<unknown>)
+      }
+      throw new InterpreterRuntimeError(
+        "Array.from expects an array, string, Map, Set, or array-like value.",
+        node,
+        "InvalidDataValue",
+      )
+    }
+    default:
+      throw new InterpreterRuntimeError(`Array.${name} is not available in CodeMode.`, node)
+  }
+}
+
+const invokeStringReplacer = <R>(
+  runner: CallbackRunner<R>,
+  value: string,
+  name: "replace" | "replaceAll",
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  const apply = applyCollectionCallback(runner, args[1], `String.${name}`, node)
+  const matches: Array<{ readonly match: string; readonly offset: number; readonly args: Array<unknown> }> = []
+  const collect = (...callbackArgs: Array<unknown>): string => {
+    const match = callbackArgs[0]
+    const groups = callbackArgs[callbackArgs.length - 1]
+    const hasGroups = groups !== null && typeof groups === "object"
+    const offset = callbackArgs[callbackArgs.length - (hasGroups ? 3 : 2)]
+    if (typeof match !== "string" || typeof offset !== "number") {
+      throw new InterpreterRuntimeError(`String.${name} produced an invalid replacement match.`, node)
+    }
+    if (hasGroups) {
+      const safeGroups: SafeObject = Object.create(null) as SafeObject
+      for (const [key, group] of Object.entries(groups)) {
+        if (!isBlockedMember(key)) safeGroups[key] = group
+      }
+      callbackArgs[callbackArgs.length - 1] = safeGroups
+    }
+    matches.push({ match, offset, args: callbackArgs })
+    return match
+  }
+
+  const pattern = args[0]
+  if (pattern instanceof SandboxRegExp) {
+    if (name === "replaceAll" && !pattern.regex.global) {
+      throw new InterpreterRuntimeError(
+        `String.replaceAll requires a regular expression with the global (g) flag: write /${pattern.regex.source}/${pattern.regex.flags}g, or use String.replace to replace only the first match.`,
+        node,
+      )
+    }
+    if (name === "replace") value.replace(pattern.regex, collect)
+    else value.replaceAll(pattern.regex, collect)
+  } else {
+    if (typeof pattern !== "string") {
+      throw new InterpreterRuntimeError(`String.${name} expects argument 1 to be a string.`, node)
+    }
+    if (name === "replace") value.replace(pattern, collect)
+    else value.replaceAll(pattern, collect)
+  }
+
+  return Effect.gen(function* () {
+    const output: Array<string> = []
+    let end = 0
+    for (const match of matches) {
+      const replacement = yield* apply(match.args)
+      const resolved =
+        args[1] instanceof CodeModeFunction && args[1].async && replacement instanceof SandboxPromise
+          ? yield* runner.settlePromise(replacement)
+          : replacement
+      output.push(
+        value.slice(end, match.offset),
+        coerceToString(boundedData(resolved, `String.${name} replacer result`)),
+      )
+      end = match.offset + match.match.length
+    }
+    output.push(value.slice(end))
+    return boundedData(output.join(""), `String.${name} result`)
+  })
+}
+
+export const applyCollectionCallback = <R>(
+  runner: CallbackRunner<R>,
+  callback: unknown,
+  name: string,
+  node: AstNode,
+): ((args: Array<unknown>) => Effect.Effect<unknown, unknown, R>) => {
+  if (
+    !(callback instanceof CodeModeFunction) &&
+    !(callback instanceof CoercionFunction) &&
+    !(callback instanceof UriFunction) &&
+    !(callback instanceof PromiseCapabilityFunction)
+  ) {
+    throw new InterpreterRuntimeError(`${name} expects a function callback.`, node)
+  }
+  return (callbackArgs) =>
+    callback instanceof CoercionFunction
+      ? Effect.succeed(invokeCoercion(callback, callbackArgs, node))
+      : callback instanceof UriFunction
+        ? Effect.succeed(invokeUriFunction(callback, callbackArgs, node))
+        : callback instanceof PromiseCapabilityFunction
+          ? Effect.sync(() => callback.settle(callbackArgs[0]))
+          : runner.invokeFunction(callback, callbackArgs)
+}
+
+const invokeMapMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: SandboxMap,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  switch (name) {
+    case "get":
+      return Effect.succeed(target.map.get(args[0]))
+    case "has":
+      return Effect.succeed(target.map.has(args[0]))
+    case "set":
+      return Effect.sync(() => {
+        target.map.set(args[0], args[1])
+        return target
+      })
+    case "delete":
+      return Effect.sync(() => target.map.delete(args[0]))
+    case "clear":
+      return Effect.sync(() => {
+        target.map.clear()
+        return undefined
+      })
+    case "keys":
+      return Effect.sync(() => Array.from(target.map.keys()))
+    case "values":
+      return Effect.sync(() => Array.from(target.map.values()))
+    case "entries":
+      return Effect.sync(() => Array.from(target.map.entries(), ([key, item]): Array<unknown> => [key, item]))
+    case "forEach": {
+      const apply = applyCollectionCallback(runner, args[0], "Map.forEach", node)
+      return Effect.gen(function* () {
+        for (const [key, item] of Array.from(target.map.entries())) yield* apply([item, key, target])
+        return undefined
+      })
+    }
+    default:
+      throw new InterpreterRuntimeError(`Map method '${name}' is not available in CodeMode.`, node)
+  }
+}
+
+const invokeSetMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: SandboxSet,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  switch (name) {
+    case "has":
+      return Effect.succeed(target.set.has(args[0]))
+    case "add":
+      return Effect.sync(() => {
+        target.set.add(args[0])
+        return target
+      })
+    case "delete":
+      return Effect.sync(() => target.set.delete(args[0]))
+    case "clear":
+      return Effect.sync(() => {
+        target.set.clear()
+        return undefined
+      })
+    case "keys":
+    case "values":
+      return Effect.sync(() => Array.from(target.set.values()))
+    case "entries":
+      return Effect.sync(() => Array.from(target.set.values(), (item): Array<unknown> => [item, item]))
+    case "forEach": {
+      const apply = applyCollectionCallback(runner, args[0], "Set.forEach", node)
+      return Effect.gen(function* () {
+        for (const item of Array.from(target.set.values())) yield* apply([item, item, target])
+        return undefined
+      })
+    }
+    default:
+      throw new InterpreterRuntimeError(`Set method '${name}' is not available in CodeMode.`, node)
+  }
+}
+
+const invokeURLSearchParamsMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: SandboxURLSearchParams,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  const arg = (index: number): string => uriArgument(args[index], `URLSearchParams.${name} argument ${index + 1}`)
+  const requireArgs = (count: number): void => {
+    if (args.length < count) {
+      throw new InterpreterRuntimeError(
+        `URLSearchParams.${name} requires ${count} argument${count === 1 ? "" : "s"}.`,
+        node,
+      ).as("TypeError")
+    }
+  }
+  switch (name) {
+    case "append": {
+      requireArgs(2)
+      return Effect.sync(() => {
+        target.params.append(arg(0), arg(1))
+        return undefined
+      })
+    }
+    case "delete": {
+      requireArgs(1)
+      return Effect.sync(() => {
+        if (args[1] !== undefined) target.params.delete(arg(0), arg(1))
+        else target.params.delete(arg(0))
+        return undefined
+      })
+    }
+    case "get":
+      requireArgs(1)
+      return Effect.sync(() => target.params.get(arg(0)))
+    case "getAll":
+      requireArgs(1)
+      return Effect.sync(() => target.params.getAll(arg(0)))
+    case "has":
+      requireArgs(1)
+      return Effect.sync(() => (args[1] !== undefined ? target.params.has(arg(0), arg(1)) : target.params.has(arg(0))))
+    case "set": {
+      requireArgs(2)
+      return Effect.sync(() => {
+        target.params.set(arg(0), arg(1))
+        return undefined
+      })
+    }
+    case "sort":
+      return Effect.sync(() => {
+        target.params.sort()
+        return undefined
+      })
+    case "keys":
+      return Effect.sync(() => Array.from(target.params.keys()))
+    case "values":
+      return Effect.sync(() => Array.from(target.params.values()))
+    case "entries":
+      return Effect.sync(() => Array.from(target.params.entries(), ([key, value]): Array<unknown> => [key, value]))
+    case "toString":
+      return Effect.sync(() => target.params.toString())
+    case "forEach": {
+      requireArgs(1)
+      const apply = applyCollectionCallback(runner, args[0], "URLSearchParams.forEach", node)
+      return Effect.gen(function* () {
+        for (const [key, value] of Array.from(target.params.entries())) yield* apply([value, key, target])
+        return undefined
+      })
+    }
+    default:
+      throw new InterpreterRuntimeError(`URLSearchParams method '${name}' is not available in CodeMode.`, node)
+  }
+}
+
+const invokeArrayMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: Array<unknown>,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  const optNumber = (value: unknown, label: string): number | undefined => {
+    if (value === undefined) return undefined
+    if (typeof value !== "number")
+      throw new InterpreterRuntimeError(`Array.${name} expects ${label} to be a number.`, node)
+    return value
+  }
+  switch (name) {
+    case "join": {
+      if (args.length > 1 || (args.length === 1 && typeof args[0] !== "string")) {
+        throw new InterpreterRuntimeError("Array.join expects zero arguments or one string separator.", node)
+      }
+      const input = boundedData(target, "Array.join input") as Array<unknown>
+      return Effect.succeed(
+        input.map((item) => coerceToString(item ?? "")).join(args.length === 0 ? "," : (args[0] as string)),
+      )
+    }
+    case "includes":
+      if (args.length === 0 || args.length > 2)
+        throw new InterpreterRuntimeError("Array.includes expects a value and optional start index.", node)
+      return Effect.succeed(target.includes(args[0], optNumber(args[1], "start index")))
+    case "indexOf":
+      return Effect.succeed(target.indexOf(args[0], optNumber(args[1], "start index")))
+    case "lastIndexOf":
+      return Effect.succeed(
+        args[1] === undefined
+          ? target.lastIndexOf(args[0])
+          : target.lastIndexOf(args[0], optNumber(args[1], "start index")),
+      )
+    case "at":
+      return Effect.succeed(target.at(optNumber(args[0], "index") ?? 0))
+    case "slice":
+      return Effect.succeed(target.slice(optNumber(args[0], "start"), optNumber(args[1], "end")))
+    case "concat":
+      return Effect.succeed(target.concat(...args))
+    case "flat":
+      return Effect.succeed(target.flat(optNumber(args[0], "depth") ?? 1))
+    case "reverse":
+      return Effect.succeed(target.reverse())
+    case "sort":
+      return Effect.map(sortArray(runner, target, args[0], node), (sorted) => {
+        target.splice(0, target.length, ...sorted)
+        return target
+      })
+    case "toSorted":
+      return sortArray(runner, target, args[0], node)
+    case "toReversed":
+      return Effect.succeed([...target].reverse())
+    case "with": {
+      const index = optNumber(args[0], "index") ?? 0
+      const resolved = index < 0 ? target.length + index : index
+      if (resolved < 0 || resolved >= target.length) {
+        throw new InterpreterRuntimeError("Array.with index is out of range.", node)
+      }
+      const copied = [...target]
+      copied[resolved] = args[1]
+      return Effect.succeed(copied)
+    }
+    case "push": {
+      // Validate all insertions before mutating to avoid partial cyclic updates.
+      for (const item of args) rejectCircularInsertion(target, item, "Array.push result", node)
+      target.push(...args)
+      return Effect.succeed(target.length)
+    }
+    case "unshift": {
+      for (const item of args) rejectCircularInsertion(target, item, "Array.unshift result", node)
+      target.unshift(...args)
+      return Effect.succeed(target.length)
+    }
+    case "pop":
+      return Effect.succeed(target.pop())
+    case "shift":
+      return Effect.succeed(target.shift())
+    case "splice": {
+      if (args.length === 0) return Effect.succeed(target.splice(0, 0))
+      const start = optNumber(args[0], "start") ?? 0
+      if (args.length === 1) return Effect.succeed(target.splice(start))
+      const deleteCount = optNumber(args[1], "delete count") ?? 0
+      const inserted = args.slice(2)
+      for (const item of inserted) rejectCircularInsertion(target, item, "Array.splice result", node)
+      return Effect.succeed(target.splice(start, deleteCount, ...inserted))
+    }
+    case "fill": {
+      rejectCircularInsertion(target, args[0], "Array.fill result", node)
+      return Effect.succeed(target.fill(args[0], optNumber(args[1], "start"), optNumber(args[2], "end")))
+    }
+    case "copyWithin":
+      return Effect.succeed(
+        target.copyWithin(
+          optNumber(args[0], "target index") ?? 0,
+          optNumber(args[1], "start") ?? 0,
+          optNumber(args[2], "end"),
+        ),
+      )
+    case "keys":
+      return Effect.succeed(Array.from(target.keys()))
+    case "values":
+      return Effect.succeed([...target])
+    case "entries":
+      return Effect.succeed(Array.from(target.entries(), ([index, item]): Array<unknown> => [index, item]))
+  }
+
+  const apply = applyCollectionCallback(runner, args[0], `Array.${name}`, node)
+  return Effect.gen(function* () {
+    // Fix iteration length while reading existing elements live.
+    const length = target.length
+    switch (name) {
+      case "map": {
+        const values: Array<unknown> = []
+        values.length = length
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          values[index] = yield* apply([target[index], index, target])
+        }
+        return values
+      }
+      case "flatMap": {
+        const values: Array<unknown> = []
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          const mapped = yield* apply([target[index], index, target])
+          if (Array.isArray(mapped)) values.push(...mapped)
+          else values.push(mapped)
+        }
+        return values
+      }
+      case "filter": {
+        const values: Array<unknown> = []
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          const item = target[index]
+          if (yield* apply([item, index, target])) values.push(item)
+        }
+        return values
+      }
+      case "find":
+        for (let index = 0; index < length; index += 1) {
+          const item = target[index]
+          if (yield* apply([item, index, target])) return item
+        }
+        return undefined
+      case "findIndex":
+        for (let index = 0; index < length; index += 1) {
+          if (yield* apply([target[index], index, target])) return index
+        }
+        return -1
+      case "some":
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          if (yield* apply([target[index], index, target])) return true
+        }
+        return false
+      case "every":
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          if (!(yield* apply([target[index], index, target]))) return false
+        }
+        return true
+      case "forEach":
+        for (let index = 0; index < length; index += 1) {
+          if (index in target) yield* apply([target[index], index, target])
+        }
+        return undefined
+      case "reduce": {
+        let start = 0
+        let accumulator = args[1]
+        if (args.length < 2) {
+          while (start < length && !(start in target)) start += 1
+          if (start === length)
+            throw new InterpreterRuntimeError("Array.reduce of an empty array with no initial value.", node).as(
+              "TypeError",
+            )
+          accumulator = target[start]
+          start += 1
+        }
+        for (let index = start; index < length; index += 1) {
+          if (!(index in target)) continue
+          accumulator = yield* apply([accumulator, target[index], index, target])
+        }
+        return accumulator
+      }
+      case "reduceRight": {
+        let start = length - 1
+        let accumulator = args[1]
+        if (args.length < 2) {
+          while (start >= 0 && !(start in target)) start -= 1
+          if (start < 0)
+            throw new InterpreterRuntimeError("Array.reduceRight of an empty array with no initial value.", node).as(
+              "TypeError",
+            )
+          accumulator = target[start]
+          start -= 1
+        }
+        for (let index = start; index >= 0; index -= 1) {
+          if (!(index in target)) continue
+          accumulator = yield* apply([accumulator, target[index], index, target])
+        }
+        return accumulator
+      }
+      case "findLast":
+        for (let index = length - 1; index >= 0; index -= 1) {
+          const item = target[index]
+          if (yield* apply([item, index, target])) return item
+        }
+        return undefined
+      case "findLastIndex":
+        for (let index = length - 1; index >= 0; index -= 1) {
+          if (yield* apply([target[index], index, target])) return index
+        }
+        return -1
+    }
+    throw new InterpreterRuntimeError(`Array method '${name}' is not available in CodeMode.`, node)
+  })
+}
+
+const sortArray = <R>(
+  runner: CallbackRunner<R>,
+  target: Array<unknown>,
+  comparator: unknown,
+  node: AstNode,
+): Effect.Effect<Array<unknown>, unknown, R> => {
+  if (comparator !== undefined && !(comparator instanceof CodeModeFunction)) {
+    throw new InterpreterRuntimeError("Array.sort expects an arrow function comparator.", node)
+  }
+  if (!(comparator instanceof CodeModeFunction)) {
+    return Effect.sync(() =>
+      [...target].sort((a, b) => {
+        const left = coerceToString(a)
+        const right = coerceToString(b)
+        return left < right ? -1 : left > right ? 1 : 0
+      }),
+    )
+  }
+  const mergeSort = (items: Array<unknown>): Effect.Effect<Array<unknown>, unknown, R> => {
+    if (items.length <= 1) return Effect.succeed(items)
+    const midpoint = Math.floor(items.length / 2)
+    return Effect.gen(function* () {
+      const left = yield* mergeSort(items.slice(0, midpoint))
+      const right = yield* mergeSort(items.slice(midpoint))
+      const merged: Array<unknown> = []
+      let leftIndex = 0
+      let rightIndex = 0
+      while (leftIndex < left.length && rightIndex < right.length) {
+        // Treat a NaN comparator result as equal to preserve stable ordering.
+        const order = coerceToNumber(yield* runner.invokeFunction(comparator, [left[leftIndex], right[rightIndex]]))
+        if (Number.isNaN(order) || order <= 0) merged.push(left[leftIndex++])
+        else merged.push(right[rightIndex++])
+      }
+      return [...merged, ...left.slice(leftIndex), ...right.slice(rightIndex)]
+    })
+  }
+  const defined = target.filter((item) => item !== undefined)
+  const undefinedCount = target.length - defined.length
+  return Effect.map(mergeSort(defined), (items) => [...items, ...Array(undefinedCount).fill(undefined)])
+}

packages/codemode/src/interpreter/model.ts

@@ -1,5 +1,5 @@
 import type { SafeObject } from "../tool-runtime.js"
-import type { SandboxURL } from "../values.js"
+import type { SandboxPromise, SandboxURL } from "../values.js"
 
 export type SourcePosition = {
   line: number
@@ -61,12 +61,25 @@ export class ComputedValue {
 
 export class PromiseNamespace {}
 
-export type PromiseMethodName = "all" | "allSettled" | "race" | "resolve" | "reject"
+export type PromiseMethodName = "all" | "allSettled" | "race" | "any" | "resolve" | "reject"
 
 export class PromiseMethodReference {
   constructor(readonly name: PromiseMethodName) {}
 }
 
+export type PromiseInstanceMethodName = "then" | "catch" | "finally"
+
+export class PromiseInstanceMethodReference {
+  constructor(
+    readonly promise: SandboxPromise,
+    readonly name: PromiseInstanceMethodName,
+  ) {}
+}
+
+export class PromiseCapabilityFunction {
+  constructor(readonly settle: (value: unknown) => void) {}
+}
+
 export type GlobalNamespaceName =
   | "Object"
   | "Math"
@@ -99,6 +112,8 @@ export class UriFunction {
   constructor(readonly name: "encodeURI" | "encodeURIComponent" | "decodeURI" | "decodeURIComponent") {}
 }
 
+export class SearchFunction {}
+
 export class ProgramThrow {
   constructor(readonly value: unknown) {}
 }
@@ -122,11 +137,11 @@ export type DiagnosticKind =
 export const OptionalShortCircuit: unique symbol = Symbol("codemode.optional-short-circuit")
 
 export const supportedSyntaxMessage =
-  "Supported orchestration syntax: tools.* calls (they return promises - resolve them with await), data literals, destructuring, optional chaining, template literals, conditionals, switch, loops (incl. for...of and for...in over object/array/tools keys), arrow functions, spread, try/catch, array methods (map/filter/find/findIndex/some/every/reduce/flatMap/forEach/sort/slice/concat/indexOf/lastIndexOf/at/flat/reverse/includes/join), string methods (incl. match/matchAll/replace/split with regular expressions), Date/RegExp/Map/Set/URL/URLSearchParams, URI encoding helpers, Object/Math/JSON helpers, captured console.log/warn/error/dir/table, and Promise.all/allSettled/race/resolve/reject over arrays mixing promises and plain values for parallel tool calls (promise chaining with .then/.catch is not supported - use await with try/catch)."
+  "Supported orchestration syntax: tools.* calls (they return promises - resolve them with await), data literals, destructuring, optional chaining, template literals, conditionals, switch, loops (incl. for...of and for...in over object/array/tools keys), arrow functions, spread, try/catch, array methods (map/filter/find/findIndex/some/every/reduce/flatMap/forEach/sort/slice/concat/indexOf/lastIndexOf/at/flat/reverse/includes/join), string methods (incl. match/matchAll/replace/split with regular expressions), Date/RegExp/Map/Set/URL/URLSearchParams, URI encoding helpers, Object/Math/JSON helpers, captured console.log/warn/error/dir/table, Promise.all/allSettled/race/any/resolve/reject over arrays mixing promises and plain values for parallel tool calls, promise chaining with .then/.catch/.finally, and new Promise((resolve, reject) => ...) construction."
 
 export class InterpreterRuntimeError extends Error {
   readonly node?: AstNode
-  errorName: string = "Error"
+  errorName = "Error"
 
   constructor(
     message: string,

packages/codemode/src/interpreter/promises.ts

@@ -0,0 +1,336 @@
+import { Cause, Deferred, Effect, Exit, Fiber, Scope } from "effect"
+import type { Diagnostic } from "../codemode.js"
+import type { SafeObject } from "../tool-runtime.js"
+import {
+  type AstNode,
+  CodeModeFunction,
+  CoercionFunction,
+  InterpreterRuntimeError,
+  ProgramThrow,
+  PromiseCapabilityFunction,
+  PromiseInstanceMethodReference,
+  PromiseMethodReference,
+  UriFunction,
+} from "./model.js"
+import { caughtErrorValue, normalizeError } from "./errors.js"
+import { applyCollectionCallback, type CallbackRunner } from "./methods.js"
+import { typeofValue } from "./references.js"
+import { spreadItems } from "../stdlib/collections.js"
+import { createAggregateErrorValue } from "../stdlib/value.js"
+import { SandboxPromise } from "../values.js"
+
+// Observation only controls rejection reporting; program completion interrupts all promise work.
+export class PromiseRuntime<R> {
+  private readonly active = new Set<SandboxPromise>()
+  private readonly ids = new WeakMap<SandboxPromise, number>()
+  private readonly observed = new WeakSet<SandboxPromise>()
+  private readonly failures = new Map<number, Diagnostic>()
+  private nextID = 0
+
+  constructor(private readonly scope: Scope.Scope) {}
+
+  create(effect: Effect.Effect<unknown, unknown, R>): Effect.Effect<SandboxPromise, never, R> {
+    return Effect.suspend(() => {
+      // Allocate before forking so reruns get distinct IDs and diagnostics retain creation order.
+      const id = this.nextID++
+      return Effect.map(Effect.forkIn(effect, this.scope, { startImmediately: true }), (fiber) => {
+        const promise = new SandboxPromise(fiber)
+        this.active.add(promise)
+        this.ids.set(promise, id)
+        fiber.addObserver((exit) => {
+          this.active.delete(promise)
+          if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) || this.observed.has(promise)) {
+            this.ids.delete(promise)
+            return
+          }
+          const failure = normalizeError(Cause.squash(exit.cause))
+          this.failures.set(id, {
+            ...failure,
+            message: `Unhandled rejection from an un-awaited promise: ${failure.message}`,
+          })
+        })
+        return promise
+      })
+    })
+  }
+
+  // Observation must be recorded when responsibility transfers, before the consumer fiber runs.
+  markObserved(promise: SandboxPromise): void {
+    this.observed.add(promise)
+    const id = this.ids.get(promise)
+    this.ids.delete(promise)
+    if (id !== undefined) this.failures.delete(id)
+  }
+
+  await(promise: SandboxPromise): Effect.Effect<Exit.Exit<unknown, unknown>> {
+    return Fiber.await(promise.fiber)
+  }
+
+  diagnostics(): Array<Diagnostic> {
+    return [...this.failures].sort(([left], [right]) => left - right).map(([, failure]) => failure)
+  }
+
+  // Re-check because a straggler can create promises before its interruption lands.
+  interrupt(): Effect.Effect<Array<Diagnostic>> {
+    const self = this
+    return Effect.gen(function* () {
+      while (self.active.size > 0) {
+        yield* Fiber.interruptAll([...self.active].map((promise) => promise.fiber))
+      }
+      return self.diagnostics()
+    })
+  }
+}
+
+export const selfResolutionError = (node?: AstNode): InterpreterRuntimeError =>
+  new InterpreterRuntimeError("Chaining cycle detected: a promise cannot resolve with itself.", node).as("TypeError")
+
+export const invokePromiseMethod = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  ref: PromiseMethodReference,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  if (ref.name === "resolve") {
+    const value = args[0]
+    return value instanceof SandboxPromise ? Effect.succeed(value) : promises.create(Effect.succeed(value))
+  }
+  if (ref.name === "reject") {
+    return promises.create(Effect.fail(new ProgramThrow(args[0])))
+  }
+
+  const spread = spreadItems(args[0])
+  if (spread === undefined) {
+    return promises.create(
+      Effect.fail(
+        new InterpreterRuntimeError(
+          `Promise.${ref.name} expects an array of promises or plain values (e.g. Promise.${ref.name}(items.map((item) => tools.ns.tool(item)))).`,
+          node,
+        ).as("TypeError"),
+      ),
+    )
+  }
+  const items = Array.from(spread)
+
+  for (const item of items) {
+    if (item instanceof SandboxPromise) promises.markObserved(item)
+  }
+
+  switch (ref.name) {
+    case "all": {
+      const observations = items.map((item) =>
+        item instanceof SandboxPromise ? Effect.flatten(promises.await(item)) : Effect.succeed(item),
+      )
+      return promises.create(settleAfterTurn(Effect.all(observations, { concurrency: "unbounded" })))
+    }
+    case "allSettled": {
+      const observations = items.map((item) =>
+        item instanceof SandboxPromise ? promises.await(item) : Effect.succeed(Exit.succeed(item)),
+      )
+      return promises.create(
+        settleAfterTurn(
+          Effect.gen(function* () {
+            const outcomes: Array<unknown> = []
+            for (const observation of observations) {
+              const exit = yield* observation
+              if (Exit.isSuccess(exit)) {
+                outcomes.push(
+                  Object.assign(Object.create(null) as SafeObject, { status: "fulfilled", value: exit.value }),
+                )
+                continue
+              }
+              if (Cause.hasInterruptsOnly(exit.cause)) {
+                // Teardown interruption is not a program-level rejection.
+                return yield* Effect.failCause(exit.cause)
+              }
+              outcomes.push(
+                Object.assign(Object.create(null) as SafeObject, {
+                  status: "rejected",
+                  reason: caughtErrorValue(Cause.squash(exit.cause)),
+                }),
+              )
+            }
+            return outcomes
+          }),
+        ),
+      )
+    }
+    case "race": {
+      if (items.length === 0) {
+        return promises.create(
+          Effect.fail(
+            new InterpreterRuntimeError(
+              "Promise.race([]) would never settle; provide at least one promise or value.",
+              node,
+            ),
+          ),
+        )
+      }
+      const observations = items.map((item) =>
+        item instanceof SandboxPromise ? promises.await(item) : Effect.succeed(Exit.succeed(item)),
+      )
+      return promises.create(settleAfterTurn(Effect.flatten(Effect.raceAll(observations))))
+    }
+    case "any": {
+      const flipped = items.map((item) =>
+        item instanceof SandboxPromise
+          ? Effect.flatMap(promises.await(item), (exit) => {
+              if (Exit.isSuccess(exit)) return Effect.fail(new PromiseAnyFulfilled(exit.value))
+              if (Cause.hasInterruptsOnly(exit.cause)) return Effect.failCause(exit.cause)
+              return Effect.succeed(caughtErrorValue(Cause.squash(exit.cause)))
+            })
+          : Effect.fail(new PromiseAnyFulfilled(item)),
+      )
+      const body = Effect.all(flipped, { concurrency: "unbounded" }).pipe(
+        Effect.flatMap((reasons) =>
+          Effect.fail(new ProgramThrow(createAggregateErrorValue(reasons, "All promises were rejected"))),
+        ),
+        Effect.catch((error) =>
+          error instanceof PromiseAnyFulfilled ? Effect.succeed(error.value) : Effect.fail(error),
+        ),
+      )
+      return promises.create(settleAfterTurn(body))
+    }
+  }
+}
+
+export const invokePromiseInstanceMethod = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  ref: PromiseInstanceMethodReference,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, never, R> => {
+  const method = `Promise.prototype.${ref.name}`
+  promises.markObserved(ref.promise)
+  if (ref.name === "finally") {
+    return chainFinally(runner, promises, ref.promise, reactionHandler(args[0], method, node), method, node)
+  }
+  const onFulfilled = ref.name === "then" ? reactionHandler(args[0], method, node) : undefined
+  const onRejected = reactionHandler(ref.name === "then" ? args[1] : args[0], method, node)
+  return chainReaction(runner, promises, ref.promise, onFulfilled, onRejected, method, node)
+}
+
+export const constructPromise = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  executor: unknown,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, unknown, R> => {
+  if (!(executor instanceof CodeModeFunction)) {
+    throw new InterpreterRuntimeError(
+      "new Promise(...) expects an executor function (e.g. new Promise((resolve, reject) => { ... })).",
+      node,
+    ).as("TypeError")
+  }
+  return Effect.gen(function* () {
+    const deferred = Deferred.makeUnsafe<unknown, unknown>()
+    const box: { own?: SandboxPromise } = {}
+    const promise = yield* promises.create(
+      Effect.flatMap(Deferred.await(deferred), (value) => {
+        if (!(value instanceof SandboxPromise)) return Effect.succeed(value)
+        if (value === box.own) return Effect.fail(selfResolutionError(node))
+        return runner.settlePromise(value)
+      }),
+    )
+    box.own = promise
+    const resolve = new PromiseCapabilityFunction((value) => {
+      Deferred.doneUnsafe(deferred, Exit.succeed(value))
+    })
+    const reject = new PromiseCapabilityFunction((value) => {
+      Deferred.doneUnsafe(deferred, Exit.fail(new ProgramThrow(value)))
+    })
+    const executed = yield* Effect.exit(runner.invokeFunction(executor, [resolve, reject]))
+    if (!Exit.isSuccess(executed)) {
+      if (Cause.hasInterruptsOnly(executed.cause)) return yield* Effect.failCause(executed.cause)
+      Deferred.doneUnsafe(deferred, Exit.fail(Cause.squash(executed.cause)))
+    }
+    return promise
+  })
+}
+
+// Settle one reaction turn after the deciding member, after its existing reactions.
+const settleAfterTurn = <A, E, R>(body: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.flatMap(Effect.exit(body), (exit) => Effect.andThen(Effect.yieldNow, exit))
+
+class PromiseAnyFulfilled {
+  constructor(readonly value: unknown) {}
+}
+
+type ReactionHandler = CodeModeFunction | CoercionFunction | UriFunction | PromiseCapabilityFunction
+
+const reactionHandler = (value: unknown, method: string, node: AstNode): ReactionHandler | undefined => {
+  if (
+    value instanceof CodeModeFunction ||
+    value instanceof CoercionFunction ||
+    value instanceof UriFunction ||
+    value instanceof PromiseCapabilityFunction
+  ) {
+    return value
+  }
+  if (typeofValue(value) === "function") {
+    throw new InterpreterRuntimeError(
+      `${method} handlers must be plain functions; wrap other callables in an arrow function, e.g. (value) => tools.ns.tool(value).`,
+      node,
+    )
+  }
+  return undefined
+}
+
+// Teardown bypasses handlers; settled reactions yield once so handlers never run inline.
+const reactionExit = <R>(
+  promises: PromiseRuntime<R>,
+  source: SandboxPromise,
+): Effect.Effect<Exit.Exit<unknown, unknown>, unknown, R> =>
+  Effect.gen(function* () {
+    const exit = yield* promises.await(source)
+    if (!Exit.isSuccess(exit) && Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause)
+    yield* Effect.yieldNow
+    return exit
+  })
+
+const chainReaction = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  source: SandboxPromise,
+  onFulfilled: ReactionHandler | undefined,
+  onRejected: ReactionHandler | undefined,
+  method: string,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, never, R> => {
+  const box: { derived?: SandboxPromise } = {}
+  const body = Effect.gen(function* () {
+    const exit = yield* reactionExit(promises, source)
+    const handler = Exit.isSuccess(exit) ? onFulfilled : onRejected
+    if (handler === undefined) return yield* exit
+    const input = Exit.isSuccess(exit) ? exit.value : caughtErrorValue(Cause.squash(exit.cause))
+    const result = yield* applyCollectionCallback(runner, handler, method, node)([input])
+    if (result === box.derived) return yield* Effect.fail(selfResolutionError(node))
+    if (result instanceof SandboxPromise) return yield* runner.settlePromise(result)
+    return result
+  })
+  return Effect.map(promises.create(body), (derived) => {
+    box.derived = derived
+    return derived
+  })
+}
+
+const chainFinally = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  source: SandboxPromise,
+  cleanup: ReactionHandler | undefined,
+  method: string,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, never, R> =>
+  promises.create(
+    Effect.gen(function* () {
+      const exit = yield* reactionExit(promises, source)
+      if (cleanup !== undefined) {
+        const result = yield* applyCollectionCallback(runner, cleanup, method, node)([])
+        if (result instanceof SandboxPromise) yield* runner.settlePromise(result)
+      }
+      return yield* exit
+    }),
+  )

packages/codemode/src/interpreter/references.ts

@@ -0,0 +1,99 @@
+import {
+  type AstNode,
+  CodeModeFunction,
+  CoercionFunction,
+  ErrorConstructorReference,
+  GlobalMethodReference,
+  GlobalNamespace,
+  InterpreterRuntimeError,
+  IntrinsicReference,
+  PromiseCapabilityFunction,
+  PromiseInstanceMethodReference,
+  PromiseMethodReference,
+  PromiseNamespace,
+  SearchFunction,
+  UriFunction,
+} from "./model.js"
+import { ToolReference } from "../tool-runtime.js"
+import { isSandboxValue, SandboxPromise } from "../values.js"
+
+export const isRuntimeReference = (value: unknown): boolean =>
+  value instanceof CodeModeFunction ||
+  value instanceof ToolReference ||
+  value instanceof IntrinsicReference ||
+  value instanceof GlobalNamespace ||
+  value instanceof GlobalMethodReference ||
+  value instanceof PromiseNamespace ||
+  value instanceof PromiseMethodReference ||
+  value instanceof PromiseInstanceMethodReference ||
+  value instanceof SandboxPromise ||
+  value instanceof CoercionFunction ||
+  value instanceof UriFunction ||
+  value instanceof SearchFunction ||
+  value instanceof PromiseCapabilityFunction ||
+  value instanceof ErrorConstructorReference ||
+  isSandboxValue(value)
+
+export const containsRuntimeReference = (value: unknown, seen = new Set<object>()): boolean => {
+  if (isRuntimeReference(value)) return true
+  if (value === null || typeof value !== "object") return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  const contains = Array.isArray(value)
+    ? value.some((item) => containsRuntimeReference(item, seen))
+    : Object.values(value).some((item) => containsRuntimeReference(item, seen))
+  seen.delete(value)
+  return contains
+}
+
+// Sandbox values are data here, not opaque interpreter references.
+export const containsOpaqueReference = (value: unknown, seen = new Set<object>()): boolean => {
+  if (isSandboxValue(value)) return false
+  if (isRuntimeReference(value)) return true
+  if (value === null || typeof value !== "object") return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  const contains = Array.isArray(value)
+    ? value.some((item) => containsOpaqueReference(item, seen))
+    : Object.values(value).some((item) => containsOpaqueReference(item, seen))
+  seen.delete(value)
+  return contains
+}
+
+// Reject cycles before mutation so later boundary walks remain safe.
+export const rejectCircularInsertion = (
+  container: object,
+  value: unknown,
+  label: string,
+  node: AstNode,
+  seen = new Set<object>(),
+): void => {
+  if (value === container)
+    throw new InterpreterRuntimeError(`${label} contains a circular value.`, node, "InvalidDataValue")
+  if (value === null || typeof value !== "object" || isRuntimeReference(value) || seen.has(value)) return
+  seen.add(value)
+  const items = Array.isArray(value) ? value : Object.values(value)
+  for (const item of items) rejectCircularInsertion(container, item, label, node, seen)
+  seen.delete(value)
+}
+
+export const typeofValue = (value: unknown): string => {
+  if (
+    value instanceof CodeModeFunction ||
+    value instanceof CoercionFunction ||
+    value instanceof IntrinsicReference ||
+    value instanceof GlobalMethodReference ||
+    value instanceof PromiseMethodReference ||
+    value instanceof PromiseInstanceMethodReference ||
+    value instanceof PromiseNamespace ||
+    value instanceof PromiseCapabilityFunction ||
+    value instanceof ErrorConstructorReference
+  )
+    return "function"
+  if (value instanceof UriFunction || value instanceof SearchFunction) return "function"
+  if (value instanceof ToolReference) return value.path.length > 0 ? "function" : "object"
+  if (value instanceof GlobalNamespace) {
+    return value.name === "Math" || value.name === "JSON" || value.name === "console" ? "object" : "function"
+  }
+  return typeof value
+}

packages/codemode/src/interpreter/scope.ts

@@ -0,0 +1,84 @@
+import { type AstNode, type Binding, InterpreterRuntimeError } from "./model.js"
+
+export class ScopeStack {
+  private readonly scopes: Array<Map<string, Binding>>
+
+  constructor(scopes: Array<Map<string, Binding>>) {
+    this.scopes = scopes
+  }
+
+  declare(name: string, value: unknown, mutable: boolean, node: AstNode): void {
+    const scope = this.current()
+
+    const existing = scope.get(name)
+    if (existing && existing.initialized !== false) {
+      throw new InterpreterRuntimeError(`Identifier '${name}' has already been declared.`, node)
+    }
+
+    scope.set(name, { mutable, value, initialized: true })
+  }
+
+  get(name: string, node: AstNode): unknown {
+    const binding = this.resolve(name)
+
+    if (!binding) {
+      throw new InterpreterRuntimeError(`Unknown identifier '${name}'.`, node).as("ReferenceError")
+    }
+
+    if (binding.initialized === false) {
+      throw new InterpreterRuntimeError(`Cannot access '${name}' before initialization.`, node).as("ReferenceError")
+    }
+
+    return binding.value
+  }
+
+  set(name: string, value: unknown, node: AstNode): unknown {
+    const binding = this.resolve(name)
+
+    if (!binding) {
+      throw new InterpreterRuntimeError(`Unknown identifier '${name}'.`, node).as("ReferenceError")
+    }
+
+    if (!binding.mutable) {
+      throw new InterpreterRuntimeError(`Cannot assign to constant '${name}'.`, node).as("TypeError")
+    }
+
+    binding.value = value
+    return value
+  }
+
+  resolve(name: string): Binding | undefined {
+    for (let index = this.scopes.length - 1; index >= 0; index -= 1) {
+      const scope = this.scopes[index]
+      const binding = scope?.get(name)
+
+      if (binding) {
+        return binding
+      }
+    }
+
+    return undefined
+  }
+
+  current(): Map<string, Binding> {
+    const scope = this.scopes[this.scopes.length - 1]
+
+    if (!scope) {
+      throw new InterpreterRuntimeError("Interpreter scope stack is empty.")
+    }
+
+    return scope
+  }
+
+  push(scope: Map<string, Binding> = new Map()): void {
+    this.scopes.push(scope)
+  }
+
+  pop(): void {
+    this.scopes.pop()
+  }
+
+  capture(): Array<Map<string, Binding>> {
+    return this.scopes.slice()
+  }
+}

packages/codemode/src/openapi/index.ts

@@ -31,10 +31,8 @@ export type {
 } from "./types.js"
 
 /**
- * Builds a CodeMode tool subtree from an OpenAPI 3.x document, one tool per
- * operation. Auth is resolved host-side via `auth.resolve` and never
- * model-visible. Tools require `HttpClient.HttpClient`; unrepresentable
- * operations land in `skipped`.
+ * Builds one CodeMode tool per representable OpenAPI 3.x operation. Auth remains host-side,
+ * tools require `HttpClient.HttpClient`, and unrepresentable operations land in `skipped`.
  */
 export const fromSpec = (options: Options): Result => {
   const document = options.spec

packages/codemode/src/openapi/runtime.ts

@@ -46,9 +46,7 @@ export const invoke = (plan: Plan, input: unknown): Effect.Effect<unknown, unkno
       )
     }
     if (json && Option.isNone(decoded)) {
-      return yield* Effect.fail(
-        toolError(`${plan.operation.method} ${plan.operation.path} returned malformed JSON.`),
-      )
+      return yield* Effect.fail(toolError(`${plan.operation.method} ${plan.operation.path} returned malformed JSON.`))
     }
     return parsed
   })
@@ -58,7 +56,7 @@ const buildRequest = (
   input: Readonly<Record<string, unknown>>,
 ): Effect.Effect<HttpClientRequest.HttpClientRequest, ToolError> =>
   Effect.gen(function* () {
-    // Validate every model-controlled value before auth resolution, which may refresh tokens.
+    // Validate model input before auth resolution can refresh credentials.
     const url = buildUrl(plan, input)
     if (url instanceof ToolError) return yield* Effect.fail(url)
     const missing = plan.fields.find(
@@ -79,7 +77,6 @@ const buildRequest = (
       request = serialized
     }
 
-    // Host headers first, then declared header parameters.
     request = HttpClientRequest.setHeaders(request, plan.headers)
     for (const field of plan.fields) {
       if (field.location !== "header") continue
@@ -171,7 +168,7 @@ const applyCredentials = (
       continue
     }
     if (credential.type === "basic") {
-      // Buffer instead of btoa: btoa throws on non-Latin-1 credentials.
+      // Basic auth credentials are UTF-8; btoa rejects non-Latin-1 input.
       const duplicate = add(
         "header",
         "authorization",
@@ -185,7 +182,6 @@ const applyCredentials = (
       if (duplicate !== undefined) return duplicate
       continue
     }
-    // apiKey: the carrier comes from the scheme declaration.
     if (definition.type !== "apiKey") {
       return toolError(
         `Security scheme '${name}' is not an apiKey scheme; resolve a bearer, basic, or header credential for it.`,
@@ -208,13 +204,13 @@ const buildUrl = (plan: Plan, input: Readonly<Record<string, unknown>>): string
       return toolError(`Missing required path parameter '${field.inputName}'.`)
     }
     const fieldValue = serializeSimple(field, item, (value) =>
-      encodeURIComponent(value).replace(/[!'()*]/g, (character) =>
-        `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+      encodeURIComponent(value).replace(
+        /[!'()*]/g,
+        (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
       ),
     )
     if (fieldValue instanceof ToolError) return fieldValue
-    // '.'/'..' survive encoding and URL normalization collapses them, letting a
-    // model-supplied value retarget the request to a different endpoint.
+    // URL normalization collapses encoded `.` and `..`, which could retarget the request.
     if (fieldValue === "" || fieldValue === "." || fieldValue === "..") {
       return toolError(`Invalid path parameter '${field.inputName}'.`)
     }
@@ -271,10 +267,7 @@ const serializeQuery = (
     if (value.some((item) => item === undefined || (item !== null && typeof item === "object"))) {
       return toolError(`Query parameter '${field.inputName}' contains an unsupported nested value.`)
     }
-    return value.reduce(
-      (current, item) => HttpClientRequest.appendUrlParam(current, field.name, String(item)),
-      request,
-    )
+    return value.reduce((current, item) => HttpClientRequest.appendUrlParam(current, field.name, String(item)), request)
   }
   if (isRecord(value) && field.explode) {
     return Object.entries(value).reduce<HttpClientRequest.HttpClientRequest | ToolError>((current, [name, item]) => {
@@ -289,11 +282,15 @@ const serializeQuery = (
   return rendered instanceof ToolError ? rendered : HttpClientRequest.appendUrlParam(request, field.name, rendered)
 }
 
-const readResponseBody = (response: HttpClientResponse.HttpClientResponse, plan: Plan): Effect.Effect<string, ToolError> =>
+const readResponseBody = (
+  response: HttpClientResponse.HttpClientResponse,
+  plan: Plan,
+): Effect.Effect<string, ToolError> =>
   Effect.gen(function* () {
     const contentLength = response.headers["content-length"]
     const parsedSize = contentLength === undefined ? undefined : Number.parseInt(contentLength, 10)
-    const declaredSize = parsedSize !== undefined && Number.isSafeInteger(parsedSize) && parsedSize >= 0 ? parsedSize : undefined
+    const declaredSize =
+      parsedSize !== undefined && Number.isSafeInteger(parsedSize) && parsedSize >= 0 ? parsedSize : undefined
     if (declaredSize !== undefined && declaredSize > maxResponseBodyBytes) {
       return yield* Effect.fail(toolError(`${plan.operation.method} ${plan.operation.path} response exceeds 50 MiB.`))
     }
@@ -304,7 +301,9 @@ const readResponseBody = (response: HttpClientResponse.HttpClientResponse, plan:
         return Effect.fail(toolError(`${plan.operation.method} ${plan.operation.path} response exceeds 50 MiB.`))
       }
       if (size + chunk.byteLength > body.byteLength) {
-        const grown = Buffer.allocUnsafe(Math.min(maxResponseBodyBytes, Math.max(size + chunk.byteLength, body.byteLength * 2)))
+        const grown = Buffer.allocUnsafe(
+          Math.min(maxResponseBodyBytes, Math.max(size + chunk.byteLength, body.byteLength * 2)),
+        )
         body.copy(grown, 0, 0, size)
         body = grown
       }

packages/codemode/src/openapi/spec.ts

@@ -23,8 +23,7 @@ const asArray = (value: unknown): ReadonlyArray<unknown> => (Array.isArray(value
 export const nonEmptyString = (value: unknown): string | undefined =>
   typeof value === "string" && value !== "" ? value : undefined
 
-// Guards record lookups keyed by spec- or model-controlled names against
-// prototype-inherited values (e.g. a parameter named `toString`).
+// Spec- and model-controlled keys must not resolve inherited properties.
 export const own = <T>(record: Readonly<Record<string, T>>, key: string): T | undefined =>
   Object.hasOwn(record, key) ? record[key] : undefined
 
@@ -78,7 +77,9 @@ const isBinaryMediaType = (document: Document, mediaType: string, value: unknown
   return isRecord(schema) && schema.format === "binary"
 }
 
-const jsonContent = (content: Record<string, unknown>): { readonly mediaType: string; readonly schema: unknown } | undefined => {
+const jsonContent = (
+  content: Record<string, unknown>,
+): { readonly mediaType: string; readonly schema: unknown } | undefined => {
   const entry = Object.entries(content).find(([mediaType]) => isJsonMediaType(mediaType))
   return entry !== undefined && isRecord(entry[1]) ? { mediaType: entry[0], schema: entry[1].schema } : undefined
 }
@@ -104,7 +105,7 @@ const operationParameters = (
   pathItem: Record<string, unknown>,
   operation: Record<string, unknown>,
 ): Parsed<ReadonlyArray<PlannedField>> => {
-  // Operation-level parameters override path-level ones sharing (location, name).
+  // OpenAPI operation parameters override path parameters with the same location and name.
   const declared = new Map<
     string,
     { readonly name: string; readonly location: string; readonly parameter: Record<string, unknown> }
@@ -344,7 +345,7 @@ export const operationOutput = (
   if (outcomes.length === 0) return { ok: true, value: undefined }
   return {
     ok: true,
-    value: withDefinitions(outcomes.length === 1 ? outcomes[0] ?? {} : { anyOf: outcomes }, definitions),
+    value: withDefinitions(outcomes.length === 1 ? (outcomes[0] ?? {}) : { anyOf: outcomes }, definitions),
   }
 }
 
@@ -380,7 +381,9 @@ export const operationPath = (
   namespaces: ReadonlySet<string>,
 ): ReadonlyArray<string> => {
   const raw = nonEmptyString(operation.operationId)
-  const segments = (raw === undefined ? [fallbackOperationId(method, path)] : raw.split(".")).map(sanitizeOperationSegment)
+  const segments = (raw === undefined ? [fallbackOperationId(method, path)] : raw.split(".")).map(
+    sanitizeOperationSegment,
+  )
   if (isOperationPathAvailable(segments, used, namespaces)) return segments
   const conflict = segments.slice(0, -1).findIndex((_, index) => used.has(segments.slice(0, index + 1).join(".")))
   if (conflict >= 0 && conflict + 1 < segments.length) {

packages/codemode/src/openapi/types.ts

@@ -22,9 +22,8 @@ export type SecurityScheme =
   | { readonly type: "openIdConnect" }
 
 /**
- * Credential material returned by a host auth resolver. The carrier for `apiKey`
- * comes from the scheme definition, not the credential. `header` is the escape
- * hatch for nonstandard schemes.
+ * Credential material returned by a host auth resolver. `apiKey` uses the scheme's carrier;
+ * `header` supports nonstandard schemes.
  */
 export type Credential =
   | { readonly type: "bearer"; readonly token: string }
@@ -33,9 +32,7 @@ export type Credential =
   | { readonly type: "header"; readonly name: string; readonly value: string }
 
 /**
- * Resolves credential material for one named security scheme at call time.
- * `undefined` means unavailable, try the next OR alternative; a failure aborts
- * the call rather than falling through.
+ * Resolves credentials at call time. `undefined` tries the next OR alternative; failure aborts.
  */
 export type AuthResolver = (context: {
   readonly name: string
@@ -74,9 +71,7 @@ export type Parsed<T> = { readonly ok: true; readonly value: T } | { readonly ok
 export type InputLocation = "path" | "query" | "header" | "body"
 
 export type InputField = {
-  /** Model-visible field name after cross-location collision handling. */
   readonly inputName: string
-  /** Original parameter or body-property name used on the wire. */
   readonly name: string
   readonly location: InputLocation
   readonly required: boolean
@@ -92,7 +87,6 @@ export type OperationInput = {
   readonly body: Body | undefined
 }
 
-/** One OR alternative: scheme name -> required scopes. Empty object = unauthenticated is acceptable. */
 export type SecurityRequirement = Readonly<Record<string, ReadonlyArray<string>>>
 
 export type Plan = {

packages/codemode/src/stdlib/console.ts

@@ -1,4 +1,122 @@
+import { containsOpaqueReference, containsRuntimeReference, isRuntimeReference } from "../interpreter/references.js"
+import { copyIn, copyOut } from "../tool-runtime.js"
+import {
+  isSandboxValue,
+  SandboxDate,
+  SandboxMap,
+  SandboxPromise,
+  SandboxRegExp,
+  SandboxSet,
+  SandboxURL,
+  SandboxURLSearchParams,
+} from "../values.js"
+import { boundedData, coerceToString } from "./value.js"
+
 export const consoleMethods = new Set(["log", "info", "debug", "warn", "error", "dir", "table"])
 
-/** Console formatting recursion ceiling; deeper values render as "...". */
-export const MAX_CONSOLE_DEPTH = 32
+const MAX_CONSOLE_DEPTH = 32
+
+export const formatConsoleMessage = (name: string, args: Array<unknown>): string => {
+  if (name === "dir") return args.length === 0 ? "undefined" : formatConsoleArgument(args[0])
+  if (name === "table") return formatConsoleTable(args[0], args[1])
+  const prefix = name === "warn" ? "[warn] " : name === "error" ? "[error] " : name === "debug" ? "[debug] " : ""
+  return `${prefix}${args.map((arg) => formatConsoleArgument(arg)).join(" ")}`
+}
+
+const formatConsoleArgument = (value: unknown): string => {
+  if (value === undefined) return "undefined"
+  if (typeof value === "string") return value
+  return formatConsoleValue(value, new Set(), 0)
+}
+
+const formatConsoleValue = (value: unknown, seen: Set<object>, depth: number): string => {
+  if (value === null || value === undefined) return "null"
+  if (typeof value === "string") return JSON.stringify(value)
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  if (typeof value !== "object") return String(value)
+  if (value instanceof SandboxPromise) return "[Promise (await it to get its value)]"
+  if (value instanceof SandboxDate) return coerceToString(value)
+  if (value instanceof SandboxRegExp) return coerceToString(value)
+  if (value instanceof SandboxURL) return coerceToString(value)
+  if (value instanceof SandboxURLSearchParams) return coerceToString(value)
+  if (depth > MAX_CONSOLE_DEPTH) return "..."
+  if (seen.has(value)) return "[Circular]"
+  if (value instanceof SandboxMap) {
+    seen.add(value)
+    try {
+      const entries = Array.from(value.map.entries(), ([key, item]): Array<unknown> => [key, item])
+      return `Map(${value.map.size}) ${formatConsoleValue(entries, seen, depth + 1)}`
+    } finally {
+      seen.delete(value)
+    }
+  }
+  if (value instanceof SandboxSet) {
+    seen.add(value)
+    try {
+      return `Set(${value.set.size}) ${formatConsoleValue(Array.from(value.set.values()), seen, depth + 1)}`
+    } finally {
+      seen.delete(value)
+    }
+  }
+  if (isRuntimeReference(value)) return "[CodeMode reference]"
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => formatConsoleValue(item, seen, depth + 1)).join(",")}]`
+    }
+    return `{${Object.entries(value)
+      .map(([key, item]) => `${JSON.stringify(key)}:${formatConsoleValue(item, seen, depth + 1)}`)
+      .join(",")}}`
+  } finally {
+    seen.delete(value)
+  }
+}
+
+const formatConsoleTable = (value: unknown, columnsArgument: unknown): string => {
+  if (value === undefined) return "undefined"
+  if (containsOpaqueReference(value)) return "[CodeMode reference]"
+  const data = boundedData(value, "console.table argument")
+  const columns = consoleTableColumns(columnsArgument)
+  const rows = consoleTableRows(data, columns)
+  const keys = columns ?? Array.from(new Set(rows.flatMap((row) => Object.keys(row.values))))
+  const header = ["(index)", ...keys].join("\t")
+  return [
+    header,
+    ...rows.map((row) => [row.index, ...keys.map((key) => formatConsoleTableCell(row.values[key]))].join("\t")),
+  ].join("\n")
+}
+
+const consoleTableColumns = (value: unknown): ReadonlyArray<string> | undefined => {
+  if (value === undefined) return undefined
+  if (containsRuntimeReference(value)) return undefined
+  const columns = copyOut(copyIn(value, "console.table columns"), true)
+  return Array.isArray(columns) ? columns.map((column) => String(column)) : undefined
+}
+
+const consoleTableRows = (
+  data: unknown,
+  columns: ReadonlyArray<string> | undefined,
+): Array<{ readonly index: string; readonly values: Record<string, unknown> }> => {
+  if (Array.isArray(data)) {
+    return data.map((item, index) => ({ index: String(index), values: consoleTableValues(item, columns) }))
+  }
+  if (data !== null && typeof data === "object" && !isSandboxValue(data)) {
+    return Object.entries(data).map(([index, item]) => ({ index, values: consoleTableValues(item, columns) }))
+  }
+  return [{ index: "0", values: { Value: data } }]
+}
+
+const consoleTableValues = (value: unknown, columns: ReadonlyArray<string> | undefined): Record<string, unknown> => {
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && !isSandboxValue(value)) {
+    const source = value as Record<string, unknown>
+    if (columns !== undefined) return Object.fromEntries(columns.map((column) => [column, source[column]]))
+    return Object.fromEntries(Object.entries(source))
+  }
+  return { Value: value }
+}
+
+const formatConsoleTableCell = (value: unknown): string => {
+  if (value === undefined) return ""
+  if (typeof value === "string") return value
+  return formatConsoleValue(value, new Set(), 0)
+}

packages/codemode/src/stdlib/date.ts

@@ -23,8 +23,6 @@ export const dateMethods = new Set([
   "getTimezoneOffset",
 ])
 
-export const dateStatics = new Set(["now", "parse", "UTC"])
-
 export const invokeDateStatic = (name: string, args: Array<unknown>, node: AstNode): number => {
   switch (name) {
     case "now":

packages/codemode/src/stdlib/json.ts

@@ -6,10 +6,7 @@ import {
 } from "../interpreter/model.js"
 import { copyIn, copyOut } from "../tool-runtime.js"
 
-export const jsonStatics = new Set(["stringify", "parse"])
-
 export const invokeJsonMethod = (name: string, args: Array<unknown>, node: AstNode): unknown => {
-  if (!jsonStatics.has(name)) throw new InterpreterRuntimeError(`JSON.${name} is not available in CodeMode.`, node)
   switch (name) {
     case "stringify": {
       const replacer = args[1]

packages/codemode/src/stdlib/object.ts

@@ -3,11 +3,9 @@ import { isBlockedMember } from "../tool-runtime.js"
 import { isSandboxValue, SandboxMap, SandboxPromise, SandboxSet, SandboxURLSearchParams } from "../values.js"
 import { boundedData, coerceToString } from "./value.js"
 
-export const objectStatics = new Set(["keys", "values", "entries", "hasOwn", "assign", "fromEntries"])
 export const objectMethodsPreservingIdentity = new Set(["assign", "values", "entries", "fromEntries"])
 
 export const invokeObjectMethod = (name: string, args: Array<unknown>, node: AstNode): unknown => {
-  if (!objectStatics.has(name)) throw new InterpreterRuntimeError(`Object.${name} is not available in CodeMode.`, node)
   const requireObject = (): Record<string, unknown> => {
     const input = args[0]
     if (Array.isArray(input)) return input as unknown as Record<string, unknown>
@@ -53,13 +51,11 @@ export const invokeObjectMethod = (name: string, args: Array<unknown>, node: Ast
       }
       const out = target as Record<string, unknown>
       for (const source of args.slice(1)) {
-        if (source === null || source === undefined) continue
-        const value = source
-        if (isSandboxValue(value)) continue
-        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        if (source === null || source === undefined || isSandboxValue(source)) continue
+        if (typeof source !== "object" || Array.isArray(source)) {
           throw new InterpreterRuntimeError("Object.assign expects data objects.", node)
         }
-        for (const [key, item] of Object.entries(value)) guardedSet(out, key, item)
+        for (const [key, item] of Object.entries(source)) guardedSet(out, key, item)
       }
       return out
     }

packages/codemode/src/stdlib/promise.ts

@@ -1,6 +1,3 @@
 import type { PromiseMethodName } from "../interpreter/model.js"
 
-export const promiseStatics = new Set<PromiseMethodName>(["all", "allSettled", "race", "resolve", "reject"])
-
-/** Maximum number of eagerly forked tool calls that may run concurrently. */
-export const TOOL_CALL_CONCURRENCY = 8
+export const promiseStatics = new Set<PromiseMethodName>(["all", "allSettled", "race", "any", "resolve", "reject"])

packages/codemode/src/stdlib/string.ts

@@ -4,12 +4,9 @@ export const stringMethods = new Set([
   "trim",
   "trimStart",
   "trimEnd",
-  "trimLeft",
-  "trimRight",
   "split",
   "slice",
   "substring",
-  "substr",
   "includes",
   "startsWith",
   "endsWith",

packages/codemode/src/stdlib/value.ts

@@ -6,6 +6,7 @@ export const errorConstructors = new Set([
   "ReferenceError",
   "EvalError",
   "URIError",
+  "AggregateError",
 ])
 
 export const valueConstructors = new Set(["Date", "RegExp", "Map", "Set", "URL", "URLSearchParams"])
@@ -20,6 +21,9 @@ export const createErrorValue = (name: string, message: string): SafeObject => {
   return value
 }
 
+export const createAggregateErrorValue = (errors: Array<unknown>, message: string): SafeObject =>
+  Object.assign(createErrorValue("AggregateError", message), { errors })
+
 export const errorBrandName = (value: unknown): string | undefined =>
   value !== null && typeof value === "object"
     ? ((value as Record<PropertyKey, unknown>)[ErrorBrand] as string | undefined)
@@ -60,7 +64,7 @@ export const invokeCoercion = (ref: CoercionFunction, args: Array<unknown>, node
     if (ref.name === "parseInt") return parseInt(coerceToString(raw))
     return parseFloat(coerceToString(raw))
   }
-  const value = boundedData(args[0], `${ref.name} input`)
+  const value = boundedData(raw, `${ref.name} input`)
   if (ref.name === "Number") return coerceToNumber(value)
   if (ref.name === "Boolean") return Boolean(value)
   if (ref.name === "parseInt") {
@@ -73,11 +77,7 @@ export const invokeCoercion = (ref: CoercionFunction, args: Array<unknown>, node
   if (ref.name === "parseFloat") return parseFloat(coerceToString(value))
   return coerceToString(value)
 }
-import {
-  type AstNode,
-  CoercionFunction,
-  InterpreterRuntimeError,
-} from "../interpreter/model.js"
+import { type AstNode, CoercionFunction, InterpreterRuntimeError } from "../interpreter/model.js"
 import { copyIn, type SafeObject } from "../tool-runtime.js"
 import {
   isSandboxValue,

packages/codemode/src/tool-runtime.ts

@@ -44,36 +44,30 @@ type ServicesOf<Tools, Depth extends ReadonlyArray<unknown>> = Depth["length"] e
           : ServicesOf<Tools[keyof Tools], [...Depth, unknown]>
         : never
 
-/** Minimal audit record retained for each admitted tool call. */
 export type ToolCall = {
   readonly name: string
 }
 
-/** Decoded tool call observed immediately before tool execution. */
 export type ToolCallStarted = {
   readonly index: number
   readonly name: string
   readonly input: unknown
 }
 
-/** Completed tool call observed immediately after tool execution settles. */
 export type ToolCallEnded = {
   readonly index: number
   readonly name: string
   readonly input: unknown
   readonly durationMs: number
   readonly outcome: "success" | "failure"
-  /** Model-safe failure message; present only when `outcome` is `"failure"`. */
   readonly message?: string
 }
 
-/** Non-throwing observation hooks fired around each admitted tool call. */
 export type ToolCallHooks<R = never> = {
   readonly onToolCallStart?: ((call: ToolCallStarted) => Effect.Effect<void, never, R>) | undefined
   readonly onToolCallEnd?: ((call: ToolCallEnded) => Effect.Effect<void, never, R>) | undefined
 }
 
-/** Model-visible description of one schema-backed tool. */
 export type ToolDescription = {
   readonly path: string
   readonly description: string
@@ -82,7 +76,6 @@ export type ToolDescription = {
 
 export type SafeObject = Record<string, unknown>
 
-const reservedNamespace = "$codemode"
 const defaultCatalogBudget = 2_000
 const defaultSearchLimit = 10
 const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0))
@@ -114,11 +107,6 @@ export class ToolReference {
   constructor(readonly path: ReadonlyArray<string>) {}
 }
 
-/**
- * Maximum nesting depth for values crossing a data boundary. Fixed (not a configurable
- * limit) purely because it produces a clearer diagnostic than a native stack-overflow
- * RangeError would.
- */
 const MAX_VALUE_DEPTH = 32
 
 export class ToolRuntimeError extends Error {
@@ -153,21 +141,7 @@ const blockedMemberNames = new Set(["__proto__", "constructor", "prototype"])
 
 export const isBlockedMember = (name: string): boolean => blockedMemberNames.has(name)
 
-/**
- * Validates and copies a value against the plain-data contract (depth, circularity, plain
- * objects only, blocked properties, data-only leaves).
- *
- * Two modes share the walk:
- * - **Boundary** (`preserveSandboxValues` false, the default): the host<->sandbox boundary -
- *   final results, tool-call arguments, `JSON.stringify`. Sandbox value types serialize
- *   exactly as JSON.stringify would: Date/URL -> strings, the remaining value types -> {}.
- * - **Intra-sandbox checkpoint** (`preserveSandboxValues` true; see `boundedData` in
- *   codemode.ts): standard-library value instances pass through untouched (treated as leaves,
- *   contents not walked), so values flowing through `Object.*` helpers, coercion inputs, and
- *   other in-sandbox checkpoints stay fully usable (`.getTime()`, `.has()`, ...).
- *
- * Both modes reject un-awaited promises with an await-hinting diagnostic.
- */
+// Checkpoint mode preserves sandbox values; boundary mode JSON-normalizes them.
 export const copyIn = (value: unknown, label: string, preserveSandboxValues = false): unknown =>
   copyBounded(value, label, 0, new Set(), preserveSandboxValues)
 
@@ -186,10 +160,6 @@ const copyBounded = (
     value === undefined ||
     typeof value === "string" ||
     typeof value === "boolean" ||
-    // NaN/Infinity are allowed to exist as in-sandbox intermediates (matching real JS and a real
-    // engine) so defensive guards like `Number.isNaN(x)` / `parseInt(x) || 0` can run. They are
-    // normalized to `null` when the value leaves the sandbox - see copyOut - exactly as
-    // JSON.stringify already does at any tool boundary.
     typeof value === "number"
   ) {
     return value
@@ -199,8 +169,6 @@ const copyBounded = (
     throw new ToolRuntimeError("InvalidDataValue", `${label} must contain data only.`)
   }
 
-  // An un-awaited promise never crosses a data checkpoint as `{}`; the diagnostic tells the
-  // model exactly how to fix the program instead.
   if (value instanceof SandboxPromise) {
     throw new ToolRuntimeError(
       "InvalidDataValue",
@@ -209,9 +177,6 @@ const copyBounded = (
   }
 
   if (preserveSandboxValues) {
-    // Intra-sandbox checkpoints keep sandbox value instances alive as leaves; their contents
-    // are never walked here (Map/Set members are validated where mutation happens, and the
-    // real boundary still serializes them below).
     if (
       value instanceof SandboxDate ||
       value instanceof SandboxRegExp ||
@@ -222,8 +187,6 @@ const copyBounded = (
     ) {
       return value
     }
-    // Host instances cannot normally reach an intra-sandbox checkpoint (tool results cross
-    // the boundary first), but wrap them defensively rather than degrading to JSON forms.
     if (value instanceof Date) return new SandboxDate(value.getTime())
     if (value instanceof RegExp) return new SandboxRegExp(value.source, value.flags)
     if (value instanceof Map) {
@@ -242,9 +205,6 @@ const copyBounded = (
     if (value instanceof URLSearchParams) return new SandboxURLSearchParams(new URLSearchParams(value))
   }
 
-  // Sandbox value types (and their host counterparts, which a host tool may legitimately
-  // return) serialize exactly as JSON.stringify would at the data boundary: Date/URL use
-  // toJSON(), while RegExp/Map/Set/URLSearchParams have no JSON form beyond {}.
   if (value instanceof SandboxDate) {
     return Number.isFinite(value.time) ? new Date(value.time).toISOString() : null
   }
@@ -275,7 +235,7 @@ const copyBounded = (
   if (Array.isArray(value)) {
     const copied = value.map((item) => copyBounded(item, label, depth + 1, seen, preserveSandboxValues))
     if (preserveSandboxValues) {
-      // Array metadata is not serialized, but intra-sandbox copies must retain it.
+      // Checkpoint copies retain array metadata that boundary copies omit.
       for (const [key, item] of Object.entries(value)) {
         if (Object.hasOwn(copied, key)) continue
         if (isBlockedMember(key)) {
@@ -306,9 +266,6 @@ const copyBounded = (
 
 export const copyOut = (value: unknown, undefinedAsNull = false): unknown => {
   if (value === undefined && undefinedAsNull) return null
-  // Normalize non-finite numbers to null as the value crosses out of the sandbox (final return
-  // and tool-call arguments both funnel through here), matching JSON semantics - NaN/Infinity
-  // have no JSON representation, so JSON.stringify would produce null anyway.
   if (typeof value === "number" && !Number.isFinite(value)) {
     return null
   }
@@ -326,15 +283,12 @@ export const copyOut = (value: unknown, undefinedAsNull = false): unknown => {
 const definitions = <R>(
   tools: HostTools<R>,
   path: ReadonlyArray<string> = [],
-): Array<{ path: string; definition: Definition<R> }> => {
-  const entries: Array<{ path: string; definition: Definition<R> }> = []
-  for (const [name, value] of Object.entries(tools)) {
+): Array<{ path: string; definition: Definition<R> }> =>
+  Object.entries(tools).flatMap(([name, value]) => {
     const next = [...path, name]
-    if (isDefinition(value)) entries.push({ path: next.join("."), definition: value })
-    else if (typeof value !== "function") entries.push(...definitions(value, next))
-  }
-  return entries
-}
+    if (isDefinition(value)) return [{ path: next.join("."), definition: value }]
+    return typeof value === "function" ? [] : definitions(value, next)
+  })
 
 const describeDefinition = <R>(path: string, definition: Definition<R>): ToolDescription => ({
   path,
@@ -349,9 +303,6 @@ const visibleDefinitions = <R>(tools: HostTools<R>) =>
     description: describeDefinition(path, definition),
   }))
 
-export const catalog = <R>(tools: HostTools<R>): ReadonlyArray<ToolDescription> =>
-  visibleDefinitions(tools).map(({ description }) => description)
-
 export type DiscoveryPlan = {
   readonly catalog: ReadonlyArray<ToolDescription>
   readonly instructions: string
@@ -360,18 +311,10 @@ export type DiscoveryPlan = {
 
 export type SearchEntry = {
   readonly description: ToolDescription
-  /** Top-level namespace (first path segment), matched by the search `namespace` option. */
   readonly namespace: string
-  /** Lowercased path + description + input property names/descriptions, for substring matching. */
   readonly searchText: string
 }
 
-/**
- * Split a query into lowercased search terms. camelCase boundaries are split
- * (`resolveLibrary` -> `resolve library`) and every non-alphanumeric character is a
- * separator, so `resolve-library-id`, `resolveLibraryId`, and `resolve library id` all
- * tokenize alike. Empties and the `*` wildcard are dropped.
- */
 const tokenize = (query: string): Array<string> =>
   query
     .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
@@ -379,13 +322,6 @@ const tokenize = (query: string): Array<string> =>
     .split(/[^a-z0-9]+/)
     .filter((term) => term.length > 0 && term !== "*")
 
-/**
- * A term plus its naive singular variants (trailing "s"/"es" stripped), so a plural
- * query term ("issues") still matches indexed text that only carries the singular
- * ("issue"). Matching is one-directional substring containment, so the variants are
- * needed only on the query side; scoring weights are unchanged - each field check
- * passes when ANY form matches.
- */
 const termForms = (term: string): Array<string> => {
   const forms = [term]
   if (term.endsWith("es") && term.length > 3) forms.push(term.slice(0, -2))
@@ -407,8 +343,6 @@ const makeSearchTool = (searchIndex: ReadonlyArray<SearchEntry>): Definition =>
         request.namespace === undefined
           ? searchIndex
           : searchIndex.filter((entry) => entry.namespace === request.namespace)
-      // A query that names one tool path exactly (canonical path or rendered JavaScript
-      // expression) is a lookup, not a search: return that tool alone.
       const trimmed = query.trim()
       const pathQuery = trimmed.startsWith("tools.") ? trimmed.slice("tools.".length) : trimmed
       const exact =
@@ -418,9 +352,6 @@ const makeSearchTool = (searchIndex: ReadonlyArray<SearchEntry>): Definition =>
               (entry) => entry.description.path === pathQuery || toolExpression(entry.description.path) === trimmed,
             )
       const terms = tokenize(query).map(termForms)
-      // Additive field-weighted scoring, summed across terms: exact path or path segment
-      // (20) > path substring (8) > description substring (4) > any searchable text,
-      // including input parameter names and descriptions (2).
       const ranked =
         exact !== undefined
           ? [exact]
@@ -458,10 +389,12 @@ const makeSearchTool = (searchIndex: ReadonlyArray<SearchEntry>): Definition =>
     }),
 })
 
-const searchDescription = describeDefinition(`${reservedNamespace}.search`, makeSearchTool([]))
+const searchSignature = (() => {
+  const definition = makeSearchTool([])
+  return `search(input: ${inputTypeScript(definition, true)}): ${outputTypeScript(definition, true)}`
+})()
 
 const catalogLine = (tool: ToolDescription) => {
-  // Keep the tool description concise; the full schema documentation remains in the signature.
   const line = tool.description.split("\n", 1)[0]!.trim()
   const description = line.length > 120 ? line.slice(0, 119) + "..." : line
   return description === "" ? `  - ${tool.signature}` : `  - ${tool.signature} // ${description}`
@@ -481,27 +414,10 @@ const toSearchEntry = <R>(path: string, definition: Definition<R>, description:
     .toLowerCase(),
 })
 
-/** The runtime search index over every described tool. Search is always registered. */
 export const searchIndex = <R>(tools: HostTools<R>): ReadonlyArray<SearchEntry> =>
   visibleDefinitions(tools).map(({ path, definition, description }) => toSearchEntry(path, definition, description))
 
-export const assertValidTools = <R>(tools: HostTools<R>): void => {
-  if (Object.hasOwn(tools, reservedNamespace)) {
-    throw new Error(`Tool namespace '${reservedNamespace}' is reserved for CodeMode discovery tools.`)
-  }
-}
-
-/**
- * Budgeted catalog: every namespace is always listed with its tool count; full call
- * signatures are inlined against the `catalogBudget` (estimated tokens,
- * chars/4) round-robin across namespaces - in each round (namespaces alphabetical), every
- * namespace still holding un-inlined tools attempts to place its next-cheapest line, and
- * a namespace whose next line does not fit is done while the others keep going - so every
- * namespace gets some representation before any namespace gets everything. The section
- * states exactly how comprehensive it is - overall (COMPLETE vs PARTIAL) and per
- * namespace. Namespace stub lines are never budgeted: every namespace appears with its
- * tool count even at budget 0.
- */
+// Budget signatures round-robin so every namespace remains visible.
 export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBudget): DiscoveryPlan => {
   if (!Number.isSafeInteger(catalogBudget) || catalogBudget < 0) {
     throw new RangeError("discovery.catalogBudget must be a non-negative safe integer")
@@ -518,12 +434,6 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
   }
   const ordered = [...namespaces].sort(([left], [right]) => left.localeCompare(right))
 
-  // Select which signatures fit the budget before emitting, so the list can state
-  // exactly how comprehensive it is. Round-robin fairness: in each round (namespaces
-  // alphabetical), every namespace still holding un-inlined tools tries to place its
-  // next-cheapest line against the shared budget; a namespace whose next line does not
-  // fit is done - the others keep going - so every namespace gets some representation
-  // before any namespace gets everything.
   const selections = ordered.map(([namespace, group]) => ({
     namespace,
     picked: new Set<ToolDescription>(),
@@ -555,23 +465,17 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
 
   const empty = described.length === 0
 
-  // Section order is deliberate: workflow first (the top is the least likely part of a long
-  // description to be truncated or skimmed away), then rules, then syntax, with the budgeted
-  // catalog at the bottom. Example call forms use placeholders - never a real or fabricated
-  // tool name - and show both dot and bracket notation so non-identifier names are not normalized.
   const intro = [
     empty
       ? "This is a restricted JavaScript language for calling tools, not a general-purpose runtime."
       : complete
-        ? "This is a restricted JavaScript language for calling tools, not a general-purpose runtime. Inside the confined interpreter, `tools` contains the Code Mode tools listed below and internal runtime tools; surrounding agent tools are not available."
-        : "This is a restricted JavaScript language for calling tools, not a general-purpose runtime. Inside the confined interpreter, `tools` contains the Code Mode tools listed or searchable below and internal runtime tools; surrounding agent tools are not available.",
+        ? "This is a restricted JavaScript language for calling tools, not a general-purpose runtime. Inside the confined interpreter, `tools` contains the Code Mode tools listed below; surrounding agent tools are not available."
+        : "This is a restricted JavaScript language for calling tools, not a general-purpose runtime. Inside the confined interpreter, `tools` contains the Code Mode tools listed or searchable below; surrounding agent tools are not available.",
     ...(empty
       ? []
       : ["Do not infer or normalize tool names; use only exact signatures shown below or returned by search."]),
   ]
 
-  // The search step exists only when search is advertised (PARTIAL catalog); a COMPLETE
-  // catalog already shows every signature, so step 1 picks from the list instead.
   const workflow = empty
     ? []
     : [
@@ -585,7 +489,7 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
               "3. Return only the fields you need from structured results; narrow unknown results before reading fields, and avoid returning large raw payloads.",
             ]
           : [
-              '1. If needed, discover tools: `return await tools.$codemode.search({ query: "<intent + key nouns>" })`.',
+              '1. If needed, discover tools with the built-in search function: `return search({ query: "<intent + key nouns>" })`.',
               "2. In the next execution, copy a returned path exactly, call it, and return only the needed fields.",
             ]),
       ]
@@ -597,16 +501,17 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
         "## Rules",
         "",
         complete
-          ? "- Only Code Mode tools listed here and internal runtime tools are available; surrounding agent tools are not implicitly exposed."
-          : "- Only Code Mode tools listed here or returned by `tools.$codemode.search` and internal runtime tools are available; surrounding agent tools are not implicitly exposed.",
+          ? "- Only Code Mode tools listed here are available; surrounding agent tools are not implicitly exposed."
+          : "- Only Code Mode tools listed here or returned by the built-in `search` function are available; surrounding agent tools are not implicitly exposed.",
         "- Filter, aggregate, and transform collections in code - never return them raw or call a tool per item across messages.",
         "- A result typed `Promise<unknown>` may be structured data or text. Before reading fields, check that it is a non-null object and not an array; otherwise handle the returned text or primitive directly.",
         '- Run independent calls in parallel: `await Promise.all(items.map((item) => tools.<namespace>.<tool>(item)))`, or use `tools.<namespace>["tool-name"](item)` when the listed signature uses bracket notation.',
+        "- Execution ends when the program returns; pending promises are interrupted, so await every call whose completion matters.",
         "- `Object.keys(tools)` lists namespaces; `Object.keys(tools.<namespace>)` lists its tools; `for...in` works on both.",
         ...(complete
           ? []
           : [
-              '- Browse one namespace: `await tools.$codemode.search({ query: "", namespace: "<name>" })`.',
+              '- Browse one namespace: `search({ query: "", namespace: "<name>" })`.',
               "- If search returns `next`, repeat the same search with `offset: next.offset`.",
             ]),
       ]
@@ -616,7 +521,7 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
     "## Language",
     "",
     "Use common JavaScript data operations, functions, control flow, selected standard-library methods, and awaited tool calls. Built-ins include Date, RegExp, Map, Set, URL, URLSearchParams, and URI encoding helpers.",
-    "Modules/imports, classes, generators, timers, fetch, eval, prototype access, unlisted methods, and promise chaining are unavailable. Use Code Mode tools for external operations. Use await with try/catch.",
+    "Modules/imports, classes, generators, timers, fetch, eval, prototype access, and unlisted methods are unavailable. Use Code Mode tools for external operations. Use await with try/catch.",
     "Prefer explicit `return`; otherwise only the final top-level expression becomes the result.",
     "Dates and URLs serialize to strings at data boundaries; Map/Set/RegExp/URLSearchParams serialize to `{}`.",
   ]
@@ -628,14 +533,12 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
     toolSection.push(
       complete
         ? "## Available tools (COMPLETE list - every tool is shown below with its full call signature)"
-        : `## Available tools (PARTIAL - ${totalShown} of ${described.length} shown; find the rest with tools.$codemode.search)`,
+        : `## Available tools (PARTIAL - ${totalShown} of ${described.length} shown; find the rest with search(...))`,
       "",
     )
     for (const [namespace, group] of ordered) {
       const picked = shown.get(namespace)!
       const count = `${group.length} tool${group.length === 1 ? "" : "s"}`
-      // Annotate only when a namespace is not fully shown, so a comprehensive
-      // namespace reads cleanly and a truncated one is unambiguous.
       const label =
         picked.size === group.length
           ? count
@@ -646,7 +549,7 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
       for (const tool of group) if (picked.has(tool)) toolSection.push(catalogLine(tool))
     }
     if (!complete) {
-      toolSection.push("", "Search returns complete callable signatures:", `- ${searchDescription.signature}`)
+      toolSection.push("", "Search returns complete callable signatures:", `- ${searchSignature}`)
     }
   }
 
@@ -658,13 +561,6 @@ export const prepare = <R>(tools: HostTools<R>, catalogBudget = defaultCatalogBu
   }
 }
 
-/**
- * The enumerable names at one node of the callable tool tree - namespace names at the root,
- * tool/namespace names below - powering `Object.keys(tools)` and `for...in` over tool
- * references. A callable tool is a leaf and enumerates as `[]` (like `Object.keys` of a
- * function in JS). An unknown path is an `UnknownTool` error pointing at the working
- * discovery idioms, mirroring how calling an unknown tool fails.
- */
 const namespaceKeys = <R>(tools: HostTools<R>, path: ReadonlyArray<string>): ReadonlyArray<string> => {
   let value: HostTool<R> | Definition<R> | HostTools<R> = tools
   for (const segment of path) {
@@ -675,7 +571,7 @@ const namespaceKeys = <R>(tools: HostTools<R>, path: ReadonlyArray<string>): Rea
       !Object.hasOwn(value, segment)
     ) {
       throw new ToolRuntimeError("UnknownTool", `Unknown tool namespace '${path.join(".")}'.`, [
-        "Object.keys(tools) lists the available namespaces; tools.$codemode.search({ query }) finds described tools.",
+        "Object.keys(tools) lists the available namespaces; search({ query }) finds described tools.",
       ])
     }
     value = value[segment] as HostTool<R> | Definition<R> | HostTools<R>
@@ -695,7 +591,7 @@ const resolve = <R>(tools: HostTools<R>, path: ReadonlyArray<string>): HostTool<
       !Object.hasOwn(value, segment)
     ) {
       throw new ToolRuntimeError("UnknownTool", `Unknown tool '${path.join(".")}'.`, [
-        "Use tools.$codemode.search({ query }) to find available described tools.",
+        "Use search({ query }) to find available described tools.",
       ])
     }
     value = value[segment] as HostTool<R> | Definition<R> | HostTools<R>
@@ -712,25 +608,20 @@ export type ToolRuntime<R = never> = {
   readonly root: ToolReference
   readonly calls: Array<ToolCall>
   readonly invoke: (path: ReadonlyArray<string>, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
-  /** Enumerable namespace/tool names at one node of the callable tool tree; see `namespaceKeys`. */
+  readonly search: (args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
   readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>
 }
 
 export const make = <R>(
   tools: HostTools<R>,
-  /** Undefined means unlimited tool calls. */
   maxToolCalls: number | undefined,
   searchIndex: ReadonlyArray<SearchEntry>,
   hooks?: ToolCallHooks<R>,
 ): ToolRuntime<R> => {
   const calls: Array<ToolCall> = []
-  const callableTools = {
-    ...tools,
-    [reservedNamespace]: { search: makeSearchTool(searchIndex) },
-  }
+  const searchTool = makeSearchTool(searchIndex)
 
-  // Wraps the settling portion of a tool call so onToolCallEnd observes success and failure
-  // symmetrically. Interruption (e.g. the execution timeout) fires neither outcome.
+  // End hooks observe settled success or failure; interruption emits neither outcome.
   const observeEnd = <A, E>(effect: Effect.Effect<A, E, R>, call: ToolCallStarted): Effect.Effect<A, E, R> => {
     const onEnd = hooks?.onToolCallEnd
     if (onEnd === undefined) return effect
@@ -763,52 +654,59 @@ export const make = <R>(
     calls.push(call)
   }
 
+  const recordAndObserve = (name: string, input: unknown) =>
+    Effect.sync(() => {
+      recordCall({ name })
+      return calls.length - 1
+    }).pipe(Effect.tap((index) => hooks?.onToolCallStart?.({ index, name, input }) ?? Effect.void))
+
+  const invokeDefinition = (name: string, tool: Definition<R>, externalArgs: Array<unknown>) =>
+    Effect.gen(function* () {
+      if (externalArgs.length !== 1)
+        throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects exactly one input object.`)
+      const input = yield* Effect.try({
+        try: () => decodeToolInput(tool, externalArgs[0]),
+        catch: (cause) =>
+          new ToolRuntimeError("InvalidToolInput", `Invalid input for tool '${name}': ${String(cause)}`),
+      })
+      const index = yield* recordAndObserve(name, input)
+      return yield* observeEnd(
+        Effect.gen(function* () {
+          const raw = yield* runHost(Effect.suspend(() => tool.run(input)))
+          const result = yield* Effect.try({
+            try: () => decodeToolOutput(tool, raw),
+            catch: () => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}'.`),
+          })
+          return yield* decodeOutput(result, name)
+        }),
+        { index, name, input },
+      )
+    })
+
   return {
     root: new ToolReference([]),
     calls,
-    keys: (path) => namespaceKeys(callableTools, path),
+    keys: (path) => namespaceKeys(tools, path),
+    search: (args) =>
+      Effect.suspend(() =>
+        invokeDefinition(
+          "search",
+          searchTool,
+          args.map((arg) => copyOut(copyIn(arg, "Arguments for tool 'search'"))),
+        ),
+      ),
     invoke: (path, args) =>
       Effect.gen(function* () {
         const name = path.join(".")
         const externalArgs = args.map((arg) => copyOut(copyIn(arg, `Arguments for tool '${name}'`)))
-        const call = { name }
-        const recordAndObserve = (input: unknown) =>
-          Effect.sync(() => {
-            recordCall(call)
-            return calls.length - 1
-          }).pipe(Effect.tap((index) => hooks?.onToolCallStart?.({ index, name, input }) ?? Effect.void))
-        const tool = resolve(callableTools, path)
-        let describedInput: unknown
-        if (isDefinition(tool)) {
-          if (externalArgs.length !== 1)
-            throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects exactly one input object.`)
-          describedInput = yield* Effect.try({
-            try: () => decodeToolInput(tool, externalArgs[0]),
-            catch: (cause) =>
-              new ToolRuntimeError("InvalidToolInput", `Invalid input for tool '${name}': ${String(cause)}`),
-          })
-        }
-        const input = isDefinition(tool) ? describedInput : externalArgs
-        const index = yield* recordAndObserve(input)
-        const currentCall = { index, name, input }
-        if (isDefinition(tool)) {
-          return yield* observeEnd(
-            Effect.gen(function* () {
-              const raw = yield* runHost(Effect.suspend(() => tool.run(describedInput)))
-              const result = yield* Effect.try({
-                try: () => decodeToolOutput(tool, raw),
-                catch: () => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}'.`),
-              })
-              return yield* decodeOutput(result, name)
-            }),
-            currentCall,
-          )
-        }
+        const tool = resolve(tools, path)
+        if (isDefinition(tool)) return yield* invokeDefinition(name, tool, externalArgs)
+        const index = yield* recordAndObserve(name, externalArgs)
         return yield* observeEnd(
           Effect.gen(function* () {
             return yield* decodeOutput(yield* runHost(Effect.suspend(() => tool(...externalArgs))), name)
           }),
-          currentCall,
+          { index, name, input: externalArgs },
         )
       }),
   }