refactor(cli): own Code Mode host wiring

Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>

.github/workflows/publish.yml

@@ -6,6 +6,7 @@ on:
     branches:
       - ci
       - dev
+      - v2
       - beta
       - fix/npm-native-binary-install
       - snapshot-*
@@ -31,6 +32,9 @@ permissions:
   contents: write
   packages: write
 
+env:
+  OPENCODE_CHANNEL: ${{ (github.ref_name == 'v2' && 'next') || '' }}
+
 jobs:
   version:
     runs-on: blacksmith-4vcpu-ubuntu-2404
@@ -122,7 +126,7 @@ jobs:
       - build-cli
       - version
     runs-on: blacksmith-4vcpu-windows-2025
-    if: github.repository == 'anomalyco/opencode'
+    if: github.repository == 'anomalyco/opencode' && github.ref_name != 'v2'
     env:
       AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
       AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
@@ -221,7 +225,7 @@ jobs:
     needs:
       - build-cli
       - version
-    if: github.repository == 'anomalyco/opencode'
+    if: github.repository == 'anomalyco/opencode' && github.ref_name != 'v2'
     continue-on-error: false
     env:
       AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
@@ -447,6 +451,7 @@ jobs:
           path: packages/opencode/dist
 
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        if: github.ref_name != 'v2'
         with:
           name: opencode-cli-signed-windows
           path: packages/opencode/dist

.github/workflows/test.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - dev
+      - v2
   pull_request:
   workflow_dispatch:
 
@@ -74,13 +75,9 @@ jobs:
         working-directory: packages/client
         run: bun run check:generated
 
-      - name: Run HttpApi exerciser gates
-        if: runner.os == 'Linux'
-        working-directory: packages/opencode
-        run: bun run test:httpapi
-
   e2e:
     name: e2e (${{ matrix.settings.name }})
+    if: github.ref_name != 'v2' && github.head_ref != 'v2'
     strategy:
       fail-fast: false
       matrix:

.github/workflows/typecheck.yml

@@ -2,9 +2,9 @@ name: typecheck
 
 on:
   push:
-    branches: [dev]
+    branches: [dev, v2]
   pull_request:
-    branches: [dev]
+    branches: [dev, v2]
   workflow_dispatch:
 
 jobs:

.gitignore

@@ -13,6 +13,7 @@ tmp
 dist
 ts-dist
 .turbo
+.typecheck-profiles
 **/.serena
 .serena/
 **/.omo

.opencode/skills/sample-skill/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: sample-skill
+description: Use when the user says sample skill, skill demo, or asks how an opencode SKILL.md should be structured; demonstrates a tiny project-local skill with practical assistant workflow guidance.
+---
+
+# Sample Skill
+
+This is a minimal project-local opencode skill. It exists as a reference for how a skill is structured and as a tiny reusable workflow the assistant can load when the user asks for a skill example.
+
+## When To Use
+
+- Use when the user asks for a sample skill or skill template.
+- Use when demonstrating the required `SKILL.md` frontmatter and body format.
+- Do not use for unrelated coding tasks just because a skill exists.
+
+## Workflow
+
+- Confirm the specific outcome the user wants if the request is ambiguous.
+- Inspect the relevant files before changing anything.
+- Make the smallest correct change.
+- Verify the result with a focused read, typecheck, test, or other lightweight check when available.
+- Summarize the changed files and any required restart or reload step.
+
+## Example Response Style
+
+When this skill is relevant, keep responses direct and actionable:
+
+```text
+I created a project-local skill at .opencode/skills/sample-skill/SKILL.md.
+Restart opencode for the new skill to be discovered by future sessions.
+```

AGENTS.md

@@ -1,6 +1,7 @@
 - To regenerate the legacy JavaScript SDK, run `./packages/sdk/js/script/build.ts`.
 - After changing the public Protocol or Server `HttpApi`, run `bun run generate` from `packages/client`. Do not edit `src/generated` or `src/generated-effect` directly.
 - Keep runtime dependencies directed from Schema to Core and Protocol, then from Core and Protocol to Server. Client runtime code may depend on Schema and Protocol but never Core or Server; `sdk-next` composes Client, Core, and Server.
+- Do not modify `packages/opencode` unless the user explicitly asks for V1 work. `packages/opencode` is the V1 implementation and is present for reference only. New implementation changes should land in the V2 package set: `packages/core`, `packages/cli`, `packages/server`, `packages/protocol`, `packages/schema`, and related generated client surfaces when required.
 - The default branch in this repo is `dev`.
 - Local `main` ref may not exist; use `dev` or `origin/dev` for diffs.
 
@@ -150,12 +151,15 @@ const table = sqliteTable("session", {
 
 ## V2 Session Core
 
+- 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_input` 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.
 - 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. Historical projected prompts lazily synthesize promoted inbox records during exact retry.
 - 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 `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 provider turn 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 step and reload projected history before durable continuation. 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 provider-turn 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 provider-turn allowance; a batch of steers resets it once.
+- 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 System Context algebra, registry, and built-ins in `src/system-context`; keep Context Source producers with their observed domains, and keep Session History selection plus Context Epoch persistence Session-owned.
+- 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.

CONTEXT.md

@@ -4,40 +4,47 @@ OpenCode sessions preserve durable conversational history while assembling the r
 
 ## Language
 
-**System Context**:
-The structured collection of contextual facts presented to the model as initial instructions and chronological updates.
-_Avoid_: System prompt
+**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 provider turn after applying the active compaction and **Context Epoch** cutoffs.
+The projected chronological conversation selected for a **Step** after applying the active compaction and **InstructionCheckpoint** baseline cutoffs.
 _Avoid_: Session Context
 
-**Context Source**:
-One independently observed typed value within the **System Context**, represented by a stable key, JSON codec, infallible loader, pure baseline/update renderers, and an optional removal renderer for dynamic sources.
+**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
 
-**System Context Registry**:
-The Location-scoped registry of ordered, scoped producers that contribute to the current **System Context**.
+**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.
 
-**Mid-Conversation System Message**:
-A durable chronological instruction that tells the model the newly effective state of a changed **Context Source**.
-_Avoid_: System update, system notification, raw text diff
+**InstructionDiscovery**:
+The Location-scoped service that observes ambient global and upward-project `AGENTS.md` files as one ordered aggregate **Instruction Source**.
 
-**Context Epoch**:
-The span during which one initially rendered **System Context** remains the immutable provider-cache baseline, ending at completed compaction, Session movement, or an incompatible context transition that requires a fresh baseline.
+**InstructionCheckpoint**:
+The Session-owned durable instruction baseline, baseline sequence, and `Instructions.Applied` record used to prepare later Steps.
 
-**Baseline System Context**:
-The full **System Context** rendered at the start of a **Context Epoch**.
+**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
 
-**Context Snapshot**:
-The overwriteable model-hidden JSON state used to compare each **Context Source** with the value last admitted to a provider turn.
+**Applied Instructions**:
+The overwriteable model-hidden `Instructions.Applied` record in **InstructionCheckpoint**, containing what the model was last told per **Instruction Source**.
 
-**Unavailable Context**:
-An expected temporary inability to observe a **Context Source** value; the runtime retains its prior effective state and emits no update, or omits it until first successfully loaded.
+**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 Provider-Turn Boundary**:
-The point immediately before a provider call, after durable input promotion and any required tool settlement, where context changes may be admitted chronologically.
+**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**.
@@ -45,11 +52,24 @@ A durable user input accepted into the Session inbox but not yet included in **S
 **Prompt Promotion**:
 The durable transition that removes an **Admitted Prompt** from pending input and appends its user message to **Session History**.
 
-**Provider Turn**:
-One request to a model provider and the response projected from that request.
+**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 **Provider Turns** until no immediate continuation remains. A Session Drain has no durable identity or transcript boundary.
+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.
@@ -87,52 +107,52 @@ _Avoid_: Response envelope
 
 ## Relationships
 
-- A **System Context** is an opaque carrier composed from zero or more **Context Sources**.
-- **Session History** contains projected conversational messages and admitted **Mid-Conversation System Messages**; the active **Baseline System Context** remains separate provider-request state.
-- The **System Context Registry** uses stable-keyed scoped contributions to assemble the current **System Context**; contributor removal naturally removes its sources at the next **Safe Provider-Turn Boundary**.
-- A changed **Context Source** may produce one **Mid-Conversation System Message** containing its newly effective state.
-- A **Mid-Conversation System Message** persists the exact combined rendered text sent to the model.
-- The current **Context Snapshot** advances atomically with the corresponding durable **Mid-Conversation System Message**.
-- A **Context Snapshot** stores one codec-encoded JSON value and, for removable dynamic sources, a pre-rendered removal message per stable **Context Source** key.
-- Changes from multiple **Context Sources** admitted at one safe boundary combine into one **Mid-Conversation System Message**.
-- Context changes are sampled and admitted lazily at a **Safe Provider-Turn Boundary**, never pushed asynchronously when their source changes.
-- At a **Safe Provider-Turn Boundary**, newly promoted user input or settled tool results precede any combined **Mid-Conversation System Message**.
+- **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 Provider-Turn Boundary** while the current **Session Drain** still requires continuation. Promoting any newly admitted user input resets the selected agent's provider-turn allowance; multiple prompts promoted at one boundary reset it once.
+- 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, provider attempts, and tool state rather than inventing an enclosing execution identity.
-- The first provider turn renders the latest complete **Baseline System Context** and initializes its **Context Snapshot** without emitting a redundant **Mid-Conversation System Message**; unavailable initial context blocks the turn instead of persisting an incomplete baseline.
-- Initial **System Context** preparation precedes the first durable input promotion so an unavailable baseline leaves that input pending and retryable; ordinary reconciliation remains after promotion.
-- Compaction starts a new **Context Epoch** with a freshly rendered **Baseline System Context** and **Context Snapshot**; prior **Mid-Conversation System Messages** remain durable audit history but leave projected model history.
-- A newly registered core or plugin-defined **Context Source** absent from the current snapshot emits its baseline rendering once at the next **Safe Provider-Turn Boundary**.
-- **Context Source** keys are stable and namespaced; duplicate keys fail composition. `SystemContext.combine(...)` preserves caller order; the **System Context Registry** evaluates producers concurrently and combines them in stable contribution-key order so rendered context remains deterministic.
-- Each **Context Source** loader returns one coherent typed value. `SystemContext.make(...)` hides that value type so differently typed sources compose uniformly. Its codec compares and stores that value; its pure renderers produce model-visible baseline, update, and removal text only when needed.
-- `SystemContext.initialize(...)` observes a composed **System Context** once and produces a fresh **Baseline System Context** with its **Context Snapshot**.
-- `SystemContext.reconcile(...)` observes a composed **System Context** once and returns exactly one next action: unchanged, updated, replacement ready, or replacement blocked.
-- `SystemContext.replace(...)` renders a fresh generation after completed compaction or another baseline-replacing transition; it reports replacement blocked while previously admitted context is unavailable.
-- **Unavailable Context** uses stale-while-revalidate semantics and is distinct from a successfully loaded absence, which may emit removal text.
-- Ordinary **Context Source** loaders return values directly; loaders that intentionally use stale-while-revalidate may explicitly return **Unavailable Context**.
-- Nested project instruction discovery after successful reads remains a follow-up; when implemented, discovered instructions must be admitted durably at the next **Safe Provider-Turn Boundary**.
-- Location-scoped services naturally re-resolve effective context when a moved session next runs in its destination location.
-- Moving a Session clears its active **Context Epoch**, so the destination must initialize a complete baseline before another prompt can promote.
-- Instruction discovery, source identity, persistence, and file loading belong to the instruction service; the **System Context** abstraction only composes effectful producers and renders loaded values.
-- The first instruction-service slice observes global and upward project `AGENTS.md` files as one ordered aggregate **Context Source** at each **Safe Provider-Turn Boundary**.
-- Built-in and instruction context producers register through the **System Context Registry** with stable contribution keys. Plugin-defined context registration and hot-reload lifecycle remain a follow-up built on the same scoped registry seam.
-- Selected-agent available-skill guidance is a **Context Source** composed with Location-wide registry sources immediately before Context Epoch admission. 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 provider turn starts. Changes admitted after that boundary apply to the next provider turn and do not restart the current turn.
-- Selected-agent available-skill guidance remains a **Context Source**. An agent switch that changes that guidance produces a **Mid-Conversation System Message** while preserving the current baseline.
-- Local tool authorization and pending permission requests retain the effective agent of the provider turn that issued the call; a later agent switch cannot change that call's policy.
-- Context source changes never wake idle sessions; the next naturally scheduled **Safe Provider-Turn Boundary** loads and compares current values lazily.
-- Once admitted, a **Mid-Conversation System Message** remains durable even if the following provider attempt fails and is replayed unchanged on retry.
-- **Mid-Conversation System Messages** remain durable Session-message history; normal user-facing transcript surfaces may hide them.
-- The date **Context Source** initially preserves host-local calendar-date behavior; a configured user timezone may replace that default later.
-- A **Context Epoch** begins with one immutable **Baseline System Context**.
-- A **Baseline System Context** is stored durably and reused verbatim across process restarts within its **Context Epoch**.
-- A **Baseline System Context** durably preserves the exact joined text used for the active provider-cache prefix.
-- Completed compaction starts a new **Context Epoch** on the next provider attempt, folding the current complete **System Context** into a fresh baseline and removing earlier **Mid-Conversation System Messages** from active model history.
-- A model/provider switch preserves the current **Context Epoch** and chronological conversation history; the new selection applies to the next provider turn.
-- **Native Continuation Metadata** remains in durable history. Provider-turn projection includes it only for a successful exact originating provider/model match; failed turns 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.
+- 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`.
@@ -175,16 +195,16 @@ _Avoid_: Response envelope
 - `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 conversational messages selected as Session context; it does not include or represent the complete provider request context, whose baseline system context and other contributions remain separate.
-- **Open question**: Should a future, separately named operation expose the complete provider request context, including baseline system context, selected source contributions, and context-epoch metadata?
+- `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(...)`; `SessionInput.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.
-- A **Mid-Conversation System Message** lowers to the provider's native chronological instruction role when supported and to a wrapped chronological fallback otherwise.
-- When the effective aggregate instruction set changes, its **Mid-Conversation System Message** includes the complete current ordered set and supersedes the prior aggregate value; when no ambient instructions remain, the message states that previously loaded instructions no longer apply.
+- 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.
@@ -217,9 +237,9 @@ Before stabilizing the client API:
 
 ## Example dialogue
 
-> **Dev:** "The date changed while the session was active. Should the **Mid-Conversation System Message** say what the old date was?"
-> **Domain expert:** "No. Emit the newly effective date so the agent can act on the current **System Context**."
+> **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 the assembled baseline system prompt arbitrarily, but V2 plugins do not yet expose an equivalent hook. Decide separately whether to port it, replace dynamic uses with plugin-defined **Context Sources**, or narrow its semantics.
+- 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.

package.json

@@ -2,18 +2,23 @@
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode",
   "description": "AI-powered development tool",
+  "version": "0.0.0",
   "private": true,
   "type": "module",
   "packageManager": "bun@1.3.14",
   "scripts": {
-    "dev": "bun run --cwd packages/opencode --conditions=browser src/index.ts",
+    "dev": "bun run --cwd packages/cli --conditions=browser src/index.ts",
     "dev:desktop": "bun --cwd packages/desktop dev",
     "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:storybook": "bun --cwd packages/storybook storybook",
     "lint": "oxlint",
-    "typecheck": "bun turbo typecheck",
+    "lint:effect-patterns": "ast-grep scan -c script/ast-grep/sgconfig.yml packages/core/src packages/server/src packages/protocol/src packages/cli/src",
+    "test:lint-rules": "ast-grep test -c script/ast-grep/sgconfig.yml",
+    "typecheck": "bun turbo typecheck --concurrency=3",
+    "typecheck:profile": "bun script/profile-typecheck.ts",
+    "typecheck:profile:packages": "bun script/profile-typecheck-packages.ts",
     "upgrade-opentui": "bun run script/upgrade-opentui.ts",
     "postinstall": "bun run --cwd packages/core fix-node-pty",
     "prepare": "husky",
@@ -94,6 +99,7 @@
   },
   "devDependencies": {
     "@actions/artifact": "5.0.1",
+    "@ast-grep/cli": "0.44.0",
     "@tsconfig/bun": "catalog:",
     "@types/mime-types": "3.0.1",
     "@typescript/native-preview": "catalog:",

packages/app/src/components/dialog-custom-provider.tsx

@@ -177,7 +177,7 @@ export function CustomProviderForm() {
   return (
     <div class="flex flex-col gap-6 px-2.5 pb-3 overflow-y-auto max-h-[60vh]">
       <div class="px-2.5 flex gap-4 items-center">
-        <ProviderIcon id="synthetic" class="size-5 shrink-0 icon-strong-base" />
+        <ProviderIcon id="session.synthetic" class="size-5 shrink-0 icon-strong-base" />
         <div class="text-16-medium text-text-strong">{language.t("provider.custom.title")}</div>
       </div>
 

packages/app/src/components/settings-providers.tsx

@@ -224,7 +224,7 @@ const SettingsProvidersContent: Component<{ onBack?: () => void }> = (props) =>
             >
               <div class="flex flex-col min-w-0">
                 <div class="flex flex-wrap items-center gap-x-3 gap-y-1">
-                  <ProviderIcon id="synthetic" class="size-5 shrink-0 icon-strong-base" />
+                  <ProviderIcon id="session.synthetic" class="size-5 shrink-0 icon-strong-base" />
                   <span class="text-14-medium text-text-strong">{language.t("provider.custom.title")}</span>
                   <Tag>{language.t("settings.providers.tag.custom")}</Tag>
                 </div>

packages/app/src/components/settings-v2/providers.tsx

@@ -221,7 +221,7 @@ export const SettingsProvidersV2: Component<{ onBack?: () => void }> = (props) =
             <div class="settings-v2-provider-row" data-component="custom-provider-section">
               <div class="settings-v2-provider-lead">
                 <ProviderIcon
-                  id="synthetic"
+                  id="session.synthetic"
                   width={PROVIDER_ICON_SIZE}
                   height={PROVIDER_ICON_SIZE}
                   class="settings-v2-provider-icon shrink-0"

packages/app/src/context/file/watcher.test.ts

@@ -7,7 +7,7 @@ describe("file watcher invalidation", () => {
     const refresh: string[] = []
     invalidateFromWatcher(
       {
-        type: "file.watcher.updated",
+        type: "filesystem.changed",
         properties: {
           file: "src/new.ts",
           event: "add",
@@ -32,7 +32,7 @@ describe("file watcher invalidation", () => {
 
     invalidateFromWatcher(
       {
-        type: "file.watcher.updated",
+        type: "filesystem.changed",
         properties: {
           file: "src/open.ts",
           event: "change",
@@ -63,7 +63,7 @@ describe("file watcher invalidation", () => {
 
     invalidateFromWatcher(
       {
-        type: "file.watcher.updated",
+        type: "filesystem.changed",
         properties: {
           file: "src",
           event: "change",
@@ -81,7 +81,7 @@ describe("file watcher invalidation", () => {
 
     invalidateFromWatcher(
       {
-        type: "file.watcher.updated",
+        type: "filesystem.changed",
         properties: {
           file: "src/file.ts",
           event: "change",
@@ -111,7 +111,7 @@ describe("file watcher invalidation", () => {
 
     invalidateFromWatcher(
       {
-        type: "file.watcher.updated",
+        type: "filesystem.changed",
         properties: {
           file: ".git/index.lock",
           event: "change",

packages/app/src/context/file/watcher.ts

@@ -16,7 +16,7 @@ type WatcherOps = {
 }
 
 export function invalidateFromWatcher(event: WatcherEvent, ops: WatcherOps) {
-  if (event.type !== "file.watcher.updated") return
+  if (event.type !== "filesystem.changed") return
   const props =
     typeof event.properties === "object" && event.properties ? (event.properties as Record<string, unknown>) : undefined
   const rawPath = typeof props?.file === "string" ? props.file : undefined

packages/app/src/context/server-sdk.test.ts

@@ -126,8 +126,9 @@ describe("enqueueServerEvent", () => {
 
     enqueue(partUpdated("old"))
     enqueue({
+      id: "event-delete",
       type: "session.deleted",
-      properties: { sessionID: "session", info: { id: "session" } },
+      properties: { sessionID: "session" },
     } as Event)
     enqueue(partUpdated("new"))
 

packages/app/src/pages/session.tsx

@@ -839,7 +839,7 @@ export default function Page() {
   )
 
   const stopVcs = sdk().event.listen((evt) => {
-    if (evt.details.type !== "file.watcher.updated") return
+    if (evt.details.type !== "filesystem.changed") return
     const props =
       typeof evt.details.properties === "object" && evt.details.properties
         ? (evt.details.properties as Record<string, unknown>)

packages/cli/AGENTS.md

@@ -0,0 +1,7 @@
+# V2 CLI and TUI development guide
+
+## Migration context
+
+- The TUI is being ported from legacy APIs to the new V2 APIs. New and migrated TUI behavior should use `sdk.client.v2` and the location-scoped data in `packages/tui/src/context/data.tsx` instead of adding dependencies on legacy sync state.
+- Preserve established TUI behavior unless the task intentionally changes it.
+- Load the `opencode-dev` skill before interactively running, debugging, or verifying opencode's V2 CLI, TUI, or server.

packages/cli/bin/opencode2.cjs

@@ -31,11 +31,11 @@ function run(target) {
 
 const envPath = process.env.OPENCODE_BIN_PATH
 const scriptDir = path.dirname(fs.realpathSync(__filename))
-const cached = path.join(scriptDir, ".lildax")
+const cached = path.join(scriptDir, ".opencode2")
 const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[os.platform()] || os.platform()
 const arch = { x64: "x64", arm64: "arm64", arm: "arm" }[os.arch()] || os.arch()
 const base = "@opencode-ai/cli-" + platform + "-" + arch
-const binary = platform === "windows" ? "lildax.exe" : "lildax"
+const binary = platform === "windows" ? "opencode2.exe" : "opencode2"
 
 function supportsAvx2() {
   if (arch !== "x64") return false
@@ -121,7 +121,7 @@ function findBinary(startDir) {
 const resolved = envPath || (fs.existsSync(cached) ? cached : findBinary(scriptDir))
 if (!resolved) {
   console.error(
-    "It seems that your package manager failed to install the right lildax CLI package. Try manually installing " +
+    "It seems that your package manager failed to install the right opencode2 CLI package. Try manually installing " +
       names.map((name) => `"${name}"`).join(" or ") +
       " package",
   )

packages/cli/package.json

@@ -5,32 +5,58 @@
   "type": "module",
   "license": "MIT",
   "bin": {
-    "lildax": "./bin/lildax.cjs"
+    "opencode2": "./bin/opencode2.cjs"
   },
   "files": [
     "bin"
   ],
+  "exports": {
+    "./daemon": "./src/daemon.ts",
+    "./mini": "./src/mini/index.ts",
+    "./mini/footer.command": "./src/mini/footer.command.tsx",
+    "./mini/footer.menu": "./src/mini/footer.menu.tsx",
+    "./mini/footer.permission": "./src/mini/footer.permission.tsx",
+    "./mini/footer.prompt": "./src/mini/footer.prompt.tsx",
+    "./mini/footer.question": "./src/mini/footer.question.tsx",
+    "./mini/footer.subagent": "./src/mini/footer.subagent.tsx",
+    "./mini/footer.view": "./src/mini/footer.view.tsx",
+    "./mini/scrollback.writer": "./src/mini/scrollback.writer.tsx",
+    "./mini/*": "./src/mini/*.ts",
+    "./server-process": "./src/server-process.ts"
+  },
   "scripts": {
     "build": "bun run script/build.ts",
     "dev": "bun run src/index.ts",
+    "test": "bun test --timeout 30000 --only-failures",
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
     "@effect/platform-node": "catalog:",
+    "@opencode-ai/client": "workspace:*",
+    "@opencode-ai/codemode": "workspace:*",
     "@opencode-ai/core": "workspace:*",
+    "@opencode-ai/plugin": "workspace:*",
+    "@opencode-ai/schema": "workspace:*",
     "@opencode-ai/sdk": "workspace:*",
     "@opencode-ai/server": "workspace:*",
     "@opencode-ai/tui": "workspace:*",
     "@opentui/core": "catalog:",
+    "@opentui/keymap": "catalog:",
     "@opentui/solid": "catalog:",
     "@parcel/watcher": "2.5.1",
     "effect": "catalog:",
-    "solid-js": "catalog:"
+    "fuzzysort": "catalog:",
+    "jsonc-parser": "3.3.1",
+    "opentui-spinner": "catalog:",
+    "semver": "catalog:",
+    "solid-js": "catalog:",
+    "strip-ansi": "7.1.2"
   },
   "devDependencies": {
     "@opencode-ai/script": "workspace:*",
     "@tsconfig/bun": "catalog:",
     "@types/bun": "catalog:",
+    "@types/semver": "catalog:",
     "@typescript/native-preview": "catalog:"
   }
 }

packages/cli/script/build.ts

@@ -10,7 +10,7 @@ import pkg from "../package.json"
 import { modelsData } from "./generate"
 
 const dir = path.resolve(import.meta.dirname, "..")
-const binary = "lildax"
+const binary = "opencode2"
 process.chdir(dir)
 
 await rm("dist", { recursive: true, force: true })
@@ -18,7 +18,6 @@ await rm("dist", { recursive: true, force: true })
 const singleFlag = process.argv.includes("--single")
 const baselineFlag = process.argv.includes("--baseline")
 const skipInstall = process.argv.includes("--skip-install")
-const sourcemapsFlag = process.argv.includes("--sourcemaps")
 const plugin = createSolidTransformPlugin()
 
 const allTargets: {
@@ -74,7 +73,7 @@ for (const item of targets) {
     external: ["node-gyp"],
     format: "esm",
     minify: true,
-    sourcemap: sourcemapsFlag ? "linked" : "none",
+    sourcemap: "inline",
     splitting: true,
     compile: {
       autoloadBunfig: false,

packages/cli/script/publish.ts

@@ -25,14 +25,15 @@ for (const filepath of new Bun.Glob("*/package.json").scanSync({ cwd: "./dist" }
 }
 console.log("binaries", binaries)
 const version = Object.values(binaries)[0]
+const name = pkg.name
 
-await $`mkdir -p ./dist/${pkg.name}/bin`
-await $`cp ./bin/lildax.cjs ./dist/${pkg.name}/bin/lildax`
-await Bun.file(`./dist/${pkg.name}/package.json`).write(
+await $`mkdir -p ./dist/${name}/bin`
+await $`cp ./bin/opencode2.cjs ./dist/${name}/bin/opencode2`
+await Bun.file(`./dist/${name}/package.json`).write(
   JSON.stringify(
     {
-      name: pkg.name,
-      bin: { lildax: "./bin/lildax" },
+      name,
+      bin: { opencode2: "./bin/opencode2" },
       version,
       license: pkg.license,
       repository: { type: "git", url: "git+https://github.com/anomalyco/opencode.git" },
@@ -50,4 +51,4 @@ await Promise.all(
     publish(`./dist/${name.replace("@opencode-ai/", "")}`, name, version),
   ),
 )
-await publish(`./dist/${pkg.name}`, pkg.name, version)
+await publish(`./dist/${name}`, name, version)

packages/cli/src/code-mode.ts

@@ -0,0 +1,66 @@
+export * as CodeModeHost from "./code-mode"
+
+import { NodeHttpClient } from "@effect/platform-node"
+import { LayerNode } from "@opencode-ai/core/effect/layer-node"
+import { ToolRegistry } from "@opencode-ai/core/tool/registry"
+import { OpenAPI, Tool } from "@opencode-ai/codemode"
+import { Api } from "@opencode-ai/server/api"
+import { ServerAuth } from "@opencode-ai/server/auth"
+import { Effect, Layer } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { OpenApi } from "effect/unstable/httpapi"
+import type { Server } from "node:http"
+
+export function replacements(server: Server, password: string): LayerNode.Replacements {
+  return [ToolRegistry.codeModeReplacement(makeTools(client(server), password))]
+}
+
+export function makeTools(client: Layer.Layer<HttpClient.HttpClient>, password: string): ToolRegistry.CodeModeTools {
+  return {
+    opencode: bindTools(
+      OpenAPI.fromSpec({
+        spec: { ...OpenApi.fromApi(Api) },
+        baseUrl: "http://opencode.local",
+        headers: ServerAuth.headers({ username: "opencode", password }),
+      }).tools,
+      client,
+    ),
+  }
+}
+
+function client(server: Server) {
+  return Layer.effect(
+    HttpClient.HttpClient,
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      return HttpClient.mapRequest(client, (request) => {
+        const address = server.address()
+        if (!address || typeof address === "string") throw new Error("OpenCode server is not listening")
+        const local =
+          address.address === "0.0.0.0" ? "127.0.0.1" : address.address === "::" ? "::1" : address.address
+        const host = local.includes(":") && !local.startsWith("[") ? `[${local}]` : local
+        const url = new URL(request.url)
+        return HttpClientRequest.setUrl(
+          request,
+          new URL(`${url.pathname}${url.search}${url.hash}`, `http://${host}:${address.port}`),
+        )
+      })
+    }),
+  ).pipe(Layer.provide(NodeHttpClient.layerNodeHttp))
+}
+
+function bindTools(tools: OpenAPI.Tools, client: Layer.Layer<HttpClient.HttpClient>): ToolRegistry.CodeModeTools {
+  return Object.fromEntries(
+    Object.entries(tools).map(([name, value]) => [
+      name,
+      Tool.isDefinition<HttpClient.HttpClient>(value)
+        ? Tool.make({
+            description: value.description,
+            input: value.input,
+            output: value.output,
+            run: (input) => value.run(input).pipe(Effect.provide(client)),
+          })
+        : bindTools(value, client),
+    ]),
+  )
+}

packages/cli/src/commands/commands.ts

@@ -3,8 +3,57 @@ import { Spec } from "../framework/spec"
 
 declare const OPENCODE_CLI_NAME: string | undefined
 
+const MiniParams = {
+  continue: Flag.boolean("continue").pipe(
+    Flag.withAlias("c"),
+    Flag.withDescription("Continue the last session"),
+    Flag.withDefault(false),
+  ),
+  session: Flag.string("session").pipe(
+    Flag.withAlias("s"),
+    Flag.withDescription("Session ID to continue"),
+    Flag.optional,
+  ),
+  fork: Flag.boolean("fork").pipe(
+    Flag.withDescription("Fork the session when continuing"),
+    Flag.withDefault(false),
+  ),
+  replay: Flag.boolean("replay").pipe(
+    Flag.withDescription("Replay session history on resume and after resize"),
+    Flag.withDefault(true),
+  ),
+  replayLimit: Flag.integer("replay-limit").pipe(
+    Flag.withDescription("Cap visible replay to the newest N messages"),
+    Flag.optional,
+  ),
+}
+
 export const Commands = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCODE_CLI_NAME : "opencode", {
   description: "OpenCode 2.0 preview command line interface",
+  params: {
+    directory: Argument.string("directory").pipe(
+      Argument.withDescription("Directory to start OpenCode in"),
+      Argument.optional,
+    ),
+    standalone: Flag.boolean("standalone").pipe(
+      Flag.withDescription("Run with a private server instead of the background service"),
+      Flag.withDefault(false),
+    ),
+    server: Flag.string("server").pipe(
+      Flag.withDescription("Connect to a server URL instead of the background service"),
+      Flag.optional,
+    ),
+    continue: Flag.boolean("continue").pipe(
+      Flag.withAlias("c"),
+      Flag.withDescription("Continue the last session"),
+      Flag.withDefault(false),
+    ),
+    session: Flag.string("session").pipe(
+      Flag.withAlias("s"),
+      Flag.withDescription("Session ID to continue"),
+      Flag.optional,
+    ),
+  },
   commands: [
     Spec.make("api", {
       description: "Make a request to the running server",
@@ -26,7 +75,124 @@ export const Commands = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCO
       description: "Debugging and troubleshooting tools",
       commands: [Spec.make("agents", { description: "List all agents" })],
     }),
+    Spec.make("mcp", {
+      description: "Manage MCP (Model Context Protocol) servers",
+      commands: [
+        Spec.make("list", { description: "List configured MCP servers and their status" }),
+        Spec.make("add", {
+          description: "Add an MCP server to your configuration",
+          params: {
+            name: Argument.string("name").pipe(Argument.withDescription("Name of the MCP server")),
+            command: Argument.string("command").pipe(
+              Argument.withDescription("Command and arguments for a local server, passed after --"),
+              Argument.variadic({ min: 0 }),
+            ),
+            url: Flag.string("url").pipe(Flag.withDescription("URL for a remote MCP server"), Flag.optional),
+            header: Flag.keyValuePair("header").pipe(
+              Flag.withDescription("HTTP header for a remote server, as name=value"),
+              Flag.optional,
+            ),
+            env: Flag.keyValuePair("env").pipe(
+              Flag.withDescription("Environment variable for a local server, as name=value"),
+              Flag.optional,
+            ),
+            global: Flag.boolean("global").pipe(
+              Flag.withDescription("Write to the global config instead of the project config"),
+              Flag.withDefault(false),
+            ),
+          },
+        }),
+        Spec.make("auth", {
+          description: "Authenticate with an OAuth-capable remote MCP server",
+          params: { name: Argument.string("name").pipe(Argument.withDescription("Name of the MCP server")) },
+        }),
+        Spec.make("logout", {
+          description: "Remove stored OAuth credentials for an MCP server",
+          params: { name: Argument.string("name").pipe(Argument.withDescription("Name of the MCP server")) },
+        }),
+      ],
+    }),
     Spec.make("migrate", { description: "Migrate v1 data to v2" }),
+    Spec.make("mini", {
+      description: "Start the minimal interactive interface",
+      params: {
+        ...MiniParams,
+        project: Argument.string("project").pipe(
+          Argument.withDescription("Path to start OpenCode in"),
+          Argument.optional,
+        ),
+        model: Flag.string("model").pipe(
+          Flag.withAlias("m"),
+          Flag.withDescription("Model to use in the format provider/model"),
+          Flag.optional,
+        ),
+        agent: Flag.string("agent").pipe(Flag.withDescription("Agent to use"), Flag.optional),
+        prompt: Flag.string("prompt").pipe(Flag.withDescription("Prompt to use"), Flag.optional),
+        server: Flag.string("server").pipe(
+          Flag.withDescription("Connect to a server URL instead of the background service"),
+          Flag.optional,
+        ),
+        demo: Flag.boolean("demo").pipe(Flag.withDefault(false), Flag.withHidden),
+      },
+    }),
+    Spec.make("run", {
+      description: "Run OpenCode with a message",
+      params: {
+        message: Argument.string("message").pipe(
+          Argument.withDescription("Message to send"),
+          Argument.variadic({ min: 0 }),
+        ),
+        continue: Flag.boolean("continue").pipe(
+          Flag.withAlias("c"),
+          Flag.withDescription("Continue the last session"),
+          Flag.withDefault(false),
+        ),
+        session: Flag.string("session").pipe(
+          Flag.withAlias("s"),
+          Flag.withDescription("Session ID to continue"),
+          Flag.optional,
+        ),
+        fork: Flag.boolean("fork").pipe(
+          Flag.withDescription("Fork the session before continuing"),
+          Flag.withDefault(false),
+        ),
+        model: Flag.string("model").pipe(
+          Flag.withAlias("m"),
+          Flag.withDescription("Model to use in the format provider/model"),
+          Flag.optional,
+        ),
+        agent: Flag.string("agent").pipe(Flag.withDescription("Agent to use"), Flag.optional),
+        format: Flag.choice("format", ["default", "json"]).pipe(
+          Flag.withDescription("Output format"),
+          Flag.withDefault("default"),
+        ),
+        file: Flag.string("file").pipe(
+          Flag.withAlias("f"),
+          Flag.withDescription("File to attach to the message"),
+          Flag.atMost(100),
+        ),
+        title: Flag.string("title").pipe(Flag.withDescription("Session title"), Flag.optional),
+        server: Flag.string("server").pipe(
+          Flag.withDescription("Connect to a server URL instead of the background service"),
+          Flag.optional,
+        ),
+        dir: Flag.string("dir").pipe(Flag.withDescription("Directory to run in"), Flag.optional),
+        variant: Flag.string("variant").pipe(Flag.withDescription("Model variant"), Flag.optional),
+        thinking: Flag.boolean("thinking").pipe(
+          Flag.withDescription("Show thinking blocks"),
+          Flag.withDefault(false),
+        ),
+        auto: Flag.boolean("auto").pipe(
+          Flag.withDescription("Auto-approve permissions that are not explicitly denied"),
+          Flag.withDefault(false),
+        ),
+        yolo: Flag.boolean("yolo").pipe(Flag.withDefault(false), Flag.withHidden),
+        dangerouslySkipPermissions: Flag.boolean("dangerously-skip-permissions").pipe(
+          Flag.withDefault(false),
+          Flag.withHidden,
+        ),
+      },
+    }),
     Spec.make("service", {
       description: "Manage the background server",
       commands: [
@@ -34,18 +200,27 @@ export const Commands = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCO
         Spec.make("restart", { description: "Restart the background server" }),
         Spec.make("status", { description: "Show background server status" }),
         Spec.make("stop", { description: "Stop the background server" }),
-        Spec.make("password", {
-          description: "Get or set the server password",
-          params: { value: Argument.string("value").pipe(Argument.optional) },
+        Spec.make("get", {
+          description: "Get service configuration",
+          params: { key: Argument.string("key").pipe(Argument.optional) },
+        }),
+        Spec.make("set", {
+          description: "Set service configuration",
+          params: { key: Argument.string("key"), value: Argument.string("value") },
+        }),
+        Spec.make("unset", {
+          description: "Unset service configuration",
+          params: { key: Argument.string("key") },
         }),
       ],
     }),
     Spec.make("serve", {
       description: "Start the v2 API server",
       params: {
-        hostname: Flag.string("hostname").pipe(Flag.withDefault("127.0.0.1")),
+        hostname: Flag.string("hostname").pipe(Flag.optional),
         port: Flag.integer("port").pipe(Flag.optional),
-        register: Flag.boolean("register").pipe(Flag.withDefault(false)),
+        service: Flag.boolean("service").pipe(Flag.withDefault(false)),
+        stdio: Flag.boolean("stdio").pipe(Flag.withDefault(false)),
       },
     }),
   ],

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

@@ -2,7 +2,8 @@ import { EOL } from "node:os"
 import { Effect, Option } from "effect"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
-import { Daemon } from "../../services/daemon"
+import { Service } from "@opencode-ai/client/effect"
+import { ServiceConfig } from "../../services/service-config"
 
 const methods = new Set(["delete", "get", "head", "options", "patch", "post", "put"])
 
@@ -17,8 +18,9 @@ type OpenApi = {
 export default Runtime.handler(
   Commands.commands.api,
   Effect.fn("cli.api")(function* (input) {
-    const daemon = yield* Daemon.Service
-    const transport = yield* daemon.transport()
+    const options = yield* ServiceConfig.options()
+    const found = yield* Service.discover(options)
+    const transport = found ?? (yield* Service.start(options))
     const params = Option.getOrElse(input.param, () => ({}))
     const request = yield* resolveRequest(transport, input.request, params)
     const headers = new Headers(transport.headers)
@@ -58,7 +60,7 @@ export function rawRequest(input: readonly string[]) {
 }
 
 function resolveRequest(
-  transport: { url: string; headers: RequestInit["headers"] },
+  transport: Service.Transport,
   input: readonly string[],
   params: Record<string, string>,
 ) {

packages/cli/src/commands/handlers/debug/agents.ts

@@ -1,14 +1,18 @@
 import { EOL } from "os"
-import * as Effect from "effect/Effect"
+import { Effect } from "effect"
+import { createOpencodeClient } from "@opencode-ai/sdk/v2/client"
 import { Commands } from "../../commands"
 import { Runtime } from "../../../framework/runtime"
-import { Daemon } from "../../../services/daemon"
+import { Service } from "@opencode-ai/client/effect"
+import { ServiceConfig } from "../../../services/service-config"
 
 export default Runtime.handler(
   Commands.commands.debug.commands.agents,
   Effect.fn("cli.debug.agents")(function* () {
-    const daemon = yield* Daemon.Service
-    const client = yield* daemon.client()
+    const options = yield* ServiceConfig.options()
+    const found = yield* Service.discover(options)
+    const transport = found ?? (yield* Service.start(options))
+    const client = createOpencodeClient({ baseUrl: transport.url, headers: transport.headers })
     const response = yield* Effect.promise(() => client.v2.agent.list({ location: { directory: process.cwd() } }))
     process.stdout.write(
       JSON.stringify(

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

@@ -1,13 +1,89 @@
+import { NodeFileSystem } from "@effect/platform-node"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
-import { Effect } from "effect"
-import { Daemon } from "../../services/daemon"
+import { Effect, Option, Redacted } from "effect"
+import { Service } from "@opencode-ai/client/effect"
+import { Env } from "../../env"
+import { ServiceConfig } from "../../services/service-config"
+import { Standalone } from "../../services/standalone"
+import { Updater } from "../../services/updater"
 
-export default Runtime.handler(Commands, () =>
+export default Runtime.handler(Commands, (input) =>
   Effect.gen(function* () {
-    const daemon = yield* Daemon.Service
-    const transport = yield* daemon.transport()
+    const directory = Option.getOrUndefined(input.directory)
+    if (directory !== undefined) process.chdir(directory)
+    const updater = yield* Updater.Service
+    yield* updater.check().pipe(Effect.forkScoped)
+    const server = Option.getOrUndefined(input.server)
+    if (server !== undefined && input.standalone)
+      return yield* Effect.fail(new Error("--server and --standalone cannot be combined"))
+    const transport = yield* Effect.gen(function* () {
+      if (server !== undefined) {
+        const password = yield* Env.password
+        const explicit = {
+          url: server,
+          headers: password
+            ? { authorization: "Basic " + btoa("opencode:" + Redacted.value(password)) }
+            : undefined,
+        } satisfies Service.Transport
+        // Fail loudly before entering the TUI: an explicit server that is
+        // unreachable or rejects auth should not present as reconnect churn.
+        const response = yield* Effect.tryPromise(() =>
+          fetch(new URL("/api/health", server), { headers: explicit.headers, signal: AbortSignal.timeout(5_000) }),
+        ).pipe(Effect.mapError((cause) => new Error(`Could not reach server at ${server}`, { cause })))
+        if (response.status === 401)
+          return yield* Effect.fail(
+            new Error(
+              password
+                ? `Server at ${server} rejected the password`
+                : `Server at ${server} requires a password; set OPENCODE_PASSWORD`,
+            ),
+          )
+        if (!response.ok)
+          return yield* Effect.fail(new Error(`Server at ${server} responded with status ${response.status}`))
+        return explicit
+      }
+      if (input.standalone) return yield* Standalone.transport()
+      const options = yield* ServiceConfig.options()
+      const found = yield* Service.discover(options)
+      return found ?? (yield* Service.start(options))
+    })
     const { runTui } = yield* Effect.promise(() => import("../../tui"))
-    yield* runTui(transport)
+    // The TUI re-runs discover whenever its event stream drops. For an explicit
+    // --server or a standalone child the transport is fixed, so reconnects
+    // retry the same address; for the managed service discovery re-reads the
+    // registration and may start a replacement.
+    const serviceOptions = server === undefined && !input.standalone ? yield* ServiceConfig.options() : undefined
+    // Only startup enforces the CLI version. A reconnect must accept a server
+    // replaced by another client or the two clients will restart it forever.
+    const reconnectOptions = serviceOptions ? { ...serviceOptions, version: undefined } : undefined
+    const discover = reconnectOptions
+      ? () =>
+          Effect.runPromise(
+            Effect.gen(function* () {
+              const found = yield* Service.discover(reconnectOptions)
+              return found ?? (yield* Service.start(reconnectOptions))
+            }).pipe(Effect.provide(NodeFileSystem.layer)),
+          )
+      : () => Promise.resolve(transport)
+    // Restart the managed service in place; start() resolves once the
+    // replacement is healthy and the reconnect loop reattaches on its own.
+    // Only meaningful in service mode: --server is not ours to restart and a
+    // standalone child cannot be respawned.
+    const reload = serviceOptions
+      ? () =>
+          Effect.runPromise(
+            Effect.gen(function* () {
+              yield* Service.stop(serviceOptions)
+              yield* Service.start(serviceOptions)
+            }).pipe(Effect.provide(NodeFileSystem.layer)),
+          )
+      : undefined
+    yield* runTui(
+      transport,
+      { continue: input.continue, sessionID: Option.getOrUndefined(input.session) },
+      discover,
+      reload,
+    )
   }),
 )

packages/cli/src/commands/handlers/mcp/add.ts

@@ -0,0 +1,58 @@
+import { EOL } from "node:os"
+import path from "node:path"
+import { Effect, Option } from "effect"
+import { applyEdits, modify } from "jsonc-parser"
+import { Global } from "@opencode-ai/core/global"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+
+export default Runtime.handler(
+  Commands.commands.mcp.commands.add,
+  Effect.fn("cli.mcp.add")(function* (input) {
+    const url = Option.getOrUndefined(input.url)
+    const headers = Option.getOrUndefined(input.header)
+    const environment = Option.getOrUndefined(input.env)
+    // The CLI framework strands `--` operands on the root command, so read the local server command
+    // straight from argv after `--`. This also lets the command carry its own flags (e.g. `npx -y`).
+    const dash = process.argv.indexOf("--")
+    const command = dash === -1 ? [...input.command] : process.argv.slice(dash + 1)
+
+    const hasCommand = command.length > 0
+    if (url && hasCommand)
+      return yield* Effect.fail(new Error("Provide either --url <url> or a command after --, not both"))
+    if (!url && !hasCommand) return yield* Effect.fail(new Error("Provide either --url <url> or a command after --"))
+    if (url && !URL.canParse(url)) return yield* Effect.fail(new Error(`Invalid URL: ${url}`))
+    if (url && environment) return yield* Effect.fail(new Error("--env is only valid for local MCP servers"))
+    if (hasCommand && headers) return yield* Effect.fail(new Error("--header is only valid for remote MCP servers"))
+
+    const server = url
+      ? { type: "remote" as const, url, ...(headers ? { headers } : {}) }
+      : { type: "local" as const, command, ...(environment ? { environment } : {}) }
+
+    const configPath = yield* Effect.promise(() => resolveConfigPath(input.global ? Global.Path.config : process.cwd()))
+    yield* Effect.promise(() => write(configPath, input.name, server))
+    process.stdout.write(`MCP server "${input.name}" added to ${configPath}` + EOL)
+  }),
+)
+
+async function resolveConfigPath(directory: string) {
+  const candidates = [
+    path.join(directory, "opencode.json"),
+    path.join(directory, "opencode.jsonc"),
+    path.join(directory, ".opencode", "opencode.json"),
+    path.join(directory, ".opencode", "opencode.jsonc"),
+  ]
+  for (const candidate of candidates) {
+    if (await Bun.file(candidate).exists()) return candidate
+  }
+  return candidates[0]
+}
+
+async function write(configPath: string, name: string, server: unknown) {
+  const file = Bun.file(configPath)
+  const text = (await file.exists()) ? await file.text() : "{}"
+  const edits = modify(text, ["mcp", "servers", name], server, {
+    formattingOptions: { tabSize: 2, insertSpaces: true },
+  })
+  await Bun.write(configPath, applyEdits(text, edits))
+}

packages/cli/src/commands/handlers/mcp/auth.ts

@@ -0,0 +1,66 @@
+import { EOL } from "node:os"
+import { Effect } from "effect"
+import {
+  createOpencodeClient,
+  type IntegrationAttemptStatus,
+  type IntegrationOAuthMethod,
+  type OpencodeClient,
+} from "@opencode-ai/sdk/v2/client"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { Service } from "@opencode-ai/client/effect"
+import { ServiceConfig } from "../../../services/service-config"
+import { resolveIntegration } from "./resolve"
+
+const location = { directory: process.cwd() }
+
+export default Runtime.handler(
+  Commands.commands.mcp.commands.auth,
+  Effect.fn("cli.mcp.auth")(function* (input) {
+    const options = yield* ServiceConfig.options()
+    const found = yield* Service.discover(options)
+    const transport = found ?? (yield* Service.start(options))
+    const client = createOpencodeClient({ baseUrl: transport.url, headers: transport.headers })
+
+    const integration = yield* resolveIntegration(client, input.name, location)
+    if (!integration)
+      return yield* Effect.fail(new Error(`MCP server "${input.name}" is not an OAuth-capable remote server`))
+    const method = integration.methods.find(
+      (candidate): candidate is IntegrationOAuthMethod => candidate.type === "oauth",
+    )
+    if (!method)
+      return yield* Effect.fail(new Error(`MCP server "${input.name}" is not an OAuth-capable remote server`))
+
+    const started = yield* Effect.promise(() =>
+      client.v2.integration.connect.oauth({ integrationID: integration.id, methodID: method.id, inputs: {}, location }),
+    )
+    const attempt = started.data?.data
+    if (!attempt) return yield* Effect.fail(new Error(started.error?.message ?? "Failed to start OAuth attempt"))
+    if (attempt.mode === "code")
+      return yield* Effect.fail(new Error("This server requires manual code entry, which the CLI does not support"))
+
+    process.stdout.write(attempt.instructions + EOL + attempt.url + EOL)
+
+    const result = yield* poll(client, attempt.attemptID)
+    if (result.status === "complete") {
+      process.stdout.write(`Authenticated with ${input.name}` + EOL)
+      return
+    }
+    const reason = result.status === "failed" ? `: ${result.message}` : ""
+    return yield* Effect.fail(new Error(`Authentication ${result.status}${reason}`))
+  }),
+)
+
+const poll = (
+  client: OpencodeClient,
+  attemptID: string,
+): Effect.Effect<Exclude<IntegrationAttemptStatus, { status: "pending" }>> =>
+  Effect.gen(function* () {
+    const response = yield* Effect.promise(() => client.v2.integration.attempt.status({ attemptID, location }))
+    const status = response.data?.data
+    if (!status || status.status === "pending") {
+      yield* Effect.sleep("1 second")
+      return yield* poll(client, attemptID)
+    }
+    return status
+  })

packages/cli/src/commands/handlers/mcp/list.ts

@@ -0,0 +1,55 @@
+import { EOL } from "node:os"
+import { Effect } from "effect"
+import { createOpencodeClient, type McpServer } from "@opencode-ai/sdk/v2/client"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { Service } from "@opencode-ai/client/effect"
+import { ServiceConfig } from "../../../services/service-config"
+
+export default Runtime.handler(
+  Commands.commands.mcp.commands.list,
+  Effect.fn("cli.mcp.list")(function* () {
+    const options = yield* ServiceConfig.options()
+    const found = yield* Service.discover(options)
+    const transport = found ?? (yield* Service.start(options))
+    const client = createOpencodeClient({ baseUrl: transport.url, headers: transport.headers })
+    const response = yield* Effect.promise(() => client.v2.mcp.list({ location: { directory: process.cwd() } }))
+    const servers = (response.data?.data ?? []).toSorted((a, b) => a.name.localeCompare(b.name))
+    if (servers.length === 0) {
+      process.stdout.write("No MCP servers configured" + EOL)
+      return
+    }
+    const width = Math.max(...servers.map((server) => server.name.length))
+    const lines = servers.map(
+      (server) => `${icon(server.status)} ${server.name.padEnd(width)}  ${describe(server.status)}`,
+    )
+    process.stdout.write(lines.join(EOL) + EOL)
+  }),
+)
+
+function icon(status: McpServer["status"]) {
+  switch (status.status) {
+    case "connected":
+      return "✓"
+    case "needs_auth":
+      return "⚠"
+    case "failed":
+    case "needs_client_registration":
+      return "✗"
+    default:
+      return "○"
+  }
+}
+
+function describe(status: McpServer["status"]) {
+  switch (status.status) {
+    case "needs_auth":
+      return "needs authentication"
+    case "needs_client_registration":
+      return `needs client registration: ${status.error}`
+    case "failed":
+      return `failed: ${status.error}`
+    default:
+      return status.status
+  }
+}

packages/cli/src/commands/handlers/mcp/logout.ts

@@ -0,0 +1,39 @@
+import { EOL } from "node:os"
+import { Effect } from "effect"
+import { createOpencodeClient } from "@opencode-ai/sdk/v2/client"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { Service } from "@opencode-ai/client/effect"
+import { ServiceConfig } from "../../../services/service-config"
+import { resolveIntegration } from "./resolve"
+
+const location = { directory: process.cwd() }
+
+export default Runtime.handler(
+  Commands.commands.mcp.commands.logout,
+  Effect.fn("cli.mcp.logout")(function* (input) {
+    const options = yield* ServiceConfig.options()
+    const found = yield* Service.discover(options)
+    const transport = found ?? (yield* Service.start(options))
+    const client = createOpencodeClient({ baseUrl: transport.url, headers: transport.headers })
+
+    const integration = yield* resolveIntegration(client, input.name, location)
+    if (!integration) {
+      process.stdout.write(`No stored credentials for ${input.name}` + EOL)
+      return
+    }
+
+    const credentials = integration.connections.filter((connection) => connection.type === "credential")
+    if (credentials.length === 0) {
+      process.stdout.write(`No stored credentials for ${input.name}` + EOL)
+      return
+    }
+
+    yield* Effect.forEach(
+      credentials,
+      (connection) => Effect.promise(() => client.v2.credential.remove({ credentialID: connection.id, location })),
+      { discard: true },
+    )
+    process.stdout.write(`Removed OAuth credentials for ${input.name}` + EOL)
+  }),
+)

packages/cli/src/commands/handlers/mcp/resolve.ts

@@ -0,0 +1,17 @@
+import { Effect } from "effect"
+import type { OpencodeClient } from "@opencode-ai/sdk/v2/client"
+
+// Resolve through the MCP-owned integrationID rather than matching integration names: the shared
+// integration registry also holds provider/plugin integrations, whose names could collide with a server.
+// Fails when the server is unknown; returns undefined when the server has no integration (e.g. a local
+// or anonymous server), leaving that case for the caller to interpret.
+export const resolveIntegration = (client: OpencodeClient, name: string, location: { directory: string }) =>
+  Effect.gen(function* () {
+    const servers = yield* Effect.promise(() => client.v2.mcp.list({ location }))
+    const server = (servers.data?.data ?? []).find((entry) => entry.name === name)
+    if (!server) return yield* Effect.fail(new Error(`MCP server not found: ${name}`))
+    const integrationID = server.integrationID
+    if (!integrationID) return undefined
+    const found = yield* Effect.promise(() => client.v2.integration.get({ integrationID, location }))
+    return found.data?.data
+  })

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

@@ -1,4 +1,4 @@
-import * as Effect from "effect/Effect"
+import { Effect } from "effect"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
 

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

@@ -0,0 +1,35 @@
+import { Effect, Option, Redacted } from "effect"
+import path from "node:path"
+import { Commands } from "../commands"
+import { Env } from "../../env"
+import { Runtime } from "../../framework/runtime"
+
+export default Runtime.handler(Commands.commands.mini, (input) =>
+  Effect.gen(function* () {
+    const { runMini } = yield* Effect.promise(() => import("../../mini"))
+    const project = Option.getOrUndefined(input.project)
+    const server = Option.getOrUndefined(input.server)
+    const password = yield* Env.password
+    yield* Effect.promise(() =>
+      runMini({
+        attach: server,
+        password: password ? Redacted.value(password) : undefined,
+        directory:
+          server !== undefined
+            ? project
+            : project === undefined
+              ? process.cwd()
+              : path.resolve(process.env.PWD ?? process.cwd(), project),
+        continue: input.continue,
+        session: Option.getOrUndefined(input.session),
+        fork: input.fork,
+        model: Option.getOrUndefined(input.model),
+        agent: Option.getOrUndefined(input.agent),
+        prompt: Option.getOrUndefined(input.prompt),
+        replay: input.replay,
+        replayLimit: Option.getOrUndefined(input.replayLimit),
+        demo: input.demo,
+      }),
+    )
+  }),
+)

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

@@ -0,0 +1,31 @@
+import { Effect, Option, Redacted } from "effect"
+import { Commands } from "../commands"
+import { Env } from "../../env"
+import { Runtime } from "../../framework/runtime"
+
+export default Runtime.handler(Commands.commands.run, (input) =>
+  Effect.gen(function* () {
+    const { runNonInteractive } = yield* Effect.promise(() => import("../../mini"))
+    const password = yield* Env.password
+    const separator = process.argv.indexOf("--", 2)
+    yield* Effect.promise(() =>
+      runNonInteractive({
+        message: [...input.message, ...(separator === -1 ? [] : process.argv.slice(separator + 1))],
+        continue: input.continue,
+        session: Option.getOrUndefined(input.session),
+        fork: input.fork,
+        model: Option.getOrUndefined(input.model),
+        agent: Option.getOrUndefined(input.agent),
+        format: input.format,
+        file: [...input.file],
+        title: Option.getOrUndefined(input.title),
+        server: Option.getOrUndefined(input.server),
+        password: password ? Redacted.value(password) : undefined,
+        directory: Option.getOrUndefined(input.dir),
+        variant: Option.getOrUndefined(input.variant),
+        thinking: input.thinking,
+        dangerouslySkipPermissions: input.auto || input.yolo || input.dangerouslySkipPermissions,
+      }),
+    )
+  }),
+)

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

@@ -1,46 +1,16 @@
-import { NodeHttpServer } from "@effect/platform-node"
-import { Credential } from "@opencode-ai/core/credential"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
-import { LayerNode } from "@opencode-ai/core/effect/layer-node"
-import { PermissionSaved } from "@opencode-ai/core/permission/saved"
-import { Context, Layer, Option } from "effect"
-import * as Effect from "effect/Effect"
-import { HttpRouter, HttpServer } from "effect/unstable/http"
-import { createServer } from "node:http"
-import { createRoutes } from "@opencode-ai/server/routes"
+import { Effect, Option } from "effect"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
-import { Daemon } from "../../services/daemon"
+import { ServerProcess } from "../../server-process"
 
 export default Runtime.handler(
   Commands.commands.serve,
   Effect.fn("cli.serve")(function* (input) {
-    return yield* Effect.scoped(
-      Effect.gen(function* () {
-        const daemon = yield* Daemon.Service
-        const address = yield* listen(input.hostname, input.port, yield* daemon.password())
-        if (input.register) yield* daemon.register(address)
-        console.log(`server listening on ${HttpServer.formatAddress(address)}`)
-        return yield* Effect.never
-      }),
-    )
+    if (input.service && input.stdio) return yield* Effect.fail(new Error("--service and --stdio cannot be combined"))
+    return yield* ServerProcess.run({
+      mode: input.service ? "service" : input.stdio ? "stdio" : "default",
+      hostname: Option.getOrUndefined(input.hostname),
+      port: Option.getOrUndefined(input.port),
+    })
   }),
 )
-
-function listen(hostname: string, port: Option.Option<number>, password: string) {
-  if (Option.isSome(port)) return bind(hostname, port.value, password)
-  const next = (port: number): ReturnType<typeof bind> =>
-    bind(hostname, port, password).pipe(
-      Effect.catch((error) => (port === 65_535 ? Effect.fail(error) : next(port + 1))),
-    )
-  return next(4096)
-}
-
-function bind(hostname: string, port: number, password: string) {
-  return Layer.build(
-    HttpRouter.serve(createRoutes(password), { disableListenLog: true, disableLogger: true }).pipe(
-      Layer.provideMerge(NodeHttpServer.layer(() => createServer(), { port, host: hostname })),
-      Layer.provide(AppNodeBuilder.build(LayerNode.group([Credential.node, PermissionSaved.node]))),
-    ),
-  ).pipe(Effect.map((context) => Context.get(context, HttpServer.HttpServer).address))
-}

packages/cli/src/commands/handlers/service/get.ts

@@ -0,0 +1,12 @@
+import { EOL } from "os"
+import { Effect, Option } from "effect"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { ServiceConfig } from "../../../services/service-config"
+
+export default Runtime.handler(
+  Commands.commands.service.commands.get,
+  Effect.fn("cli.service.get")(function* (input) {
+    process.stdout.write((yield* ServiceConfig.get(Option.getOrUndefined(input.key))) + EOL)
+  }),
+)

packages/cli/src/commands/handlers/service/password.ts

@@ -1,16 +0,0 @@
-import { EOL } from "os"
-import { Option } from "effect"
-import * as Effect from "effect/Effect"
-import { Commands } from "../../commands"
-import { Runtime } from "../../../framework/runtime"
-import { Daemon } from "../../../services/daemon"
-
-export default Runtime.handler(
-  Commands.commands.service.commands.password,
-  Effect.fn("cli.service.password")(function* (input) {
-    const daemon = yield* Daemon.Service
-    const value = Option.getOrUndefined(input.value)
-    if (value !== undefined) yield* daemon.stop()
-    process.stdout.write((yield* daemon.password(value)) + EOL)
-  }),
-)

packages/cli/src/commands/handlers/service/restart.ts

@@ -1,14 +1,16 @@
 import { EOL } from "os"
-import * as Effect from "effect/Effect"
+import { Effect } from "effect"
+import { Service } from "@opencode-ai/client/effect"
 import { Commands } from "../../commands"
 import { Runtime } from "../../../framework/runtime"
-import { Daemon } from "../../../services/daemon"
+import { ServiceConfig } from "../../../services/service-config"
 
 export default Runtime.handler(
   Commands.commands.service.commands.restart,
   Effect.fn("cli.service.restart")(function* () {
-    const daemon = yield* Daemon.Service
-    yield* daemon.stop()
-    process.stdout.write((yield* daemon.start()) + EOL)
+    const options = yield* ServiceConfig.options()
+    yield* Service.stop(options)
+    const transport = yield* Service.start(options)
+    process.stdout.write(transport.url + EOL)
   }),
 )

packages/cli/src/commands/handlers/service/set.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { ServiceConfig } from "../../../services/service-config"
+
+export default Runtime.handler(
+  Commands.commands.service.commands.set,
+  Effect.fn("cli.service.set")(function* (input) {
+    yield* ServiceConfig.set(input.key, input.value)
+  }),
+)

packages/cli/src/commands/handlers/service/start.ts

@@ -1,12 +1,14 @@
 import { EOL } from "os"
-import * as Effect from "effect/Effect"
+import { Effect } from "effect"
+import { Service } from "@opencode-ai/client/effect"
 import { Commands } from "../../commands"
 import { Runtime } from "../../../framework/runtime"
-import { Daemon } from "../../../services/daemon"
+import { ServiceConfig } from "../../../services/service-config"
 
 export default Runtime.handler(
   Commands.commands.service.commands.start,
   Effect.fn("cli.service.start")(function* () {
-    process.stdout.write((yield* (yield* Daemon.Service).start()) + EOL)
+    const transport = yield* Service.start(yield* ServiceConfig.options())
+    process.stdout.write(transport.url + EOL)
   }),
 )

packages/cli/src/commands/handlers/service/status.ts

@@ -1,13 +1,14 @@
 import { EOL } from "os"
-import * as Effect from "effect/Effect"
+import { Effect } from "effect"
+import { Service } from "@opencode-ai/client/effect"
 import { Commands } from "../../commands"
 import { Runtime } from "../../../framework/runtime"
-import { Daemon } from "../../../services/daemon"
+import { ServiceConfig } from "../../../services/service-config"
 
 export default Runtime.handler(
   Commands.commands.service.commands.status,
   Effect.fn("cli.service.status")(function* () {
-    const url = yield* (yield* Daemon.Service).status()
-    process.stdout.write((url ? `running ${url}` : "stopped") + EOL)
+    const found = yield* Service.discover(yield* ServiceConfig.options())
+    process.stdout.write((found ? found.url : "stopped") + EOL)
   }),
 )

packages/cli/src/commands/handlers/service/stop.ts

@@ -1,11 +1,12 @@
-import * as Effect from "effect/Effect"
+import { Effect } from "effect"
+import { Service } from "@opencode-ai/client/effect"
 import { Commands } from "../../commands"
 import { Runtime } from "../../../framework/runtime"
-import { Daemon } from "../../../services/daemon"
+import { ServiceConfig } from "../../../services/service-config"
 
 export default Runtime.handler(
   Commands.commands.service.commands.stop,
   Effect.fn("cli.service.stop")(function* () {
-    yield* (yield* Daemon.Service).stop()
+    yield* Service.stop(yield* ServiceConfig.options())
   }),
 )

packages/cli/src/commands/handlers/service/unset.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { ServiceConfig } from "../../../services/service-config"
+
+export default Runtime.handler(
+  Commands.commands.service.commands.unset,
+  Effect.fn("cli.service.unset")(function* (input) {
+    yield* ServiceConfig.unset(input.key)
+  }),
+)

packages/cli/src/daemon.ts

@@ -0,0 +1,70 @@
+import { Service } from "@opencode-ai/client/effect"
+import { ClientError, isUnauthorizedError, OpenCode } from "@opencode-ai/client/promise"
+import { InstallationVersion } from "@opencode-ai/core/installation/version"
+import { ServerAuth } from "@opencode-ai/server/auth"
+import { Effect } from "effect"
+import { ServiceConfig } from "./services/service-config"
+
+export type SharedOptions = {
+  readonly mode: "shared"
+  readonly command?: ReadonlyArray<string>
+}
+export type AttachOptions = {
+  readonly mode: "attach"
+  readonly url: string
+  readonly username?: string
+  readonly password?: string
+}
+export type Options = SharedOptions | AttachOptions
+
+const attach = Effect.fn("cli.daemon.attach")(function* (options: AttachOptions) {
+  const transport = {
+    url: options.url,
+    headers:
+      options.password === undefined
+        ? undefined
+        : ServerAuth.headers({ password: options.password, username: options.username }),
+  } satisfies Service.Transport
+  const client = OpenCode.make({ baseUrl: transport.url, headers: transport.headers })
+  const health = yield* Effect.tryPromise({
+    try: () => client.health.get({ signal: AbortSignal.timeout(5_000) }),
+    catch: (cause) => attachError(options, cause),
+  })
+  if (health.version !== InstallationVersion)
+    process.stderr.write(
+      `Warning: Server at ${options.url} has version ${health.version}; this client is ${InstallationVersion}. Continuing anyway.\n`,
+    )
+  return transport
+})
+
+const shared = Effect.fn("cli.daemon.shared")(function* (options: SharedOptions) {
+  const config = yield* ServiceConfig.options()
+  const service = options.command === undefined ? config : { ...config, command: options.command }
+  const found = yield* Service.discover(service)
+  if (found) return found
+  return yield* Service.start(service)
+})
+
+export function transport(options: AttachOptions): ReturnType<typeof attach>
+export function transport(options: SharedOptions): ReturnType<typeof shared>
+export function transport(options: Options): ReturnType<typeof attach> | ReturnType<typeof shared>
+export function transport(options: Options) {
+  if (options.mode === "attach") return attach(options)
+  return shared(options)
+}
+
+function attachError(options: AttachOptions, cause: unknown) {
+  if (isUnauthorizedError(cause)) {
+    return new Error(
+      options.password === undefined
+        ? `Server at ${options.url} requires authentication; provide a password`
+        : `Server at ${options.url} rejected the supplied credentials`,
+      { cause },
+    )
+  }
+  if (cause instanceof ClientError && cause.reason === "Transport")
+    return new Error(`Could not reach server at ${options.url}`, { cause })
+  return new Error(`Server at ${options.url} did not provide a compatible V2 health response`, { cause })
+}
+
+export * as Daemon from "./daemon"

packages/cli/src/env.ts

@@ -0,0 +1,15 @@
+import { Config } from "effect"
+
+// Every environment variable the CLI reads, in one place. Consumers yield
+// these instead of touching process.env so the full surface stays visible,
+// typed, and redacted where secret.
+
+// The opencode server password: sent by clients connecting to an explicit
+// --server, and adopted by a manually run or standalone server. The legacy
+// name is still honored.
+export const password = Config.redacted("OPENCODE_PASSWORD").pipe(
+  Config.orElse(() => Config.redacted("OPENCODE_SERVER_PASSWORD")),
+  Config.withDefault(undefined),
+)
+
+export * as Env from "./env"

packages/cli/src/framework/runtime.ts

@@ -1,7 +1,8 @@
-import * as Effect from "effect/Effect"
-import * as Command from "effect/unstable/cli/Command"
+import { Effect, FileSystem, Scope } from "effect"
+import { Command } from "effect/unstable/cli"
 import { Spec } from "./spec"
-import { Daemon } from "../services/daemon"
+import { Global } from "@opencode-ai/core/global"
+import { Updater } from "../services/updater"
 
 export type Input<Value> =
   Value extends Spec.Node<infer _Name, infer Command, infer _Commands>
@@ -10,11 +11,21 @@ export type Input<Value> =
       ? Input
       : never
 
-type RuntimeHandler = (input: unknown) => Effect.Effect<void, unknown, Daemon.Service>
+type RuntimeHandler = (
+  input: unknown,
+) => Effect.Effect<void, unknown, FileSystem.FileSystem | Global.Service | Updater.Service | Scope.Scope>
 type Loader<Node extends Spec.Any> = () => Promise<{
-  default: (input: Input<Node>) => Effect.Effect<void, any, Daemon.Service>
+  default: (
+    input: Input<Node>,
+  ) => Effect.Effect<void, any, FileSystem.FileSystem | Global.Service | Updater.Service | Scope.Scope>
 }>
-type ProvidedCommand = Command.Command<string, unknown, unknown, unknown, Daemon.Service>
+type ProvidedCommand = Command.Command<
+  string,
+  unknown,
+  unknown,
+  unknown,
+  FileSystem.FileSystem | Global.Service | Updater.Service | Scope.Scope
+>
 
 export type Handlers<Node extends Spec.Any> = keyof Node["commands"] extends never
   ? Loader<Node>

packages/cli/src/framework/spec.ts

@@ -1,4 +1,4 @@
-import * as Command from "effect/unstable/cli/Command"
+import { Command } from "effect/unstable/cli"
 
 type Options<Config extends Command.Command.Config, Commands extends ReadonlyArray<Any>> = {
   readonly description?: string

packages/cli/src/index.ts

@@ -1,11 +1,22 @@
 #!/usr/bin/env bun
 
-import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
-import * as NodeServices from "@effect/platform-node/NodeServices"
-import * as Effect from "effect/Effect"
+import { NodeFileSystem, NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Effect, Layer, Logger, References } from "effect"
 import { Commands } from "./commands/commands"
 import { Runtime } from "./framework/runtime"
-import { Daemon } from "./services/daemon"
+import { Logging } from "@opencode-ai/core/observability/logging"
+import { Updater } from "./services/updater"
+import { InstallationChannel, InstallationVersion, InstallationLocal } from "@opencode-ai/core/installation/version"
+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"
+
+const LoggingLayer = Logger.layer(Logging.loggers(), { mergeWithExisting: false }).pipe(
+  Layer.provide(NodeFileSystem.layer),
+  Layer.orDie,
+  Layer.merge(Layer.succeed(References.MinimumLogLevel, Logging.minimumLogLevel())),
+)
 
 const Handlers = Runtime.handlers(Commands, {
   $: () => import("./commands/handlers/default"),
@@ -13,20 +24,40 @@ const Handlers = Runtime.handlers(Commands, {
   debug: {
     agents: () => import("./commands/handlers/debug/agents"),
   },
+  mcp: {
+    list: () => import("./commands/handlers/mcp/list"),
+    add: () => import("./commands/handlers/mcp/add"),
+    auth: () => import("./commands/handlers/mcp/auth"),
+    logout: () => import("./commands/handlers/mcp/logout"),
+  },
   migrate: () => import("./commands/handlers/migrate"),
+  mini: () => import("./commands/handlers/mini"),
+  run: () => import("./commands/handlers/run"),
   service: {
     start: () => import("./commands/handlers/service/start"),
     restart: () => import("./commands/handlers/service/restart"),
     status: () => import("./commands/handlers/service/status"),
     stop: () => import("./commands/handlers/service/stop"),
-    password: () => import("./commands/handlers/service/password"),
+    get: () => import("./commands/handlers/service/get"),
+    set: () => import("./commands/handlers/service/set"),
+    unset: () => import("./commands/handlers/service/unset"),
   },
   serve: () => import("./commands/handlers/serve"),
 })
 
-Runtime.run(Commands, Handlers, { version: "local" }).pipe(
-  Effect.provide(Daemon.layer),
+Effect.logInfo("cli starting", {
+  version: InstallationVersion,
+  channel: InstallationChannel,
+  local: InstallationLocal,
+  args: process.argv.slice(2),
+}).pipe(
+  Effect.flatMap(() => Runtime.run(Commands, Handlers, { version: InstallationVersion })),
+  Effect.annotateLogs({ role: "cli" }),
+  Effect.provide(Updater.layer),
+  Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node]))),
+  Effect.provide(LoggingLayer),
   Effect.provide(NodeServices.layer),
   Effect.scoped,
+  Effect.tap(() => Effect.sync(() => process.exit(process.exitCode ?? 0))),
   NodeRuntime.runMain,
 )

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

@@ -0,0 +1,158 @@
+import type {
+  AgentListOutput,
+  CommandListOutput,
+  ModelListOutput,
+  OpenCodeClient,
+  ProviderListOutput,
+  SkillListOutput,
+} from "@opencode-ai/client/promise"
+import type { RunAgent, RunCommand, RunProvider, RunReference } from "./types"
+
+type CurrentAgent = AgentListOutput["data"][number]
+type CurrentCommand = CommandListOutput["data"][number]
+type CurrentSkill = SkillListOutput["data"][number]
+type CurrentProvider = ProviderListOutput["data"][number]
+type CurrentModel = ModelListOutput["data"][number]
+
+function location(directory: string, workspace?: string) {
+  return {
+    location: {
+      directory,
+      workspace,
+    },
+  }
+}
+
+function defaultCost(model: CurrentModel) {
+  const picked = model.cost.find((cost) => cost.tier === undefined) ?? model.cost[0]
+  if (!picked) {
+    return undefined
+  }
+
+  return {
+    ...picked,
+    input: model.cost.every((cost) => cost.input === 0) ? 0 : picked.input,
+  }
+}
+
+export function runAgent(input: CurrentAgent): RunAgent {
+  return {
+    name: input.id,
+    description: input.description,
+    mode: input.mode,
+    hidden: input.hidden,
+  }
+}
+
+export function runCommand(input: CurrentCommand): RunCommand {
+  return {
+    name: input.name,
+    description: input.description,
+  }
+}
+
+export function runSkill(input: CurrentSkill): RunCommand {
+  return {
+    name: input.name,
+    description: input.description,
+    source: "skill",
+  }
+}
+
+export function runProviders(providers: CurrentProvider[], models: CurrentModel[]): RunProvider[] {
+  const grouped = new Map<string, RunProvider>()
+
+  for (const provider of providers) {
+    grouped.set(provider.id, {
+      id: provider.id,
+      name: provider.name,
+      models: {},
+    })
+  }
+
+  for (const model of models) {
+    const provider = grouped.get(model.providerID) ?? {
+      id: model.providerID,
+      name: model.providerID,
+      models: {},
+    }
+    provider.models[model.id] = {
+      id: model.id,
+      providerID: model.providerID,
+      name: model.name,
+      capabilities: model.capabilities,
+      cost: defaultCost(model),
+      limit: model.limit,
+      status: model.status,
+      variants: Object.fromEntries((model.variants ?? []).map((variant) => [variant.id, {}])),
+    }
+    grouped.set(provider.id, provider)
+  }
+
+  return [...grouped.values()]
+}
+
+// A location boots its plugins in a deferred background batch after the layer
+// is built, so first-turn model resolution can observe empty catalog state.
+// For explicit --model flows, wait for that exact ref to appear before prompt
+// admission. On timeout, return and let the real execution error surface.
+export async function waitForCatalogReady(input: {
+  sdk: OpenCodeClient
+  directory: string
+  workspace?: string
+  model: { providerID: string; modelID: string }
+  timeoutMs?: number
+}) {
+  const deadline = Date.now() + (input.timeoutMs ?? 5_000)
+  while (Date.now() < deadline) {
+    const models = await input.sdk.model
+      .list(location(input.directory, input.workspace))
+      .then((result) => result.data)
+      .catch(() => undefined)
+    if (models?.some((model) => model.providerID === input.model.providerID && model.id === input.model.modelID)) return
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+}
+
+export async function waitForDefaultModel(input: {
+  sdk: OpenCodeClient
+  directory: string
+  timeoutMs?: number
+  active?: () => boolean
+}): Promise<{ providerID: string; modelID: string } | undefined> {
+  const deadline = Date.now() + (input.timeoutMs ?? 5_000)
+  while (Date.now() < deadline && (input.active?.() ?? true)) {
+    const model = await input.sdk.model
+      .default(location(input.directory))
+      .then((result) => result.data)
+      .catch(() => undefined)
+    if (model) return { providerID: model.providerID, modelID: model.id }
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+}
+
+export async function loadRunAgents(sdk: OpenCodeClient, directory: string): Promise<RunAgent[]> {
+  const result = await sdk.agent.list(location(directory))
+  return result.data.map(runAgent)
+}
+
+export async function loadRunCommands(sdk: OpenCodeClient, directory: string): Promise<RunCommand[]> {
+  const [commands, skills] = await Promise.all([
+    sdk.command.list(location(directory)),
+    sdk.skill.list(location(directory)),
+  ])
+  return [...commands.data.map(runCommand), ...skills.data.filter((skill) => skill.slash !== false).map(runSkill)]
+}
+
+export async function loadRunReferences(sdk: OpenCodeClient, directory: string): Promise<RunReference[]> {
+  const result = await sdk.reference.list(location(directory))
+  return result.data.filter((reference) => !reference.hidden)
+}
+
+export async function loadRunProviders(sdk: OpenCodeClient, directory: string): Promise<RunProvider[]> {
+  const [providers, models] = await Promise.all([
+    sdk.provider.list(location(directory)),
+    sdk.model.list(location(directory)),
+  ])
+  return runProviders([...providers.data], [...models.data])
+}

packages/cli/src/mini/demo.ts

@@ -678,7 +678,7 @@ function emitTask(state: State): void {
     state: {
       status: "running",
       input: {
-        filePath: "packages/opencode/src/cli/cmd/run/stream.ts",
+        filePath: "packages/cli/src/mini/stream.ts",
         offset: 1,
         limit: 200,
       },

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

@@ -3,7 +3,7 @@ import { TextAttributes, type ColorInput } from "@opentui/core"
 import { useTerminalDimensions } from "@opentui/solid"
 import { createEffect, createMemo, createSignal, type Accessor } from "solid-js"
 import { transparent, type RunFooterTheme } from "./theme"
-import * as Locale from "@/util/locale"
+import { Locale } from "@opencode-ai/tui/util/locale"
 
 export const FOOTER_MENU_ROWS = 8
 

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

@@ -141,7 +141,9 @@ export function RunPermissionBody(props: {
   const info = createMemo(() => permissionInfo(props.request))
   const ft = createMemo(() => toolFiletype(info().file))
   const narrow = createMemo(() => footerWidthPolicy(dims().width).dialog.narrow)
-  const opts = createMemo(() => permissionOptions(state().stage))
+  const opts = createMemo(() =>
+    permissionOptions(state().stage).filter((option) => option !== "always" || props.request.always.length > 0),
+  )
   const busy = createMemo(() => state().submitting)
   const title = createMemo(() => {
     if (state().stage === "always") {
@@ -165,7 +167,7 @@ export function RunPermissionBody(props: {
   })
 
   const shift = (dir: -1 | 1) => {
-    setState((prev) => permissionShift(prev, dir))
+    setState((prev) => permissionShift(prev, dir, opts()))
   }
 
   const submit = async (next: PermissionReply) => {

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

@@ -1,18 +1,18 @@
 // Prompt composer and its state machine for direct interactive mode.
 //
 // createPromptState() wires keymap command layers, history navigation, and
-// `@` autocomplete for files, subagents, and MCP resources.
+// `@` autocomplete for files, subagents, and project references.
 // It produces a PromptState that RunPromptBody renders as a slim single-line
 // composer while the footer view renders any active menus below it.
 /** @jsxImportSource @opentui/solid */
 import { pathToFileURL } from "bun"
 import { StyledText, fg, type ColorInput, type KeyEvent, type TextareaRenderable } from "@opentui/core"
 import { useRenderer } from "@opentui/solid"
-import { normalizePromptContent } from "@opencode-ai/tui/editor"
+import { normalizePromptContent } from "@opencode-ai/tui/prompt/content"
 import fuzzysort from "fuzzysort"
 import path from "path"
 import { createEffect, createMemo, createResource, createSignal, onCleanup, onMount, type Accessor } from "solid-js"
-import * as Locale from "@/util/locale"
+import { Locale } from "@opencode-ai/tui/util/locale"
 import {
   createPromptHistory,
   displayCharAt,
@@ -27,7 +27,7 @@ import { OPENCODE_BASE_MODE, useBindings } from "@opencode-ai/tui/keymap"
 import { realignEditorPromptParts, resolveEditorSlashValue } from "./prompt.editor"
 import { FOOTER_MENU_ROWS, createFooterMenuState, type RunFooterMenuItem } from "./footer.menu"
 import type { RunFooterTheme } from "./theme"
-import type { FooterState, RunAgent, RunCommand, RunPrompt, RunPromptPart, RunResource, RunTuiConfig } from "./types"
+import type { FooterState, RunAgent, RunCommand, RunPrompt, RunPromptPart, RunReference, RunTuiConfig } from "./types"
 
 const AUTOCOMPLETE_ROWS = FOOTER_MENU_ROWS
 const AUTOCOMPLETE_BOTTOM_ROWS = 1
@@ -59,7 +59,7 @@ type PromptInput = {
   directory: string
   findFiles: (query: string) => Promise<string[]>
   agents: Accessor<RunAgent[]>
-  resources: Accessor<RunResource[]>
+  references: Accessor<RunReference[]>
   commands: Accessor<RunCommand[] | undefined>
   tuiConfig: RunTuiConfig
   state: Accessor<FooterState>
@@ -67,7 +67,7 @@ type PromptInput = {
   prompt: Accessor<boolean>
   width: Accessor<number>
   theme: Accessor<RunFooterTheme>
-  history?: RunPrompt[]
+  history?: Accessor<RunPrompt[]>
   onSubmit: (input: RunPrompt) => boolean | Promise<boolean>
   onCycle: () => void
   onInterrupt: () => boolean
@@ -175,14 +175,18 @@ function parseSlashCommand(text: string, commands: RunCommand[] | undefined) {
     return { type: "pending" as const }
   }
 
-  if (!commands.some((item) => item.name === head.name)) {
+  const item = commands.find((entry) => entry.name === head.name)
+  if (!item) {
     return { type: "none" as const }
   }
 
-  return { type: "command" as const, command: { name: head.name, arguments: head.arguments } }
+  return {
+    type: "command" as const,
+    command: { name: head.name, arguments: head.arguments, ...(item.source ? { source: item.source } : {}) },
+  }
 }
 
-function selectedCommand(text: string, command: RunPrompt["command"]) {
+export function selectedCommand(text: string, command: RunPrompt["command"], commands?: RunCommand[]) {
   if (!command) {
     return
   }
@@ -192,9 +196,14 @@ function selectedCommand(text: string, command: RunPrompt["command"]) {
     return
   }
 
+  // Bound drafts (e.g. the skill picker) may predate or omit the catalog
+  // source; resolve it at submit time so routing never degrades to a plain
+  // command for a skill entry.
+  const source = command.source ?? commands?.find((item) => item.name === command.name)?.source
   return {
     name: command.name,
     arguments: head.arguments,
+    ...(source ? { source } : {}),
   }
 }
 
@@ -293,7 +302,10 @@ export function createPromptState(input: PromptInput): PromptState {
     return new StyledText([fg(input.theme().muted)('Ask anything... "Fix a TODO in the codebase"')])
   })
 
-  let history = createPromptHistory(input.history)
+  let history = createPromptHistory(input.history?.())
+  createEffect(() => {
+    history = createPromptHistory(input.history?.())
+  })
   let draft: RunPrompt = { text: "", parts: [] }
   let stash: RunPrompt = { text: "", parts: [] }
   let area: TextareaRenderable | undefined
@@ -333,21 +345,20 @@ export function createPromptState(input: PromptInput): PromptState {
         },
       }))
   })
-  const resources = createMemo<Auto[]>(() => {
-    return input.resources().map((item) => ({
+  const references = createMemo<Auto[]>(() => {
+    return input.references().map((item) => ({
       kind: "mention",
-      display: Locale.truncateMiddle(`@${item.name} (${item.uri})`, width()),
+      display: Locale.truncateMiddle("@" + item.name, width()),
       value: item.name,
-      description: item.description,
+      description: item.description ?? (item.source.type === "git" ? item.source.repository : item.source.path),
       part: {
         type: "file",
-        mime: item.mimeType ?? "text/plain",
+        mime: "application/x-directory",
         filename: item.name,
-        url: item.uri,
+        url: pathToFileURL(item.path).href,
         source: {
-          type: "resource",
-          clientName: item.client,
-          uri: item.uri,
+          type: "file",
+          path: item.name,
           text: {
             start: 0,
             end: 0,
@@ -402,7 +413,7 @@ export function createPromptState(input: PromptInput): PromptState {
     },
     { initialValue: [] as Auto[] },
   )
-  const mentionOptions = createMemo(() => [...agents(), ...files(), ...resources()])
+  const mentionOptions = createMemo(() => [...agents(), ...files(), ...references()])
   const skillCommands = createMemo(() => (input.commands() ?? []).filter((item) => item.source === "skill"))
   const hasSkillsCommand = createMemo(() =>
     (input.commands() ?? []).some((item) => item.source !== "skill" && item.name === "skills"),
@@ -462,7 +473,7 @@ export function createPromptState(input: PromptInput): PromptState {
       return [
         ...fuzzysort.go(next, agents(), { keys: ["value", "display", "description"] }).map((item) => item.obj),
         ...files(),
-        ...fuzzysort.go(next, resources(), { keys: ["value", "display", "description"] }).map((item) => item.obj),
+        ...fuzzysort.go(next, references(), { keys: ["value", "display", "description"] }).map((item) => item.obj),
       ]
     }
 
@@ -1179,7 +1190,7 @@ export function createPromptState(input: PromptInput): PromptState {
       return
     }
 
-    const command = next.mode === "shell" ? undefined : selectedCommand(next.text, next.command)
+    const command = next.mode === "shell" ? undefined : selectedCommand(next.text, next.command, input.commands())
     if (!command && next.mode !== "shell" && isExitCommand(next.text)) {
       input.onExit()
       return

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

@@ -55,6 +55,9 @@ export function RunFooterSubagentBody(props: {
   diffStyle?: RunDiffStyle
   onCycle: (dir: -1 | 1) => void
   onClose: () => void
+  // Formatted interrupt shortcut from the registered keymap binding; the
+  // command itself is dispatched through the keymap in footer.view.
+  interrupt?: () => string | undefined
 }) {
   const theme = createMemo(() => props.theme())
   const footer = createMemo(() => theme().footer)
@@ -91,6 +94,11 @@ export function RunFooterSubagentBody(props: {
   ))
   let scroll: ScrollBoxRenderable | undefined
 
+  const interruptHint = createMemo(() => {
+    if (tab()?.status !== "running") return undefined
+    return props.interrupt?.()
+  })
+
   useKeyboard((event) => {
     if (!props.active()) {
       return
@@ -141,6 +149,13 @@ export function RunFooterSubagentBody(props: {
                   <span style={{ fg: footer().muted }}>{"  " + subtitle()}</span>
                 </Show>
               </text>
+              <Show when={interruptHint()}>
+                {(hint) => (
+                  <text fg={footer().muted} wrapMode="none" truncate flexShrink={0}>
+                    {hint()} interrupt
+                  </text>
+                )}
+              </Show>
               <Show when={props.total() > 1 && props.index() > 0}>
                 <text fg={footer().muted} wrapMode="none" truncate flexShrink={0}>
                   {props.index()} of {props.total()}

packages/cli/src/mini/footer.ts

@@ -55,7 +55,7 @@ import type {
   RunInput,
   RunPrompt,
   RunProvider,
-  RunResource,
+  RunReference,
   RunTuiConfig,
   StreamCommit,
 } from "./types"
@@ -71,7 +71,7 @@ type RunFooterOptions = {
   directory: string
   findFiles: (query: string) => Promise<string[]>
   agents: RunAgent[]
-  resources: RunResource[]
+  references: RunReference[]
   commands?: RunCommand[]
   wrote?: boolean
   sessionID: () => string | undefined
@@ -97,6 +97,7 @@ type RunFooterOptions = {
   onEditorOpen: (input: { value: string }) => Promise<string | undefined>
   onExit?: () => void
   onSubagentSelect?: (sessionID: string | undefined) => void
+  onSubagentInterrupt?: (sessionID: string) => void
   treeSitterClient?: TreeSitterClient
 }
 
@@ -180,8 +181,8 @@ export class RunFooter implements FooterApi {
   private rows = TEXTAREA_MIN_ROWS
   private agents: Accessor<RunAgent[]>
   private setAgents: Setter<RunAgent[]>
-  private resources: Accessor<RunResource[]>
-  private setResources: Setter<RunResource[]>
+  private references: Accessor<RunReference[]>
+  private setReferences: Setter<RunReference[]>
   private commands: Accessor<RunCommand[] | undefined>
   private setCommands: Setter<RunCommand[] | undefined>
   private providers: Accessor<RunProvider[] | undefined>
@@ -202,6 +203,8 @@ export class RunFooter implements FooterApi {
   private setSubagent: (next: FooterSubagentState) => void
   private queuedPrompts: Accessor<FooterQueuedPrompt[]>
   private setQueuedPrompts: Setter<FooterQueuedPrompt[]>
+  private history: Accessor<RunPrompt[]>
+  private setHistory: Setter<RunPrompt[]>
   private promptRoute: FooterPromptRoute = { type: "composer" }
   private subagentMenuRows = SUBAGENT_ROWS
   private autocomplete = false
@@ -255,9 +258,9 @@ export class RunFooter implements FooterApi {
     const [agents, setAgents] = createSignal(options.agents)
     this.agents = agents
     this.setAgents = setAgents
-    const [resources, setResources] = createSignal(options.resources)
-    this.resources = resources
-    this.setResources = setResources
+    const [references, setReferences] = createSignal(options.references)
+    this.references = references
+    this.setReferences = setReferences
     const [commands, setCommands] = createSignal<RunCommand[] | undefined>(options.commands)
     this.commands = commands
     this.setCommands = setCommands
@@ -288,6 +291,9 @@ export class RunFooter implements FooterApi {
     const [queuedPrompts, setQueuedPrompts] = createSignal<FooterQueuedPrompt[]>([])
     this.queuedPrompts = queuedPrompts
     this.setQueuedPrompts = setQueuedPrompts
+    const [history, setHistory] = createSignal(options.history ?? [])
+    this.history = history
+    this.setHistory = setHistory
     this.base = Math.max(1, renderer.footerHeight - TEXTAREA_MIN_ROWS)
     this.scrollback = this.createScrollback(options.wrote ?? false)
 
@@ -311,7 +317,7 @@ export class RunFooter implements FooterApi {
               queuedPrompts: footer.queuedPrompts,
               findFiles: options.findFiles,
               agents: footer.agents,
-              resources: footer.resources,
+              references: footer.references,
               commands: footer.commands,
               providers: footer.providers,
               currentModel: footer.currentModel,
@@ -321,7 +327,7 @@ export class RunFooter implements FooterApi {
               diffStyle: options.diffStyle,
               tuiConfig: options.tuiConfig,
               backgroundSubagents: options.backgroundSubagents,
-              history: options.history,
+              history: footer.history,
               agent: options.agentLabel,
               onSubmit: footer.handlePrompt,
               onPermissionReply: footer.handlePermissionReply,
@@ -341,6 +347,7 @@ export class RunFooter implements FooterApi {
               onLayout: footer.syncLayout,
               onStatus: footer.setStatus,
               onSubagentSelect: options.onSubagentSelect,
+              onSubagentInterrupt: options.onSubagentInterrupt,
               onQueuedRemove: footer.handleQueuedRemove,
             })
           },
@@ -388,6 +395,15 @@ export class RunFooter implements FooterApi {
   }
 
   public event(next: FooterEvent): void {
+    if (next.type === "history") {
+      this.setHistory(next.history)
+      return
+    }
+
+    if (next.type === "model") {
+      this.setCurrentModel(next.selection)
+    }
+
     if (next.type === "turn.duration") {
       const current = this.currentModel()
       this.flush()
@@ -411,7 +427,7 @@ export class RunFooter implements FooterApi {
       }
 
       this.setAgents(next.agents)
-      this.setResources(next.resources)
+      this.setReferences(next.references)
       if (next.commands !== undefined) {
         this.setCommands(next.commands)
       }

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

@@ -50,7 +50,7 @@ import type {
   RunInput,
   RunPrompt,
   RunProvider,
-  RunResource,
+  RunReference,
   RunTuiConfig,
 } from "./types"
 import type { RunTheme } from "./theme"
@@ -76,7 +76,7 @@ type RunFooterViewProps = {
   directory: string
   findFiles: (query: string) => Promise<string[]>
   agents: () => RunAgent[]
-  resources: () => RunResource[]
+  references: () => RunReference[]
   commands: () => RunCommand[] | undefined
   providers: () => RunProvider[] | undefined
   currentModel: () => RunInput["model"]
@@ -90,7 +90,7 @@ type RunFooterViewProps = {
   diffStyle?: RunDiffStyle
   tuiConfig: RunTuiConfig
   backgroundSubagents: boolean
-  history?: RunPrompt[]
+  history?: () => RunPrompt[]
   agent: string
   onSubmit: (input: RunPrompt) => boolean
   onPermissionReply: (input: PermissionReply) => void | Promise<void>
@@ -110,6 +110,7 @@ type RunFooterViewProps = {
   onLayout: (input: { route: FooterPromptRoute; autocomplete: boolean; subagentRows: number }) => void
   onStatus: (text: string) => void
   onSubagentSelect?: (sessionID: string | undefined) => void
+  onSubagentInterrupt?: (sessionID: string) => void
   onQueuedRemove: (messageID: string) => Promise<boolean>
 }
 
@@ -215,6 +216,15 @@ export function RunFooterView(props: RunFooterViewProps) {
         props.tuiConfig,
       ) ?? "",
   )
+  const subagentInterruptShortcut = useKeymapSelector(
+    (keymap: OpenTuiKeymap) =>
+      formatKeySequence(
+        keymap
+          .getCommandBindings({ visibility: "registered", commands: ["subagent.interrupt"] })
+          .get("subagent.interrupt")?.[0]?.sequence,
+        props.tuiConfig,
+      ) ?? "",
+  )
   const interrupt = useKeymapSelector(
     (keymap: OpenTuiKeymap) =>
       formatKeySequence(
@@ -360,7 +370,7 @@ export function RunFooterView(props: RunFooterViewProps) {
     directory: props.directory,
     findFiles: props.findFiles,
     agents: props.agents,
-    resources: props.resources,
+    references: props.references,
     commands: props.commands,
     tuiConfig: props.tuiConfig,
     state: props.state,
@@ -522,7 +532,7 @@ export function RunFooterView(props: RunFooterViewProps) {
 
   useBindings(() => ({
     mode: OPENCODE_BASE_MODE,
-    enabled: active().type === "prompt" && route().type === "composer" && foregroundSubagents(),
+    enabled: active().type === "prompt" && route().type === "composer" && foregroundSubagents() && !!props.onBackground,
     priority: 1,
     commands: [
       {
@@ -563,6 +573,32 @@ export function RunFooterView(props: RunFooterViewProps) {
     bindings: props.tuiConfig.keybinds.get("session.queued_prompts"),
   }))
 
+  useBindings(() => ({
+    mode: OPENCODE_BASE_MODE,
+    enabled:
+      active().type === "prompt" &&
+      route().type === "subagent" &&
+      selectedTab()?.status === "running" &&
+      !!props.onSubagentInterrupt,
+    priority: 1,
+    commands: [
+      {
+        name: "subagent.interrupt",
+        title: "Interrupt subagent",
+        category: "Session",
+        run: () => {
+          const current = selectedTab()
+          if (current?.status !== "running") {
+            return
+          }
+
+          props.onSubagentInterrupt?.(current.sessionID)
+        },
+      },
+    ],
+    bindings: [{ key: "ctrl+d", desc: "Interrupt subagent", group: "Subagents", cmd: "subagent.interrupt" }],
+  }))
+
   createEffect(() => {
     const current = route()
     if (current.type !== "subagent") {
@@ -747,6 +783,7 @@ export function RunFooterView(props: RunFooterViewProps) {
                                 command: {
                                   name,
                                   arguments: "",
+                                  source: "skill",
                                 },
                               })
                               closePanel()
@@ -937,6 +974,7 @@ export function RunFooterView(props: RunFooterViewProps) {
             diffStyle={props.diffStyle}
             onCycle={cycleTab}
             onClose={closeTab}
+            interrupt={() => subagentInterruptShortcut() || undefined}
           />
         </box>
       </Show>

packages/cli/src/mini/index.ts

@@ -0,0 +1,7 @@
+export { runMini, mergeInput as mergeInteractiveInput, type MiniCommandInput } from "./mini"
+export {
+  runNonInteractive,
+  mergeInput as mergeNonInteractiveInput,
+  pickRunModel,
+  type RunCommandInput,
+} from "./run"

packages/cli/src/mini/mini.ts

@@ -0,0 +1,234 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { OpenCode, type OpenCodeClient } from "@opencode-ai/client/promise"
+import { truthy } from "@opencode-ai/core/flag/flag"
+import { Global } from "@opencode-ai/core/global"
+import { Effect } from "effect"
+import path from "node:path"
+import { Daemon } from "../daemon"
+import { waitForCatalogReady } from "./catalog.shared"
+import { INTERACTIVE_INPUT_ERROR, resolveInteractiveStdin } from "./runtime.stdin"
+import type { RunInput, RunTuiConfig } from "./types"
+
+export type MiniCommandInput = {
+  directory?: string
+  attach?: string
+  password?: string
+  username?: string
+  continue?: boolean
+  session?: string
+  fork?: boolean
+  model?: string
+  agent?: string
+  prompt?: string
+  replay?: boolean
+  replayLimit?: number
+  demo?: boolean
+  serverCommand?: ReadonlyArray<string>
+  tuiConfig?: RunTuiConfig | Promise<RunTuiConfig>
+}
+
+type Session = Awaited<ReturnType<OpenCodeClient["session"]["get"]>>
+type Transport = { readonly url: string; readonly headers?: HeadersInit }
+
+export async function runMini(input: MiniCommandInput) {
+  validate(input)
+  const initialInput = mergeInput(process.stdin.isTTY ? undefined : await Bun.stdin.text(), input.prompt)
+  const runtimeTask = import("./runtime")
+  const directory = input.attach ? input.directory : localDirectory(input.directory)
+  const transportTask = startTransport(input)
+  void transportTask.catch(() => {})
+
+  try {
+    if (input.attach) await transportTask
+    const sdk = OpenCode.make({
+      baseUrl: "http://opencode.pending",
+      fetch: deferredFetch(transportTask),
+    })
+    const attachedSession =
+      input.attach && input.session && !input.directory
+        ? await sdk.session.get({ sessionID: input.session }).catch(() => fail("Session not found"))
+        : undefined
+    const resolvedDirectory =
+      directory ?? attachedSession?.location.directory ?? (await remoteDirectory(await transportTask, sdk))
+    const model = parseModel(input.model)
+    let agentTask: Promise<string | undefined> | undefined
+    const resolveAgent = () => {
+      agentTask ??= validateAgent(sdk, resolvedDirectory, input.agent, input.attach)
+      return agentTask
+    }
+    const resolveSession = async () => {
+      const [agent, selected] = await Promise.all([
+        resolveAgent(),
+        selectSession(sdk, resolvedDirectory, input, attachedSession),
+      ])
+      const readyModel =
+        model ?? (selected?.model ? { providerID: selected.model.providerID, modelID: selected.model.id } : undefined)
+      if (readyModel) await waitForCatalogReady({ sdk, directory: resolvedDirectory, model: readyModel })
+      const session = selected ?? (await createSession(sdk, resolvedDirectory, agent, model))
+      return { id: session.id, title: session.title, resume: selected !== undefined }
+    }
+    const create = (
+      _sdk: OpenCodeClient,
+      next: { agent: string | undefined; model: RunInput["model"]; variant: string | undefined },
+    ) => createSession(sdk, resolvedDirectory, next.agent, next.model, next.variant)
+    const runtime = await runtimeTask
+    await runtime.runInteractiveDeferredMode({
+      sdk,
+      directory: resolvedDirectory,
+      resolveAgent,
+      session: resolveSession,
+      createSession: create,
+      agent: input.agent,
+      model,
+      variant: undefined,
+      files: [],
+      initialInput,
+      thinking: true,
+      backgroundSubagents:
+        truthy("OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS") ||
+        (process.env.OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS === undefined && truthy("OPENCODE_EXPERIMENTAL")),
+      replay: input.replay ?? true,
+      replayLimit: input.replayLimit,
+      demo: input.demo,
+      tuiConfig: input.tuiConfig,
+    })
+  } catch (error) {
+    if (error instanceof Error && error.message === INTERACTIVE_INPUT_ERROR) fail(error.message)
+    throw error
+  }
+}
+
+/** @internal Exported for testing. */
+export function mergeInput(piped: string | undefined, prompt: string | undefined) {
+  if (!prompt) return piped || undefined
+  if (!piped) return prompt
+  return piped + "\n" + prompt
+}
+
+function validate(input: MiniCommandInput) {
+  if (!process.stdout.isTTY) fail("opencode mini requires a TTY stdout")
+  if (input.replayLimit !== undefined && (!Number.isInteger(input.replayLimit) || input.replayLimit <= 0)) {
+    fail("--replay-limit must be a positive integer")
+  }
+  if (input.fork && !input.continue && !input.session) fail("--fork requires --continue or --session")
+  resolveInteractiveStdin().cleanup?.()
+}
+
+function localDirectory(directory?: string): string {
+  const root = process.env.PWD ?? process.cwd()
+  try {
+    process.chdir(directory ? (path.isAbsolute(directory) ? directory : path.join(root, directory)) : root)
+    return process.cwd()
+  } catch {
+    fail(`Failed to change directory to ${directory}`)
+  }
+}
+
+function startTransport(input: MiniCommandInput): Promise<Transport> {
+  if (input.attach) {
+    return Effect.runPromise(
+      Daemon.transport({
+        mode: "attach",
+        url: input.attach,
+        password: input.password ?? process.env.OPENCODE_SERVER_PASSWORD,
+        username: input.username ?? process.env.OPENCODE_SERVER_USERNAME,
+      }),
+    )
+  }
+  return Effect.runPromise(
+    Daemon.transport({ mode: "shared", command: input.serverCommand }).pipe(
+      Effect.provide(NodeFileSystem.layer),
+      Effect.provide(Global.layerWith({})),
+    ),
+  )
+}
+
+function deferredFetch(transportTask: Promise<{ url: string; headers?: HeadersInit }>): typeof globalThis.fetch {
+  const fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+    const transport = await transportTask
+    const request = new Request(input, init)
+    const source = new URL(request.url)
+    const headers = new Headers(request.headers)
+    for (const [key, value] of new Headers(transport.headers)) headers.set(key, value)
+    return globalThis.fetch(new Request(new URL(source.pathname + source.search, transport.url), request), { headers })
+  }
+  return fetch as typeof globalThis.fetch
+}
+
+async function remoteDirectory(
+  transport: { url: string; headers?: HeadersInit },
+  sdk: OpenCodeClient,
+): Promise<string> {
+  const location = await sdk.location.get()
+  if (!location.directory) throw new Error(`Failed to resolve remote directory from ${transport.url}`)
+  return location.directory
+}
+
+function parseModel(value?: string): RunInput["model"] {
+  if (!value) return
+  const [providerID, ...rest] = value.split("/")
+  const modelID = rest.join("/")
+  if (!providerID || !modelID) fail("--model must use the format provider/model")
+  return { providerID, modelID }
+}
+
+async function validateAgent(sdk: OpenCodeClient, directory: string, name?: string, attach?: string) {
+  if (!name) return
+  const deadline = Date.now() + 5_000
+  let agents: Awaited<ReturnType<OpenCodeClient["agent"]["list"]>> | undefined
+  while (Date.now() < deadline) {
+    agents = await sdk.agent.list({ location: { directory } }).catch(() => undefined)
+    const agent = agents?.data.find((item) => item.id === name)
+    if (agent?.mode === "subagent") {
+      warning(`agent "${name}" is a subagent, not a primary agent. Falling back to default agent`)
+      return
+    }
+    if (agent) return name
+    await Bun.sleep(25)
+  }
+  if (!agents) {
+    warning(`failed to list agents${attach ? ` from ${attach}` : ""}. Falling back to default agent`)
+    return
+  }
+  warning(`agent "${name}" not found. Falling back to default agent`)
+}
+
+async function selectSession(sdk: OpenCodeClient, directory: string, input: MiniCommandInput, preselected?: Session) {
+  const selected =
+    preselected ??
+    (input.session
+      ? await sdk.session.get({ sessionID: input.session }).catch(() => undefined)
+      : input.continue
+        ? await sdk.session
+            .list({ directory, parentID: null, limit: 1, order: "desc" })
+            .then((result) => result.data[0])
+        : undefined)
+  if (input.session && !selected) fail("Session not found")
+  if (!selected) return
+  if (!input.fork) return selected
+  return sdk.session.fork({ sessionID: selected.id })
+}
+
+async function createSession(
+  sdk: OpenCodeClient,
+  directory: string,
+  agent: string | undefined,
+  model: RunInput["model"],
+  variant?: string,
+): Promise<Session> {
+  if (model) await waitForCatalogReady({ sdk, directory, model })
+  return sdk.session.create({
+    agent,
+    model: model ? { providerID: model.providerID, id: model.modelID, variant } : undefined,
+    location: { directory },
+  })
+}
+
+function warning(message: string) {
+  process.stderr.write(`\x1b[93m\x1b[1m!\x1b[0m ${message}\n`)
+}
+
+function fail(message: string): never {
+  process.stderr.write(`\x1b[91m\x1b[1mError: \x1b[0m${message}\n`)
+  process.exit(1)
+}

packages/cli/src/mini/noninteractive.ts

@@ -0,0 +1,491 @@
+import type { EventSubscribeOutput, OpenCodeClient } from "@opencode-ai/client/promise"
+import type { ReasoningPart, StepFinishPart, StepStartPart, TextPart, ToolPart } from "@opencode-ai/sdk/v2"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { EOL } from "node:os"
+import { UI } from "./ui"
+
+type Model = {
+  providerID: string
+  modelID: string
+}
+
+type File = {
+  url: string
+  filename: string
+  mime: string
+}
+
+type Input = {
+  client: OpenCodeClient
+  sessionID: string
+  message: string
+  files: File[]
+  agent?: string
+  model?: Model
+  variant?: string
+  thinking: boolean
+  format: "default" | "json"
+  dangerouslySkipPermissions: boolean
+  /** True when the client is attached to a shared server rather than an exclusive in-process one. */
+  attached: boolean
+  renderTool: (part: ToolPart) => Promise<void>
+  renderToolError: (part: ToolPart) => Promise<void>
+}
+
+type StartedPart = {
+  id: string
+  timestamp: number
+}
+
+type ToolState = StartedPart & {
+  assistantMessageID: string
+  tool: string
+  input: Record<string, unknown>
+  raw?: string
+  provider?: unknown
+}
+
+type V2Event = EventSubscribeOutput
+type FormRequest = Extract<V2Event, { type: "form.created" }>["data"]["form"]
+
+// MCP elicitations are temporarily owned by the "global" sentinel instead of a real
+// session. An exclusive local process may treat them as this run's blockers; an
+// attached client must not cancel input that may belong to another session.
+const GLOBAL_FORM_SESSION_ID = "global"
+
+export async function runNonInteractivePrompt(input: Input) {
+  const controller = new AbortController()
+  const stream = input.client.event.subscribe({ signal: controller.signal })[Symbol.asyncIterator]()
+  const connected = await stream.next()
+  if (connected.done) throw new Error("Event stream disconnected before prompt admission")
+
+  const messageID = SessionMessage.ID.create()
+  const starts = new Map<string, StartedPart>()
+  const tools = new Map<string, ToolState>()
+  let submitted = false
+  let promoted = false
+  let emittedError = false
+  let questionRejected = false
+  let permissionRejected = false
+  let formCancelled = false
+  let interrupted = false
+  let admission: AbortController | undefined
+
+  const emit = (type: string, timestamp: number, data: Record<string, unknown>) => {
+    if (input.format !== "json") return false
+    process.stdout.write(JSON.stringify({ type, timestamp, sessionID: input.sessionID, ...data }) + EOL)
+    return true
+  }
+
+  const writeText = (part: TextPart, timestamp: number) => {
+    if (emit("text", timestamp, { part })) return
+    const text = part.text.trim()
+    if (!text) return
+    if (!process.stdout.isTTY) {
+      process.stdout.write(text + EOL)
+      return
+    }
+    UI.empty()
+    UI.println(text)
+    UI.empty()
+  }
+
+  const replyPermission = async (request: { id: string; action: string; resources: ReadonlyArray<string> }) => {
+    if (!input.dangerouslySkipPermissions) {
+      permissionRejected = true
+      UI.println(
+        UI.Style.TEXT_WARNING_BOLD + "!",
+        UI.Style.TEXT_NORMAL +
+          `permission requested: ${request.action} (${request.resources.join(", ")}); auto-rejecting`,
+      )
+    }
+    await input.client.permission
+      .reply({
+        sessionID: input.sessionID,
+        requestID: request.id,
+        reply: input.dangerouslySkipPermissions ? "once" : "reject",
+      })
+      .catch(() => {})
+    if (!input.dangerouslySkipPermissions) {
+      await input.client.session.interrupt({ sessionID: input.sessionID }).catch(() => {})
+    }
+  }
+
+  const rejectQuestion = async (request: { id: string }) => {
+    questionRejected = true
+    await input.client.question.reject({ sessionID: input.sessionID, requestID: request.id }).catch(() => {})
+  }
+
+  const cancelForm = async (request: Pick<FormRequest, "id" | "sessionID">) => {
+    formCancelled = true
+    await input.client.form.cancel({ sessionID: request.sessionID, formID: request.id }).catch(() => {})
+  }
+
+  const consume = async () => {
+    while (!controller.signal.aborted) {
+      const next = await stream.next().catch((error) => {
+        if (!emittedError) throw error
+        return { done: true as const, value: undefined }
+      })
+      if (next.done) {
+        if (emittedError) return
+        throw new Error("Event stream disconnected during prompt execution")
+      }
+      const event = next.value
+
+      if (event.type === "permission.v2.asked" && submitted && event.data.sessionID === input.sessionID) {
+        await replyPermission(event.data)
+        continue
+      }
+      if (event.type === "question.v2.asked" && submitted && event.data.sessionID === input.sessionID) {
+        await rejectQuestion(event.data)
+        continue
+      }
+      if (
+        event.type === "form.created" &&
+        submitted &&
+        (event.data.form.sessionID === input.sessionID ||
+          (!input.attached && event.data.form.sessionID === GLOBAL_FORM_SESSION_ID))
+      ) {
+        await cancelForm(event.data.form)
+        continue
+      }
+      if (!("sessionID" in event.data) || event.data.sessionID !== input.sessionID) continue
+      const time = toMillis("created" in event ? event.created : undefined)
+
+      if (event.type === "session.prompt.promoted") {
+        if (event.data.inputID === messageID) {
+          promoted = true
+          continue
+        }
+      }
+      if (
+        event.type === "session.execution.interrupted" &&
+        event.data.reason === "user" &&
+        (interrupted || permissionRejected || questionRejected || formCancelled)
+      ) {
+        return
+      }
+      if (!promoted) continue
+
+      if (event.type === "session.step.started") {
+        const part: StepStartPart = {
+          id: partID(event.id),
+          sessionID: input.sessionID,
+          messageID: event.data.assistantMessageID,
+          type: "step-start",
+          snapshot: event.data.snapshot,
+        }
+        if (!emit("step_start", time, { part }) && input.format !== "json") {
+          UI.empty()
+          UI.println(`> ${event.data.agent} · ${event.data.model.id}`)
+          UI.empty()
+        }
+        continue
+      }
+
+      if (event.type === "session.text.started") {
+        starts.set("text", { id: partID(event.id), timestamp: time })
+        continue
+      }
+      if (event.type === "session.text.ended") {
+        const started = starts.get("text")
+        starts.delete("text")
+        const part: TextPart = {
+          id: started?.id ?? partID(event.id),
+          sessionID: input.sessionID,
+          messageID: event.data.assistantMessageID,
+          type: "text",
+          text: event.data.text,
+          time: { start: started?.timestamp ?? time, end: time },
+        }
+        writeText(part, time)
+        continue
+      }
+
+      if (event.type === "session.reasoning.started") {
+        starts.set("reasoning", { id: partID(event.id), timestamp: time })
+        continue
+      }
+      if (event.type === "session.reasoning.ended" && input.thinking) {
+        const started = starts.get("reasoning")
+        starts.delete("reasoning")
+        const part: ReasoningPart = {
+          id: started?.id ?? partID(event.id),
+          sessionID: input.sessionID,
+          messageID: event.data.assistantMessageID,
+          type: "reasoning",
+          text: event.data.text,
+          metadata: event.data.state,
+          time: { start: started?.timestamp ?? time, end: time },
+        }
+        if (emit("reasoning", time, { part })) continue
+        const text = part.text.trim()
+        if (!text) continue
+        const line = `Thinking: ${text}`
+        if (!process.stdout.isTTY) {
+          process.stdout.write(line + EOL)
+          continue
+        }
+        UI.empty()
+        UI.println(`${UI.Style.TEXT_DIM}\u001b[3m${line}\u001b[0m${UI.Style.TEXT_NORMAL}`)
+        UI.empty()
+        continue
+      }
+
+      if (event.type === "session.tool.input.started") {
+        tools.set(event.data.callID, {
+          id: partID(event.id),
+          timestamp: time,
+          assistantMessageID: event.data.assistantMessageID,
+          tool: event.data.name,
+          input: {},
+        })
+        continue
+      }
+      if (event.type === "session.tool.input.ended") {
+        const current = tools.get(event.data.callID)
+        if (current) current.raw = event.data.text
+        continue
+      }
+      if (event.type === "session.tool.called") {
+        const current = tools.get(event.data.callID)
+        tools.set(event.data.callID, {
+          id: current?.id ?? partID(event.id),
+          timestamp: current?.timestamp ?? time,
+          assistantMessageID: event.data.assistantMessageID,
+          tool: current?.tool ?? "tool",
+          input: event.data.input,
+          raw: current?.raw,
+          provider: { executed: event.data.executed, state: event.data.state },
+        })
+        continue
+      }
+      if (event.type === "session.tool.success") {
+        const current = tools.get(event.data.callID) ?? fallbackTool(event)
+        const part: ToolPart = {
+          id: current.id,
+          sessionID: input.sessionID,
+          messageID: event.data.assistantMessageID,
+          type: "tool",
+          callID: event.data.callID,
+          tool: current.tool,
+          state: {
+            status: "completed",
+            input: current.input,
+            output: event.data.content
+              .filter((item) => item.type === "text")
+              .map((item) => item.text)
+              .join("\n"),
+            title: current.tool,
+            metadata: {
+              structured: event.data.structured,
+              content: event.data.content,
+              outputPaths: event.data.outputPaths,
+              result: event.data.result,
+              providerCall: current.provider,
+              providerResult: { executed: event.data.executed, state: event.data.resultState },
+              rawInput: current.raw,
+            },
+            time: { start: current.timestamp, end: time },
+          },
+        }
+        tools.delete(event.data.callID)
+        if (!emit("tool_use", time, { part })) await input.renderTool(part)
+        continue
+      }
+      if (event.type === "session.tool.failed") {
+        const current = tools.get(event.data.callID) ?? fallbackTool(event)
+        const error = event.data.error.message
+        const part: ToolPart = {
+          id: current.id,
+          sessionID: input.sessionID,
+          messageID: event.data.assistantMessageID,
+          type: "tool",
+          callID: event.data.callID,
+          tool: current.tool,
+          state: {
+            status: "error",
+            input: current.input,
+            error,
+            metadata: {
+              result: event.data.result,
+              providerCall: current.provider,
+              providerResult: { executed: event.data.executed, state: event.data.resultState },
+              rawInput: current.raw,
+            },
+            time: { start: current.timestamp, end: time },
+          },
+        }
+        tools.delete(event.data.callID)
+        if (!emit("tool_use", time, { part })) {
+          await input.renderToolError(part)
+          UI.error(error)
+        }
+        continue
+      }
+
+      if (event.type === "session.step.ended") {
+        const part: StepFinishPart = {
+          id: partID(event.id),
+          sessionID: input.sessionID,
+          messageID: event.data.assistantMessageID,
+          type: "step-finish",
+          reason: event.data.finish,
+          snapshot: event.data.snapshot,
+          cost: event.data.cost,
+          tokens: event.data.tokens,
+        }
+        emit("step_finish", time, { part })
+        continue
+      }
+      if (event.type === "session.step.failed") {
+        if (interrupted || permissionRejected || questionRejected || formCancelled) continue
+        emittedError = true
+        process.exitCode = 1
+        if (!emit("error", time, { error: event.data.error })) UI.error(event.data.error.message)
+        continue
+      }
+      if (event.type === "session.execution.failed") {
+        if (!emittedError && !questionRejected && !formCancelled) {
+          emittedError = true
+          process.exitCode = 1
+          if (!emit("error", time, { error: event.data.error })) UI.error(event.data.error.message)
+        }
+        return
+      }
+      if (event.type === "session.execution.interrupted") {
+        if (event.data.reason === "user" && interrupted) process.exitCode = 130
+        if (event.data.reason !== "user" && !emittedError) {
+          emittedError = true
+          process.exitCode = 1
+          const error = { type: "aborted" as const, message: `Session interrupted: ${event.data.reason}` }
+          if (!emit("error", time, { error })) UI.error(error.message)
+        }
+        return
+      }
+      if (event.type === "session.execution.succeeded") return
+    }
+  }
+
+  const interrupt = () => {
+    if (interrupted) process.exit(130)
+    interrupted = true
+    process.exitCode = 130
+    admission?.abort()
+    void input.client.session.interrupt({ sessionID: input.sessionID }).catch(() => {})
+  }
+  process.on("SIGINT", interrupt)
+
+  let completed: Promise<void> | undefined
+  try {
+    if (input.agent) {
+      await input.client.session.switchAgent({ sessionID: input.sessionID, agent: input.agent })
+    }
+    const selected = input.model
+      ? { providerID: input.model.providerID, id: input.model.modelID, variant: input.variant }
+      : input.variant
+        ? await input.client.session
+            .get({ sessionID: input.sessionID })
+            .then((result) => result.model)
+            .then(async (model) => {
+              if (model) return { ...model, variant: input.variant }
+              const result = await input.client.model.default()
+              const fallback = result.data
+              return fallback ? { providerID: fallback.providerID, id: fallback.id, variant: input.variant } : undefined
+            })
+        : undefined
+    if (input.variant && !selected) throw new Error("Cannot select a variant before selecting a model")
+    if (selected) {
+      await input.client.session.switchModel({ sessionID: input.sessionID, model: selected })
+    }
+
+    const prepared = await Promise.all(input.files.map(prepareFile))
+    if (interrupted) return
+    submitted = true
+    completed = consume()
+    admission = new AbortController()
+    const response = await input.client.session
+      .prompt(
+        {
+          sessionID: input.sessionID,
+          id: messageID,
+          prompt: {
+            text: [input.message, ...prepared.flatMap((file) => (file.text ? [file.text] : []))].join("\n\n"),
+            files: prepared.flatMap((file) => (file.attachment ? [file.attachment] : [])),
+          },
+          delivery: "steer",
+        },
+        { signal: admission.signal },
+      )
+      .catch(async (error) => {
+        if (interrupted) {
+          await input.client.session.interrupt({ sessionID: input.sessionID }).catch(() => {})
+        }
+        controller.abort()
+        await completed?.catch(() => {})
+        if (interrupted || emittedError) return undefined
+        throw error
+      })
+    admission = undefined
+    if (!response) return
+    if (interrupted) await input.client.session.interrupt({ sessionID: input.sessionID }).catch(() => {})
+
+    const [permissions, questions, forms] = await Promise.all([
+      input.client.permission.list({ sessionID: input.sessionID }).catch(() => undefined),
+      input.client.question.list({ sessionID: input.sessionID }).catch(() => undefined),
+      Promise.all(
+        (input.attached ? [input.sessionID] : [input.sessionID, GLOBAL_FORM_SESSION_ID]).map((sessionID) =>
+          input.client.form.list({ sessionID }).catch(() => undefined),
+        ),
+      ),
+    ])
+    await Promise.all([
+      ...(permissions ?? []).map(replyPermission),
+      ...(questions ?? []).map(rejectQuestion),
+      ...forms.flatMap((response) => response ?? []).map(cancelForm),
+    ])
+    await completed
+  } finally {
+    process.off("SIGINT", interrupt)
+    controller.abort()
+    await stream.return?.(undefined).catch(() => {})
+  }
+}
+
+function partID(eventID: string) {
+  return `prt_${eventID.replace(/^evt_/, "")}`
+}
+
+function fallbackTool(event: {
+  id: string
+  created: number
+  data: { assistantMessageID: string; callID: string }
+}): ToolState {
+  return {
+    id: partID(event.id),
+    timestamp: toMillis(event.created),
+    assistantMessageID: event.data.assistantMessageID,
+    tool: "tool",
+    input: {},
+  }
+}
+
+function toMillis(value: unknown) {
+  if (typeof value === "number") return value
+  if (typeof value === "string") return new Date(value).getTime()
+  return Date.now()
+}
+
+async function prepareFile(file: File) {
+  if (file.mime !== "text/plain") {
+    const uri = file.url.startsWith("data:")
+      ? file.url
+      : `data:${file.mime};base64,${Buffer.from(await Bun.file(new URL(file.url)).arrayBuffer()).toString("base64")}`
+    return { attachment: { uri, mime: file.mime, name: file.filename } }
+  }
+  const content = file.url.startsWith("data:")
+    ? Buffer.from(file.url.slice(file.url.indexOf(",") + 1), "base64").toString("utf8")
+    : await Bun.file(new URL(file.url)).text()
+  return { text: `<file name="${file.filename}">\n${content}\n</file>` }
+}

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

@@ -150,8 +150,11 @@ export function permissionReply(requestID: string, reply: PermissionReply["reply
   }
 }
 
-export function permissionShift(state: PermissionBodyState, dir: -1 | 1): PermissionBodyState {
-  const list = permissionOptions(state.stage)
+export function permissionShift(
+  state: PermissionBodyState,
+  dir: -1 | 1,
+  list = permissionOptions(state.stage),
+): PermissionBodyState {
   if (list.length === 0) {
     return state
   }

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

@@ -7,7 +7,7 @@
 // the current browse position. When the user arrows up at cursor offset 0,
 // the current draft is saved and history begins. Arrowing past the end
 // restores the draft.
-export { displayCharAt, displaySlice, mentionTriggerIndex } from "../prompt-display"
+export { displayCharAt, displaySlice, mentionTriggerIndex } from "@opencode-ai/tui/prompt/display"
 import type { RunPrompt } from "./types"
 
 const HISTORY_LIMIT = 200

packages/cli/src/mini/run.ts

@@ -0,0 +1,311 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { OpenCode, type OpenCodeClient } from "@opencode-ai/client/promise"
+import { Global } from "@opencode-ai/core/global"
+import { FSUtil } from "@opencode-ai/core/fs-util"
+import type { ToolPart } from "@opencode-ai/sdk/v2"
+import { Effect } from "effect"
+import { open } from "node:fs/promises"
+import path from "node:path"
+import { Daemon } from "../daemon"
+import { Standalone } from "../services/standalone"
+import { loadRunAgents, waitForCatalogReady } from "./catalog.shared"
+import { runNonInteractivePrompt } from "./noninteractive"
+import { toolInlineInfo } from "./tool"
+import { UI } from "./ui"
+
+export type RunCommandInput = {
+  message: string[]
+  continue?: boolean
+  session?: string
+  fork?: boolean
+  model?: string
+  agent?: string
+  format: "default" | "json"
+  file: string[]
+  title?: string
+  server?: string
+  password?: string
+  username?: string
+  directory?: string
+  variant?: string
+  thinking?: boolean
+  dangerouslySkipPermissions?: boolean
+  standaloneCommand?: ReadonlyArray<string>
+}
+
+type FilePart = {
+  url: string
+  filename: string
+  mime: string
+}
+
+type Transport = { readonly url: string; readonly headers?: HeadersInit }
+
+type Prepared = {
+  directory?: string
+  message: string
+  files: FilePart[]
+}
+
+const ATTACH_FILE_MAX_BYTES = 10 * 1024 * 1024
+
+export function runNonInteractive(input: RunCommandInput) {
+  return run(input).catch((error) => reportError(input, error instanceof Error ? error.message : String(error)))
+}
+
+async function run(input: RunCommandInput) {
+  if (input.fork && !input.continue && !input.session) fail("--fork requires --continue or --session")
+  const root = process.env.PWD ?? process.cwd()
+  const directory = input.server ? input.directory : localDirectory(input.directory, root)
+  const message = mergeInput(formatMessage(input.message), process.stdin.isTTY ? undefined : await Bun.stdin.text())
+  if (!message?.trim()) fail("You must provide a message")
+  const files = await Promise.all(
+    input.file.map((file) => prepareFile(file, input.server ? root : (directory ?? root), input.server !== undefined)),
+  )
+  const prepared = { directory, message, files }
+  if (input.standaloneCommand)
+    return Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const transport = yield* Standalone.transport({ command: input.standaloneCommand })
+          yield* Effect.promise(() => execute(input, prepared, transport))
+        }),
+      ),
+    )
+  const transport = await startTransport(input)
+  return execute(input, prepared, transport)
+}
+
+async function execute(input: RunCommandInput, prepared: Prepared, transport: Transport) {
+  const client = OpenCode.make({ baseUrl: transport.url, headers: transport.headers })
+  const requestedDirectory = prepared.directory ?? (await client.location.get()).directory
+  if (!requestedDirectory) fail("Failed to resolve server directory")
+  const session = await selectSession(client, requestedDirectory, input)
+  const cwd = session?.location.directory ?? requestedDirectory
+  const workspace = session?.location.workspaceID
+  const explicitModel = parseModel(input.model)
+  const sessionModel = session?.model ? { providerID: session.model.providerID, modelID: session.model.id } : undefined
+  const defaultModel =
+    !explicitModel && !sessionModel
+      ? await client.model
+          .default({ location: { directory: cwd, workspace } })
+          .then((result) =>
+            result.data ? { providerID: result.data.providerID, modelID: result.data.id } : undefined,
+          )
+      : undefined
+  const model = pickRunModel(explicitModel, input.variant, sessionModel, defaultModel)
+  if (input.variant && !model) return reportError(input, "Cannot select a variant before selecting a model", session?.id)
+  if (model) {
+    await waitForCatalogReady({ sdk: client, directory: cwd, workspace, model })
+    const available = await client.model.list({ location: { directory: cwd, workspace } })
+    if (!available.data.some((item) => item.providerID === model.providerID && item.id === model.modelID))
+      return reportError(input, `Model unavailable: ${model.providerID}/${model.modelID}`, session?.id)
+  }
+  const agent = await validateAgent(client, cwd, input.agent, input.server)
+  const selected =
+    session ??
+    (await client.session.create({
+      agent,
+      model: model ? { providerID: model.providerID, id: model.modelID, variant: input.variant } : undefined,
+      location: { directory: cwd },
+    }))
+  if (!session && input.title !== undefined) {
+    await client.session.rename({
+      sessionID: selected.id,
+      title:
+        input.title ||
+        prepared.message.slice(0, 50) + (prepared.message.length > 50 ? "..." : ""),
+    })
+  }
+
+  await runNonInteractivePrompt({
+    client,
+    sessionID: selected.id,
+    message: prepared.message,
+    files: prepared.files,
+    agent,
+    model,
+    variant: input.variant,
+    thinking: input.thinking ?? false,
+    format: input.format,
+    dangerouslySkipPermissions: input.dangerouslySkipPermissions ?? false,
+    attached: !input.standaloneCommand,
+    renderTool,
+    renderToolError,
+  }).catch((error) => reportError(input, error instanceof Error ? error.message : String(error), selected.id))
+}
+
+export function mergeInput(message: string | undefined, piped: string | undefined) {
+  if (!message) return piped || undefined
+  if (!piped) return message
+  return message + "\n" + piped
+}
+
+export function pickRunModel(
+  explicit: { providerID: string; modelID: string } | undefined,
+  variant: string | undefined,
+  session: { providerID: string; modelID: string } | undefined,
+  fallback: { providerID: string; modelID: string } | undefined,
+) {
+  if (explicit) return explicit
+  if (!variant) return
+  return session ?? fallback
+}
+
+function formatMessage(message: string[]) {
+  const value = message.map((part) => (part.includes(" ") ? `"${part.replace(/"/g, '\\"')}"` : part)).join(" ")
+  return value || undefined
+}
+
+function localDirectory(directory: string | undefined, root: string) {
+  try {
+    process.chdir(directory ? (path.isAbsolute(directory) ? directory : path.join(root, directory)) : root)
+    return process.cwd()
+  } catch {
+    fail(`Failed to change directory to ${directory}`)
+  }
+}
+
+function startTransport(input: RunCommandInput) {
+  if (input.server) {
+    return Effect.runPromise(
+      Daemon.transport({
+        mode: "attach",
+        url: input.server,
+        password: input.password,
+        username: input.username,
+      }),
+    )
+  }
+  return Effect.runPromise(
+    Daemon.transport({ mode: "shared" }).pipe(
+      Effect.provide(NodeFileSystem.layer),
+      Effect.provide(Global.layerWith({})),
+    ),
+  )
+}
+
+function parseModel(value?: string) {
+  if (!value) return
+  const [providerID, ...rest] = value.split("/")
+  const modelID = rest.join("/")
+  if (!providerID || !modelID) fail("--model must use the format provider/model")
+  return { providerID, modelID }
+}
+
+async function validateAgent(client: OpenCodeClient, directory: string, name?: string, server?: string) {
+  if (!name) return
+  const agents = await loadRunAgents(client, directory).catch(() => undefined)
+  if (!agents) {
+    warning(`failed to list agents${server ? ` from ${server}` : ""}. Falling back to default agent`)
+    return
+  }
+  const agent = agents.find((item) => item.name === name)
+  if (!agent) {
+    warning(`agent "${name}" not found. Falling back to default agent`)
+    return
+  }
+  if (agent.mode === "subagent") {
+    warning(`agent "${name}" is a subagent, not a primary agent. Falling back to default agent`)
+    return
+  }
+  return name
+}
+
+async function selectSession(client: OpenCodeClient, directory: string, input: RunCommandInput) {
+  const selected = input.session
+    ? await client.session.get({ sessionID: input.session }).catch(() => undefined)
+    : input.continue
+      ? await client.session
+          .list({ directory, parentID: null, limit: 1, order: "desc" })
+          .then((result) => result.data[0])
+      : undefined
+  if (input.session && !selected) fail("Session not found")
+  if (!selected || !input.fork) return selected
+  return client.session.fork({ sessionID: selected.id })
+}
+
+async function prepareFile(input: string, directory: string, remote: boolean): Promise<FilePart> {
+  const file = path.resolve(directory, input)
+  const handle = await open(file, "r").catch(() => fail(`File not found: ${input}`))
+  try {
+    const stat = await handle.stat()
+    if (remote && stat.isDirectory()) fail(`Cannot attach local directory without a shared filesystem: ${input}`)
+    if (!stat.isFile() || stat.size > ATTACH_FILE_MAX_BYTES)
+      fail(`Cannot attach a directory, special file, or file larger than 10 MiB: ${input}`)
+    const content = Buffer.alloc(Number(stat.size))
+    let offset = 0
+    while (offset < content.length) {
+      const read = await handle.read(content, offset, content.length - offset, offset)
+      if (read.bytesRead === 0) break
+      offset += read.bytesRead
+    }
+    const bytes = content.subarray(0, offset)
+    const detected = FSUtil.mimeType(file)
+    const text = bytes.toString("utf8")
+    const mime =
+      detected.startsWith("image/") || detected === "application/pdf"
+        ? detected
+        : !isBinaryContent(bytes) && Buffer.from(text, "utf8").equals(bytes)
+          ? "text/plain"
+          : detected
+    return {
+      url: `data:${mime};base64,${bytes.toString("base64")}`,
+      filename: path.basename(file),
+      mime,
+    }
+  } finally {
+    await handle.close()
+  }
+}
+
+function isBinaryContent(bytes: Uint8Array) {
+  if (bytes.length === 0) return false
+  if (bytes.includes(0)) return true
+  return bytes.reduce((count, byte) => count + Number(byte < 9 || (byte > 13 && byte < 32)), 0) / bytes.length > 0.3
+}
+
+async function renderTool(part: ToolPart) {
+  const info = toolInlineInfo(part)
+  if (info.mode === "block") {
+    UI.empty()
+    UI.println(UI.Style.TEXT_NORMAL + info.icon, UI.Style.TEXT_NORMAL + info.title)
+    if (info.body?.trim()) UI.println(info.body)
+    UI.empty()
+    return
+  }
+  UI.println(
+    UI.Style.TEXT_NORMAL + info.icon,
+    UI.Style.TEXT_NORMAL + info.title,
+    info.description ? UI.Style.TEXT_DIM + info.description + UI.Style.TEXT_NORMAL : "",
+  )
+}
+
+async function renderToolError(part: ToolPart) {
+  const info = toolInlineInfo(part)
+  UI.println(UI.Style.TEXT_NORMAL + "✗", UI.Style.TEXT_NORMAL + `${info.title} failed`)
+}
+
+function warning(message: string) {
+  UI.println(UI.Style.TEXT_WARNING_BOLD + "!", UI.Style.TEXT_NORMAL, message)
+}
+
+function reportError(input: RunCommandInput, message: string, sessionID?: string) {
+  process.exitCode = 1
+  if (input.format === "json") {
+    process.stdout.write(
+      JSON.stringify({
+        type: "error",
+        timestamp: Date.now(),
+        sessionID: sessionID ?? "",
+        error: { type: "unknown", message },
+      }) + "\n",
+    )
+    return
+  }
+  UI.error(message)
+}
+
+function fail(message: string): never {
+  throw new Error(message)
+}

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

@@ -7,10 +7,11 @@
 // none block each other.
 import { Context, Effect, Layer } from "effect"
 import { resolve } from "@opencode-ai/tui/config"
-import { TuiConfig } from "@/config/tui"
-import { makeRuntime } from "@/effect/run-service"
-import { reusePendingTask } from "./runtime.shared"
-import { resolveSession, sessionHistory } from "./session.shared"
+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"
+import { loadRunProviders } from "./catalog.shared"
+import { resolveCurrentSession, sessionHistory } from "./session.shared"
 import type { RunDiffStyle, RunInput, RunPrompt, RunProvider, RunTuiConfig } from "./types"
 import { pickVariant } from "./variant.shared"
 
@@ -23,10 +24,10 @@ export type ModelInfo = {
 export type SessionInfo = {
   first: boolean
   history: RunPrompt[]
+  model?: NonNullable<RunInput["model"]>
   variant: string | undefined
 }
 
-type Config = Awaited<ReturnType<typeof TuiConfig.get>>
 type BootService = {
   readonly resolveModelInfo: (
     sdk: RunInput["sdk"],
@@ -38,18 +39,10 @@ type BootService = {
     sessionID: string,
     model: RunInput["model"],
   ) => Effect.Effect<SessionInfo>
-  readonly resolveRunTuiConfig: () => Effect.Effect<RunTuiConfig>
-  readonly resolveDiffStyle: () => Effect.Effect<RunDiffStyle>
 }
 
-const configTask: { current?: Promise<Config> } = {}
-
 class Service extends Context.Service<Service, BootService>()("@opencode/RunBoot") {}
 
-function loadConfig() {
-  return reusePendingTask(configTask, () => TuiConfig.get())
-}
-
 function emptyModelInfo(): ModelInfo {
   return {
     providers: [],
@@ -73,42 +66,15 @@ function defaultRunTuiConfig(): RunTuiConfig {
   }
 }
 
-function runTuiConfig(config: Config | undefined): RunTuiConfig {
-  if (!config) {
-    return defaultRunTuiConfig()
-  }
-
-  return {
-    keybinds: config.keybinds,
-    leader_timeout: config.leader_timeout,
-    diff_style: config.diff_style ?? "auto",
-  }
-}
-
 const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
-    const config = Effect.fn("RunBoot.config")(() => Effect.promise(() => loadConfig().catch(() => undefined)))
-
     const resolveModelInfo = Effect.fn("RunBoot.resolveModelInfo")(function* (
       sdk: RunInput["sdk"],
       directory: string,
       model: RunInput["model"],
     ) {
-      const connected = yield* Effect.promise(() =>
-        sdk.config
-          .providers({ directory })
-          .then((item) => item.data?.providers)
-          .catch(() => undefined),
-      )
-      const providers = yield* Effect.promise(() =>
-        connected
-          ? Promise.resolve(connected)
-          : sdk.provider
-              .list()
-              .then((item) => item.data?.all ?? [])
-              .catch(() => []),
-      )
+      const providers = yield* Effect.promise(() => loadRunProviders(sdk, directory))
       const limits = Object.fromEntries(
         providers.flatMap((provider) =>
           Object.entries(provider.models ?? {}).flatMap(([modelID, info]) => {
@@ -143,7 +109,7 @@ const layer = Layer.effect(
       sessionID: string,
       model: RunInput["model"],
     ) {
-      const session = yield* Effect.promise(() => resolveSession(sdk, sessionID).catch(() => undefined))
+      const session = yield* Effect.promise(() => resolveCurrentSession(sdk, sessionID).catch(() => undefined))
       if (!session) {
         return emptySessionInfo()
       }
@@ -151,28 +117,20 @@ const layer = Layer.effect(
       return {
         first: session.first,
         history: sessionHistory(session),
-        variant: pickVariant(model, session),
+        model: session.model,
+        variant: pickVariant(model ?? session.model, session),
       }
     })
 
-    const resolveRunTuiConfig = Effect.fn("RunBoot.resolveRunTuiConfig")(function* () {
-      return runTuiConfig(yield* config())
-    })
-
-    const resolveDiffStyle = Effect.fn("RunBoot.resolveDiffStyle")(function* () {
-      return runTuiConfig(yield* config()).diff_style ?? "auto"
-    })
-
     return Service.of({
       resolveModelInfo,
       resolveSessionInfo,
-      resolveRunTuiConfig,
-      resolveDiffStyle,
     })
   }),
 )
 
-const runtime = makeRuntime(Service, layer)
+const node = makeGlobalNode({ service: Service, layer, deps: [] })
+const runtime = makeRuntime(Service, AppNodeBuilder.build(node))
 
 // Fetches available variants and context limits for every provider/model pair.
 export async function resolveModelInfo(
@@ -183,6 +141,10 @@ export async function resolveModelInfo(
   return runtime.runPromise((svc) => svc.resolveModelInfo(sdk, directory, model)).catch(() => emptyModelInfo())
 }
 
+export function resolveModelInfoStrict(sdk: RunInput["sdk"], directory: string, model: RunInput["model"]) {
+  return runtime.runPromise((svc) => svc.resolveModelInfo(sdk, directory, model))
+}
+
 // Fetches session messages to determine if this is the first turn and build prompt history.
 export async function resolveSessionInfo(
   sdk: RunInput["sdk"],
@@ -193,10 +155,12 @@ export async function resolveSessionInfo(
 }
 
 // Reads TUI config once for direct mode keymap setup and display preferences.
-export async function resolveRunTuiConfig(): Promise<RunTuiConfig> {
-  return runtime.runPromise((svc) => svc.resolveRunTuiConfig()).catch(() => defaultRunTuiConfig())
+export async function resolveRunTuiConfig(
+  config?: RunTuiConfig | Promise<RunTuiConfig>,
+): Promise<RunTuiConfig> {
+  return Promise.resolve(config).then((value) => value ?? defaultRunTuiConfig()).catch(() => defaultRunTuiConfig())
 }
 
-export async function resolveDiffStyle(): Promise<RunDiffStyle> {
-  return runtime.runPromise((svc) => svc.resolveDiffStyle()).catch(() => "auto")
+export async function resolveDiffStyle(config?: RunTuiConfig | Promise<RunTuiConfig>): Promise<RunDiffStyle> {
+  return resolveRunTuiConfig(config).then((value) => value.diff_style ?? "auto")
 }

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

@@ -12,10 +12,9 @@ import path from "path"
 import { CliRenderEvents, createCliRenderer, type CliRenderer, type ScrollbackWriter } from "@opentui/core"
 import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
 import { Global } from "@opencode-ai/core/global"
-import { openEditor } from "@opencode-ai/tui/editor"
 import { registerOpencodeKeymap } from "@opencode-ai/tui/keymap"
-import { Session as SessionApi } from "@/session/session"
-import * as Locale from "@/util/locale"
+import { isDefaultTitle } from "@opencode-ai/tui/util/session"
+import { Locale } from "@opencode-ai/tui/util/locale"
 import { resolveInteractiveStdin } from "./runtime.stdin"
 import { entrySplash, exitSplash, splashMeta } from "./splash"
 import { resolveRunTheme } from "./theme"
@@ -27,7 +26,7 @@ import type {
   RunAgent,
   RunInput,
   RunPrompt,
-  RunResource,
+  RunReference,
   RunTuiConfig,
 } from "./types"
 import { formatModelLabel } from "./variant.shared"
@@ -55,7 +54,7 @@ export type LifecycleInput = {
   directory: string
   findFiles: (query: string) => Promise<string[]>
   agents: RunAgent[]
-  resources: RunResource[]
+  references: RunReference[]
   sessionID: string
   sessionTitle?: string
   getSessionID?: () => string | undefined
@@ -64,7 +63,7 @@ export type LifecycleInput = {
   agent: string | undefined
   model: RunInput["model"]
   variant: string | undefined
-  tuiConfig: RunTuiConfig
+  tuiConfig: RunTuiConfig | Promise<RunTuiConfig>
   backgroundSubagents: boolean
   onPermissionReply: (input: PermissionReply) => void | Promise<void>
   onQuestionReply: (input: QuestionReply) => void | Promise<void>
@@ -75,6 +74,7 @@ export type LifecycleInput = {
   onInterrupt?: () => void
   onBackground?: () => void
   onSubagentSelect?: (sessionID: string | undefined) => void
+  onSubagentInterrupt?: (sessionID: string) => void
 }
 
 export type Lifecycle = {
@@ -107,7 +107,7 @@ function shutdown(renderer: CliRenderer): void {
 }
 
 function splashInfo(title: string | undefined, history: RunPrompt[]) {
-  if (title && !SessionApi.isDefaultTitle(title)) {
+  if (title && !isDefaultTitle(title)) {
     return {
       title,
       showSession: true,
@@ -123,17 +123,9 @@ function splashInfo(title: string | undefined, history: RunPrompt[]) {
 
 function footerLabels(input: Pick<RunInput, "agent" | "model" | "variant">): FooterLabels {
   const agentLabel = Locale.titlecase(input.agent ?? "build")
-
-  if (!input.model) {
-    return {
-      agentLabel,
-      modelLabel: "Model default",
-    }
-  }
-
   return {
     agentLabel,
-    modelLabel: formatModelLabel(input.model, input.variant),
+    modelLabel: input.model ? formatModelLabel(input.model, input.variant) : "",
   }
 }
 
@@ -175,6 +167,7 @@ function queueSplash(
 // the entry splash, RunFooter takes over the footer region.
 export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lifecycle> {
   const source = resolveInteractiveStdin()
+  const footerTask = import("./footer")
   let unregisterKeymap: (() => void) | undefined
 
   try {
@@ -193,10 +186,10 @@ export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lif
       consoleMode: "disabled",
       clearOnShutdown: false,
     })
-    const theme = await resolveRunTheme(renderer)
+    const [theme, tuiConfig] = await Promise.all([resolveRunTheme(renderer), input.tuiConfig])
     renderer.setBackgroundColor(theme.background)
     const keymap = createDefaultOpenTuiKeymap(renderer)
-    unregisterKeymap = registerOpencodeKeymap(keymap, renderer, input.tuiConfig)
+    unregisterKeymap = registerOpencodeKeymap(keymap, renderer, tuiConfig)
     const state: SplashState = {
       entry: false,
       exit: false,
@@ -211,7 +204,6 @@ export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lif
       model: input.model,
       variant: input.variant,
     })
-    const footerTask = import("./footer")
     const wrote = queueSplash(
       renderer,
       state,
@@ -233,7 +225,7 @@ export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lif
       directory: input.directory,
       findFiles: input.findFiles,
       agents: input.agents,
-      resources: input.resources,
+      references: input.references,
       sessionID: input.getSessionID ?? (() => input.sessionID),
       ...labels,
       model: input.model,
@@ -243,9 +235,9 @@ export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lif
       theme,
       wrote,
       keymap,
-      tuiConfig: input.tuiConfig,
+      tuiConfig,
       backgroundSubagents: input.backgroundSubagents,
-      diffStyle: input.tuiConfig.diff_style ?? "auto",
+      diffStyle: tuiConfig.diff_style ?? "auto",
       onPermissionReply: input.onPermissionReply,
       onQuestionReply: input.onQuestionReply,
       onQuestionReject: input.onQuestionReject,
@@ -259,6 +251,7 @@ export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lif
           return
         }
 
+        const { openEditor } = await import("@opencode-ai/tui/editor")
         await renderer.idle().catch(() => {})
         const ignore = () => {}
         detachSigint()
@@ -276,6 +269,7 @@ export async function createRuntimeLifecycle(input: LifecycleInput): Promise<Lif
         }
       },
       onSubagentSelect: input.onSubagentSelect,
+      onSubagentInterrupt: input.onSubagentInterrupt,
     })
 
     const sigint = () => {

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

@@ -8,8 +8,9 @@
 // and tracks per-turn wall-clock duration for the footer status line.
 //
 // Resolves when the footer closes and all in-flight work finishes.
-import * as Locale from "@/util/locale"
-import { MessageID, PartID } from "@/session/schema"
+import { ascending } from "@opencode-ai/schema/identifier"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { Locale } from "@opencode-ai/tui/util/locale"
 import { isExitCommand, isNewCommand } from "./prompt.shared"
 import type { FooterApi, FooterEvent, FooterQueuedPrompt, RunPrompt } from "./types"
 
@@ -167,7 +168,7 @@ export async function runPromptQueue(input: QueueInput): Promise<void> {
               ? prompt
               : {
                   ...prompt,
-                  messageID: prompt.messageID ?? queued?.messageID ?? MessageID.ascending(),
+                  messageID: prompt.messageID ?? queued?.messageID ?? SessionMessage.ID.create(),
                 }
           state.active = sent
 
@@ -285,8 +286,8 @@ export async function runPromptQueue(input: QueueInput): Promise<void> {
       !isNewCommand(prompt.text)
     ) {
       const queued: FooterQueuedPrompt = {
-        messageID: MessageID.ascending(),
-        partID: PartID.ascending(),
+        messageID: SessionMessage.ID.create(),
+        partID: "prt_" + ascending(),
         prompt,
       }
       state.queued = [...state.queued, queued]

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

@@ -1,7 +1,7 @@
 import fs from "fs"
 import * as tty from "node:tty"
 
-export const INTERACTIVE_INPUT_ERROR = "--mini requires a controlling terminal for input"
+export const INTERACTIVE_INPUT_ERROR = "opencode mini requires a controlling terminal for input"
 
 type InteractiveStdin = {
   stdin: NodeJS.ReadStream

packages/cli/src/mini/runtime.ts

@@ -1,10 +1,10 @@
-// Top-level orchestrator for `opencode --mini`.
+// Top-level orchestrator for `opencode mini`.
 //
 // Wires the boot sequence, lifecycle (renderer + footer), stream transport,
 // and prompt queue together into a single session loop. Two entry points:
 //
 //   runInteractiveMode     -- used when an SDK client already exists (attach mode)
-//   runInteractiveLocalMode -- used for local in-process mode (no server)
+//   runInteractiveDeferredMode -- paints before resolving its session
 //
 // Both delegate to runInteractiveRuntime, which:
 //   1. resolves TUI config, model info, and session history,
@@ -12,15 +12,22 @@
 //   3. starts the stream transport (SDK event subscription), lazily for fresh
 //      local sessions,
 //   4. runs the prompt queue until the footer closes.
-import { createOpencodeClient } from "@opencode-ai/sdk/v2"
 import { Flag } from "@opencode-ai/core/flag/flag"
-import { MessageID } from "@/session/schema"
-import { createRunDemo } from "./demo"
-import { resolveModelInfo, resolveRunTuiConfig, resolveSessionInfo } from "./runtime.boot"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { loadRunAgents, loadRunCommands, loadRunReferences, waitForDefaultModel } from "./catalog.shared"
+import { resolveModelInfo, resolveModelInfoStrict, resolveRunTuiConfig, resolveSessionInfo } from "./runtime.boot"
 import { createRuntimeLifecycle } from "./runtime.lifecycle"
 import { trace } from "./trace"
 import { cycleVariant, formatModelLabel, resolveSavedVariant, resolveVariant, saveVariant } from "./variant.shared"
-import type { LocalReplayAnchor, LocalReplayRow, RunInput, RunPrompt, RunProvider, StreamCommit } from "./types"
+import type {
+  LocalReplayAnchor,
+  LocalReplayRow,
+  RunInput,
+  RunPrompt,
+  RunProvider,
+  RunTuiConfig,
+  StreamCommit,
+} from "./types"
 
 /** @internal Exported for testing */
 export { pickVariant, resolveVariant } from "./variant.shared"
@@ -44,9 +51,7 @@ type CreateSession = (sdk: RunInput["sdk"], input: CreateSessionInput) => Promis
 type RunRuntimeInput = {
   boot: () => Promise<BootContext>
   afterPaint?: (ctx: BootContext) => Promise<void> | void
-  resolveSession?: (
-    ctx: BootContext,
-  ) => Promise<{ sessionID: string; sessionTitle?: string; agent?: string | undefined }>
+  resolveSession?: (ctx: BootContext) => Promise<ResolvedSession>
   createSession?: (ctx: BootContext, input: CreateSessionInput) => Promise<ResolvedSession>
   files: RunInput["files"]
   initialInput?: string
@@ -55,14 +60,14 @@ type RunRuntimeInput = {
   replay?: boolean
   replayLimit?: number
   demo?: RunInput["demo"]
+  tuiConfig?: RunTuiConfig | Promise<RunTuiConfig>
 }
 
-type RunLocalInput = {
+type RunDeferredInput = {
+  sdk: RunInput["sdk"]
   directory: string
-  fetch: typeof globalThis.fetch
   resolveAgent: () => Promise<string | undefined>
-  session: (sdk: RunInput["sdk"]) => Promise<{ id: string; title?: string } | undefined>
-  share: (sdk: RunInput["sdk"], sessionID: string) => Promise<void>
+  session: (sdk: RunInput["sdk"]) => Promise<{ id: string; title?: string; resume?: boolean } | undefined>
   createSession?: CreateSession
   agent: RunInput["agent"]
   model: RunInput["model"]
@@ -74,10 +79,11 @@ type RunLocalInput = {
   replay?: boolean
   replayLimit?: number
   demo?: RunInput["demo"]
+  tuiConfig?: RunTuiConfig | Promise<RunTuiConfig>
 }
 
 type StreamTransportModule = Pick<
-  Awaited<typeof import("./stream.transport")>,
+  Awaited<typeof import("./stream-v2.transport")>,
   "createSessionTransport" | "formatUnknownError"
 >
 
@@ -91,10 +97,13 @@ type StreamState = {
   handle: Awaited<ReturnType<StreamTransportModule["createSessionTransport"]>>
 }
 
+type RunDemo = ReturnType<(typeof import("./demo"))["createRunDemo"]>
+
 type ResolvedSession = {
   sessionID: string
   sessionTitle?: string
   agent?: string | undefined
+  resume?: boolean
 }
 
 function createSessionResolver(fn?: CreateSession) {
@@ -130,7 +139,7 @@ type RuntimeState = {
   sessionTitle?: string
   agent: string | undefined
   switching?: Promise<void>
-  demo?: ReturnType<typeof createRunDemo>
+  demo?: RunDemo
   selectSubagent?: (sessionID: string | undefined) => void
   session?: Promise<void>
   stream?: Promise<StreamState>
@@ -165,10 +174,8 @@ async function resolveExitTitle(
   }
 
   return ctx.sdk.session
-    .get({
-      sessionID: state.sessionID,
-    })
-    .then((x) => x.data?.title)
+    .get({ sessionID: state.sessionID })
+    .then((session) => session.title)
     .catch(() => undefined)
 }
 
@@ -181,23 +188,23 @@ async function resolveExitTitle(
 async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDeps = {}): Promise<void> {
   const start = performance.now()
   const log = trace()
-  const tuiConfigTask = resolveRunTuiConfig()
+  const tuiConfigTask = resolveRunTuiConfig(input.tuiConfig)
   const ctx = await input.boot()
-  const modelTask = resolveModelInfo(ctx.sdk, ctx.directory, ctx.model)
   const sessionTask =
     ctx.resume === true
       ? resolveSessionInfo(ctx.sdk, ctx.sessionID, ctx.model)
       : Promise.resolve({
           first: true,
           history: [],
+          model: undefined,
           variant: undefined,
         })
   const savedTask = resolveSavedVariant(ctx.model)
-  const [tuiConfig, session, savedVariant] = await Promise.all([tuiConfigTask, sessionTask, savedTask])
+  const [session, savedVariant] = await Promise.all([sessionTask, savedTask])
   const state: RuntimeState = {
     shown: !session.first,
     aborting: false,
-    model: ctx.model,
+    model: ctx.model ?? session.model,
     providers: [],
     variants: [],
     limits: {},
@@ -208,41 +215,61 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
     sessionTitle: ctx.sessionTitle,
     agent: ctx.agent,
   }
-  const ensureSession = () => {
-    if (!input.resolveSession || state.sessionID) {
-      return Promise.resolve()
+  const loadModel = async () => {
+    if (state.model) {
+      return {
+        model: state.model,
+        savedVariant,
+        boot: true,
+        info: await resolveModelInfo(ctx.sdk, ctx.directory, state.model),
+      }
     }
 
-    if (state.session) {
-      return state.session
-    }
-
-    state.session = input.resolveSession(ctx).then((next) => {
-      state.sessionID = next.sessionID
-      state.sessionTitle = next.sessionTitle ?? state.sessionTitle
-      state.agent = next.agent
+    const model = await waitForDefaultModel({
+      sdk: ctx.sdk,
+      directory: ctx.directory,
+      active: () => !footer.isClosed,
     })
-    return state.session
-  }
+    if (footer.isClosed) return
+    const [fallbackSavedVariant, info] = await Promise.all([
+      resolveSavedVariant(model),
+      resolveModelInfo(ctx.sdk, ctx.directory, model),
+    ])
+    if (!model || state.model) {
+      return {
+        model: state.model,
+        savedVariant: undefined,
+        boot: false,
+        info,
+      }
+    }
 
+    state.model = model
+    return {
+      model,
+      savedVariant: fallbackSavedVariant,
+      boot: true,
+      info,
+    }
+  }
   const shell = await (deps.createRuntimeLifecycle ?? createRuntimeLifecycle)({
     directory: ctx.directory,
     findFiles: (query) =>
-      ctx.sdk.find
-        .files({ query, directory: ctx.directory })
-        .then((x) => x.data ?? [])
+      ctx.sdk.file
+        .find({ query, type: "file", location: { directory: ctx.directory } })
+        .then((result) => result.data.map((file) => file.path))
         .catch(() => []),
     agents: [],
-    resources: [],
+    references: [],
     sessionID: state.sessionID,
     sessionTitle: state.sessionTitle,
     getSessionID: () => state.sessionID,
     first: session.first,
-    history: session.history,
+    history: state.history,
     agent: state.agent,
     model: state.model,
     variant: state.activeVariant,
-    tuiConfig,
+    tuiConfig: tuiConfigTask,
     backgroundSubagents: input.backgroundSubagents,
     onPermissionReply: async (next) => {
       if (state.demo?.permission(next)) {
@@ -250,21 +277,25 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
       }
 
       log?.write("send.permission.reply", next)
-      await ctx.sdk.permission.reply(next)
+      await ctx.sdk.permission.reply({ sessionID: state.sessionID, ...next })
     },
     onQuestionReply: async (next) => {
       if (state.demo?.questionReply(next)) {
         return
       }
 
-      await ctx.sdk.question.reply(next)
+      await ctx.sdk.question.reply({
+        sessionID: state.sessionID,
+        requestID: next.requestID,
+        answers: next.answers ?? [],
+      })
     },
     onQuestionReject: async (next) => {
       if (state.demo?.questionReject(next)) {
         return
       }
 
-      await ctx.sdk.question.reject(next)
+      await ctx.sdk.question.reject({ sessionID: state.sessionID, ...next })
     },
     onCycleVariant: () => {
       if (!state.model || state.variants.length === 0) {
@@ -339,22 +370,32 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
     },
     onInterrupt: () => {
       if (!hasSession(input, state) || state.aborting) {
-        return
+        return false
       }
 
       state.aborting = true
-      void ctx.sdk.session
-        .abort({
-          sessionID: state.sessionID,
-        })
+      void (
+        state.stream
+          ? state.stream.then((item) => item.handle.interruptActiveTurn())
+          : ctx.sdk.session.interrupt({ sessionID: state.sessionID })
+      )
         .catch(() => {})
         .finally(() => {
           state.aborting = false
         })
+      return true
     },
     onBackground: () => {
-      if (!hasSession(input, state)) return
-      void ctx.sdk.experimental.session.background({ sessionID: state.sessionID }).catch(() => {})
+      if (!hasSession(input, state)) {
+        return
+      }
+
+      log?.write("send.background", { sessionID: state.sessionID })
+      void ctx.sdk.session.background({ sessionID: state.sessionID }).catch(() => {})
+    },
+    onSubagentInterrupt: (sessionID) => {
+      log?.write("send.subagent.interrupt", { sessionID })
+      void ctx.sdk.session.interrupt({ sessionID }).catch(() => {})
     },
     onSubagentSelect: (sessionID) => {
       state.selectSubagent?.(sessionID)
@@ -364,58 +405,148 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
     },
   })
   const footer = shell.footer
+  const firstPaint = footer.idle().catch(() => {})
+  const ensureSession = () => {
+    if (!input.resolveSession || state.sessionID) {
+      return Promise.resolve()
+    }
+
+    if (state.session) {
+      return state.session
+    }
+
+    state.session = input.resolveSession(ctx).then(async (next) => {
+      state.sessionID = next.sessionID
+      state.sessionTitle = next.sessionTitle ?? state.sessionTitle
+      state.agent = next.agent
+      if (!next.resume) return
+      const resumed = await resolveSessionInfo(ctx.sdk, next.sessionID, ctx.model)
+      session.first = resumed.first
+      session.history = resumed.history
+      session.model = resumed.model
+      session.variant = resumed.variant
+      state.shown = !resumed.first
+      state.history = [...resumed.history]
+      state.model = ctx.model ?? resumed.model
+      const resumedSavedVariant = state.model ? await resolveSavedVariant(state.model) : undefined
+      state.activeVariant = resolveVariant(ctx.variant, resumed.variant, resumedSavedVariant, [])
+      session.variant = state.activeVariant
+      footer.event({ type: "history", history: resumed.history })
+      footer.event({ type: "first", first: resumed.first })
+    })
+    return state.session
+  }
+  const modelTask = firstPaint.then(async () => {
+    if (footer.isClosed) return
+    await ensureSession()
+    if (footer.isClosed) return
+    return loadModel()
+  })
   const rememberLocal = (commit: StreamCommit, after?: LocalReplayAnchor) => {
     state.localRows = [...state.localRows, { commit, after }].slice(-LOCAL_REPLAY_ROW_LIMIT)
   }
 
-  const loadCatalog = async (): Promise<void> => {
+  const applyCatalog = (catalog: {
+    agents: Awaited<ReturnType<typeof loadRunAgents>>
+    references: Awaited<ReturnType<typeof loadRunReferences>>
+    commands: Awaited<ReturnType<typeof loadRunCommands>>
+  }) => {
     if (footer.isClosed) {
       return
     }
-
-    const [agents, resources, commands] = await Promise.all([
-      ctx.sdk.app
-        .agents({ directory: ctx.directory })
-        .then((x) => x.data ?? [])
-        .catch(() => []),
-      ctx.sdk.experimental.resource
-        .list({ directory: ctx.directory })
-        .then((x) => Object.values(x.data ?? {}))
-        .catch(() => []),
-      ctx.sdk.command
-        .list({ directory: ctx.directory })
-        .then((x) => x.data ?? [])
-        .catch(() => []),
-    ])
-    if (footer.isClosed) {
-      return
-    }
-
     footer.event({
       type: "catalog",
-      agents,
-      resources,
-      commands,
+      agents: catalog.agents,
+      references: catalog.references,
+      commands: catalog.commands,
     })
   }
 
-  void footer
-    .idle()
-    .then(loadCatalog)
-    .catch(() => {})
+  const fetchCatalog = async () => {
+    const [agents, references, commands] = await Promise.all([
+      loadRunAgents(ctx.sdk, ctx.directory),
+      loadRunReferences(ctx.sdk, ctx.directory),
+      loadRunCommands(ctx.sdk, ctx.directory),
+    ])
+    return { agents, references, commands }
+  }
+
+  const loadCatalog = async () => {
+    applyCatalog(
+      await Promise.all([
+        loadRunAgents(ctx.sdk, ctx.directory).catch(() => []),
+        loadRunReferences(ctx.sdk, ctx.directory).catch(() => []),
+        loadRunCommands(ctx.sdk, ctx.directory).catch(() => []),
+      ]).then(([agents, references, commands]) => ({ agents, references, commands })),
+    )
+  }
+
+  const applyModelInfo = (
+    info: Awaited<ReturnType<typeof resolveModelInfo>>,
+    current: string | undefined,
+    boot = false,
+    saved = savedVariant,
+  ) => {
+    state.providers = info.providers
+    state.variants = variantsFor(state.providers, state.model)
+    state.limits = info.limits
+    state.activeVariant = boot
+      ? resolveVariant(ctx.variant, current, saved, state.variants)
+      : current && !state.variants.includes(current)
+        ? undefined
+        : current
+    if (footer.isClosed) return
+    footer.event({ type: "models", providers: info.providers })
+    footer.event({ type: "variants", variants: state.variants, current: state.activeVariant })
+    if (state.model)
+      footer.event({
+        type: "model",
+        model: formatModelLabel(state.model, state.activeVariant, state.providers),
+        selection: state.model,
+      })
+  }
+
+  let catalogRefresh: Promise<void> | undefined
+  let catalogRefreshQueued = false
+  const requestCatalogRefresh = () => {
+    catalogRefreshQueued = true
+    if (catalogRefresh || footer.isClosed) return
+    catalogRefresh = (async () => {
+      await Promise.all([modelTask, initialCatalog])
+      while (catalogRefreshQueued && !footer.isClosed) {
+        catalogRefreshQueued = false
+        const [catalog, info] = await Promise.allSettled([
+          fetchCatalog(),
+          resolveModelInfoStrict(ctx.sdk, ctx.directory, state.model),
+        ])
+        if (catalog.status === "fulfilled") applyCatalog(catalog.value)
+        if (info.status === "fulfilled") applyModelInfo(info.value, state.activeVariant)
+      }
+    })().finally(() => {
+      catalogRefresh = undefined
+      if (catalogRefreshQueued) requestCatalogRefresh()
+    })
+    void catalogRefresh.catch(() => {})
+  }
+
+  const initialCatalog = firstPaint.then(() => (footer.isClosed ? undefined : loadCatalog())).catch(() => {})
+  void initialCatalog
 
   if (Flag.OPENCODE_SHOW_TTFD) {
-    footer.append({
-      kind: "system",
-      text: `startup ${Math.max(0, Math.round(performance.now() - start))}ms`,
-      phase: "final",
-      source: "system",
+    void firstPaint.then(() => {
+      if (footer.isClosed) return
+      footer.append({
+        kind: "system",
+        text: `startup ${Math.max(0, Math.round(performance.now() - start))}ms`,
+        phase: "final",
+        source: "system",
+      })
     })
   }
 
-  if (input.demo) {
-    await ensureSession()
-    state.demo = createRunDemo({
+  const createDemo = async () => {
+    const { createRunDemo } = await import("./demo")
+    return createRunDemo({
       footer,
       sessionID: state.sessionID,
       thinking: input.thinking,
@@ -423,37 +554,35 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
     })
   }
 
-  if (input.afterPaint) {
-    void Promise.resolve(input.afterPaint(ctx)).catch(() => {})
+  if (input.demo) {
+    await firstPaint
+    if (!footer.isClosed) {
+      await ensureSession()
+      state.demo = await createDemo()
+    }
   }
 
-  void modelTask.then((info) => {
-    state.providers = info.providers
-    state.variants = variantsFor(state.providers, state.model)
-    state.limits = info.limits
+  if (input.afterPaint) {
+    void firstPaint.then(() => (footer.isClosed ? undefined : input.afterPaint?.(ctx))).catch(() => {})
+  }
 
-    const next = resolveVariant(ctx.variant, session.variant, savedVariant, state.variants)
-    if (next !== state.activeVariant) {
-      state.activeVariant = next
-    }
-
-    if (footer.isClosed) {
-      return
-    }
-
-    footer.event({ type: "models", providers: info.providers })
-    footer.event({ type: "variants", variants: state.variants, current: state.activeVariant })
-    if (!state.model) {
-      return
-    }
-
-    footer.event({
-      type: "model",
-      model: formatModelLabel(state.model, state.activeVariant, state.providers),
-    })
+  void modelTask.then((result) => {
+    if (!result) return
+    const current = state.model
+    const boot =
+      result.boot &&
+      !!current &&
+      current.providerID === result.model?.providerID &&
+      current.modelID === result.model.modelID
+    applyModelInfo(result.info, boot ? session.variant : state.activeVariant, boot, result.savedVariant)
   })
 
-  const streamTask = deps.streamTransport ?? import("./stream.transport")
+  let streamTask = deps.streamTransport
+  const loadStreamTransport = () => {
+    if (streamTask) return streamTask
+    streamTask = import("./stream-v2.transport")
+    return streamTask
+  }
   const ensureStream = () => {
     if (state.stream) {
       return state.stream
@@ -467,7 +596,7 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
         throw new Error("runtime closed")
       }
 
-      const mod = await streamTask
+      const mod = await loadStreamTransport()
       if (footer.isClosed) {
         throw new Error("runtime closed")
       }
@@ -483,6 +612,7 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
         providers: () => state.providers,
         footer,
         trace: log,
+        onCatalogRefresh: requestCatalogRefresh,
       })
       if (footer.isClosed) {
         await handle.close()
@@ -535,6 +665,12 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
   })
 
   const runQueue = async () => {
+    await firstPaint
+    if (footer.isClosed) return
+    await ensureSession()
+    if (footer.isClosed) return
+    await modelTask
+    if (footer.isClosed) return
     let includeFiles = true
     if (state.demo) {
       await state.demo.start()
@@ -580,14 +716,7 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
               state.history = []
               state.localRows = []
               includeFiles = true
-              state.demo = input.demo
-                ? createRunDemo({
-                    footer,
-                    sessionID: state.sessionID,
-                    thinking: input.thinking,
-                    limits: () => state.limits,
-                  })
-                : undefined
+              state.demo = input.demo ? await createDemo() : undefined
               log?.write("session.new", {
                 sessionID: state.sessionID,
               })
@@ -630,7 +759,7 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
                 text: error instanceof Error ? error.message : String(error),
                 phase: "start",
                 source: "system",
-                messageID: MessageID.ascending(),
+                messageID: SessionMessage.ID.create(),
               } as const
               rememberLocal(commit)
               footer.append(commit)
@@ -664,7 +793,9 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
               (row) => row.commit.kind !== "user" || row.commit.messageID !== prompt.messageID,
             )
           }
-          includeFiles = false
+          // Shell and skill turns never send CLI file attachments; keep them
+          // pending for the next prompt-shaped turn.
+          if (prompt.mode !== "shell" && prompt.command?.source !== "skill") includeFiles = false
         } catch (error) {
           if (signal.aborted || footer.isClosed) {
             return
@@ -690,6 +821,8 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
   try {
     const eager = eagerStream(input, ctx)
     if (eager) {
+      await firstPaint
+      if (footer.isClosed) return
       if (input.replay && state.shown) {
         // Replay commits immutable scrollback rows, so wait for provider names
         // before bootstrapping existing session history.
@@ -700,13 +833,15 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
     }
 
     if (!eager && input.resolveSession) {
-      queueMicrotask(() => {
-        if (footer.isClosed) {
-          return
-        }
+      void firstPaint
+        .then(() => {
+          if (footer.isClosed) {
+            return
+          }
 
-        void ensureStream().catch(() => {})
-      })
+          return ensureStream()
+        })
+        .catch(() => {})
     }
 
     try {
@@ -730,62 +865,62 @@ async function runInteractiveRuntime(input: RunRuntimeInput, deps: RunRuntimeDep
   }
 }
 
-// Local in-process mode. Creates an SDK client backed by a direct fetch to
-// the in-process server, so no external HTTP server is needed.
-export async function runInteractiveLocalMode(input: RunLocalInput): Promise<void> {
-  const sdk = createOpencodeClient({
-    baseUrl: "http://opencode.internal",
-    fetch: input.fetch,
-    directory: input.directory,
-  })
+// Deferred mode paints before session resolution. The caller may back the
+// generated client with a transport that is still acquiring a daemon.
+export async function runInteractiveDeferredMode(input: RunDeferredInput, deps?: RunRuntimeDeps): Promise<void> {
+  const sdk = input.sdk
   let session: Promise<ResolvedSession> | undefined
 
-  return runInteractiveRuntime({
-    files: input.files,
-    initialInput: input.initialInput,
-    thinking: input.thinking,
-    backgroundSubagents: input.backgroundSubagents,
-    replay: input.replay,
-    replayLimit: input.replayLimit,
-    demo: input.demo,
-    resolveSession: () => {
-      if (session) {
+  return runInteractiveRuntime(
+    {
+      files: input.files,
+      initialInput: input.initialInput,
+      thinking: input.thinking,
+      backgroundSubagents: input.backgroundSubagents,
+      replay: input.replay,
+      replayLimit: input.replayLimit,
+      demo: input.demo,
+      tuiConfig: input.tuiConfig,
+      resolveSession: () => {
+        if (session) {
+          return session
+        }
+
+        session = Promise.all([input.resolveAgent(), input.session(sdk)]).then(([agent, next]) => {
+          if (!next?.id) {
+            throw new Error("Session not found")
+          }
+
+          return {
+            sessionID: next.id,
+            sessionTitle: next.title,
+            agent,
+            resume: next.resume,
+          }
+        })
         return session
-      }
-
-      session = Promise.all([input.resolveAgent(), input.session(sdk)]).then(([agent, next]) => {
-        if (!next?.id) {
-          throw new Error("Session not found")
-        }
-
-        void input.share(sdk, next.id).catch(() => {})
+      },
+      createSession: createSessionResolver(input.createSession),
+      boot: async () => {
         return {
-          sessionID: next.id,
-          sessionTitle: next.title,
-          agent,
+          sdk,
+          directory: input.directory,
+          sessionID: "",
+          sessionTitle: undefined,
+          resume: false,
+          agent: input.agent,
+          model: input.model,
+          variant: input.variant,
         }
-      })
-      return session
+      },
     },
-    createSession: createSessionResolver(input.createSession),
-    boot: async () => {
-      return {
-        sdk,
-        directory: input.directory,
-        sessionID: "",
-        sessionTitle: undefined,
-        resume: false,
-        agent: input.agent,
-        model: input.model,
-        variant: input.variant,
-      }
-    },
-  })
+    deps,
+  )
 }
 
 // Attach mode. Uses the caller-provided SDK client directly.
 export async function runInteractiveMode(
-  input: RunInput & { createSession?: CreateSession },
+  input: RunInput & { createSession?: CreateSession; tuiConfig?: RunTuiConfig | Promise<RunTuiConfig> },
   deps?: RunRuntimeDeps,
 ): Promise<void> {
   return runInteractiveRuntime(
@@ -797,6 +932,7 @@ export async function runInteractiveMode(
       replay: input.replay,
       replayLimit: input.replayLimit,
       demo: input.demo,
+      tuiConfig: input.tuiConfig,
       boot: async () => ({
         sdk: input.sdk,
         directory: input.directory,

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

@@ -105,7 +105,7 @@ export class RunScrollbackStream {
   ) {
     this.diffStyle = options.diffStyle
     this.sessionID = options.sessionID
-    this.treeSitterClient = options.treeSitterClient ?? getTreeSitterClient()
+    this.treeSitterClient = options.treeSitterClient
     this.wrote = options.wrote ?? false
     this.onThemeRelease = options.onThemeRelease
   }
@@ -151,6 +151,7 @@ export class RunScrollbackStream {
       startOnNewLine: entryFlags(commit).startOnNewLine,
     })
     const style = entryLook(commit, this.theme.entry)
+    const treeSitterClient = body.type === "text" ? undefined : (this.treeSitterClient ??= getTreeSitterClient())
     const renderable =
       body.type === "text"
         ? new TextRenderable(surface.renderContext, {
@@ -170,7 +171,7 @@ export class RunScrollbackStream {
               drawUnstyledText: false,
               streaming: true,
               fg: entryColor(commit, this.theme),
-              treeSitterClient: this.treeSitterClient,
+              treeSitterClient,
             })
           : new MarkdownRenderable(surface.renderContext, {
               content: "",
@@ -180,7 +181,7 @@ export class RunScrollbackStream {
               internalBlockMode: "top-level",
               tableOptions: { widthMode: "content" },
               fg: entryColor(commit, this.theme),
-              treeSitterClient: this.treeSitterClient,
+              treeSitterClient,
             })
 
     surface.root.add(renderable)

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

@@ -338,7 +338,6 @@ export function turnSummaryWriter(input: { agent: string; model: string; duratio
     () => (
       <box width="100%" height={1}>
         <text wrapMode="none" truncate>
-          <span style={{ fg: input.theme.block.highlight }}>▣ </span>
           <span style={{ fg: input.theme.block.text }}>{input.agent}</span>
           <span style={{ fg: input.theme.block.muted }}>
             {" "}

packages/cli/src/mini/session-data.ts

@@ -5,9 +5,9 @@
 //   - FooterOutput:   status bar patches and view transitions (permission, question)
 //
 // The reducer mutates SessionData in place for performance but has no
-// external side effects -- no IO, no footer calls. The caller
-// (stream.transport.ts) feeds events in and forwards output to the footer
-// through stream.ts.
+// external side effects -- no IO, no footer calls. The demo runtime
+// (demo.ts) feeds events in and forwards output to the footer through
+// stream.ts; the current transport reuses the blocker helpers below.
 //
 // Key design decisions:
 //
@@ -24,8 +24,8 @@
 //   `data.questions`. The footer shows whichever is first. When a reply
 //   event arrives, the queue entry is removed and the footer falls back
 //   to the next pending request or to the prompt view.
-import type { Event, Part, PermissionRequest, QuestionRequest, ToolPart } from "@opencode-ai/sdk/v2"
-import * as Locale from "@/util/locale"
+import type { Event, PermissionRequest, QuestionRequest, ToolPart } from "@opencode-ai/sdk/v2"
+import { Locale } from "@opencode-ai/tui/util/locale"
 import { toolView } from "./tool"
 import type { FooterOutput, FooterPatch, FooterView, StreamCommit } from "./types"
 
@@ -62,7 +62,7 @@ type SessionCommit = StreamCommit
 // - sent:   part ID → byte offset of last flushed text (for incremental output)
 // - visible: part ID → rendered text for an active part after display transforms
 // - end:    part IDs whose time.end has arrived (part is finished)
-// - shell:  shell call ID → chosen transcript source for direct shell calls
+// - shell:  shell ID → chosen transcript source for direct shell calls
 // - echo:   message ID → bash outputs to strip from the next assistant chunk
 type ShellCall = {
   source: "shell" | "tool"
@@ -280,33 +280,6 @@ function remove(list: Array<{ id: string }>, id: string): boolean {
   return true
 }
 
-export function bootstrapSessionData(input: {
-  data: SessionData
-  messages: Array<{
-    parts: Part[]
-  }>
-  permissions: PermissionRequest[]
-  questions: QuestionRequest[]
-}) {
-  for (const message of input.messages) {
-    for (const part of message.parts) {
-      if (part.type !== "tool") {
-        continue
-      }
-
-      input.data.call.set(key(part.messageID, part.callID), part.state.input)
-    }
-  }
-
-  for (const request of input.permissions.slice().sort((a, b) => a.id.localeCompare(b.id))) {
-    upsert(input.data.permissions, enrichPermission(input.data, request))
-  }
-
-  for (const request of input.questions.slice().sort((a, b) => a.id.localeCompare(b.id))) {
-    upsert(input.data.questions, request)
-  }
-}
-
 function key(msg: string, call: string): string {
   return `${msg}:${call}`
 }
@@ -634,12 +607,12 @@ function toolCommit(
   }
 }
 
-function shellPartID(callID: string): string {
-  return `shell:${callID}`
+function shellPartID(shellID: string): string {
+  return `shell:${shellID}`
 }
 
-function claimShell(data: SessionData, callID: string, source: ShellCall["source"], command?: string): ShellCall {
-  const current = data.shell.get(callID)
+function claimShell(data: SessionData, shellID: string, source: ShellCall["source"], command?: string): ShellCall {
+  const current = data.shell.get(shellID)
   if (current) {
     if (command && !current.command) {
       current.command = command
@@ -652,7 +625,7 @@ function claimShell(data: SessionData, callID: string, source: ShellCall["source
     source,
     ...(command ? { command } : {}),
   } satisfies ShellCall
-  data.shell.set(callID, next)
+  data.shell.set(shellID, next)
   return next
 }
 
@@ -740,26 +713,6 @@ function failTool(part: ToolPart, text: string): SessionCommit {
   })
 }
 
-// Emits "interrupted" final entries for all in-flight parts. Called when a turn is aborted.
-export function flushInterrupted(data: SessionData, commits: SessionCommit[]) {
-  for (const partID of data.part.keys()) {
-    if (data.ids.has(partID)) {
-      continue
-    }
-
-    const msg = data.msg.get(partID)
-    if (msg && data.role.get(msg) === "user" && !data.includeUserText) {
-      data.ids.add(partID)
-      drop(data, partID)
-      continue
-    }
-
-    flushPart(data, commits, partID, true)
-    data.ids.add(partID)
-    drop(data, partID)
-  }
-}
-
 // The main reducer. Takes one SDK event and returns scrollback commits and
 // footer updates. Called once per event from the stream transport's watch loop.
 //
@@ -775,37 +728,37 @@ export function reduceSessionData(input: SessionDataInput): SessionDataOutput {
   const data = input.data
   const event = input.event
 
-  if (event.type === "session.next.shell.started") {
+  if (event.type === "session.shell.started") {
     if (event.properties.sessionID !== input.sessionID) {
       return out(data, commits)
     }
 
-    const shell = claimShell(data, event.properties.callID, "shell", event.properties.command)
+    const shell = claimShell(data, event.properties.shell.id, "shell", event.properties.shell.command)
     if (shell.source !== "shell") {
       return out(data, commits)
     }
 
-    const partID = shellPartID(event.properties.callID)
+    const partID = shellPartID(event.properties.shell.id)
     if (data.ids.has(partID) || data.tools.has(partID)) {
       return out(data, commits, patch({ status: "running shell" }))
     }
 
     data.tools.add(partID)
-    commits.push(startShell(event.properties.callID, shell.command ?? event.properties.command))
+    commits.push(startShell(event.properties.shell.id, shell.command ?? event.properties.shell.command))
     return out(data, commits, patch({ status: "running shell" }))
   }
 
-  if (event.type === "session.next.shell.ended") {
+  if (event.type === "session.shell.ended") {
     if (event.properties.sessionID !== input.sessionID) {
       return out(data, commits)
     }
 
-    const shell = claimShell(data, event.properties.callID, "shell")
+    const shell = claimShell(data, event.properties.shell.id, "shell")
     if (shell.source !== "shell") {
       return out(data, commits)
     }
 
-    const partID = shellPartID(event.properties.callID)
+    const partID = shellPartID(event.properties.shell.id)
     const seen = data.tools.has(partID)
     const command = shell.command ?? ""
     data.tools.delete(partID)
@@ -814,11 +767,11 @@ export function reduceSessionData(input: SessionDataInput): SessionDataOutput {
     }
 
     if (!seen && command) {
-      commits.push(startShell(event.properties.callID, command))
+      commits.push(startShell(event.properties.shell.id, command))
     }
 
     data.ids.add(partID)
-    commits.push(doneShell(event.properties.callID, command, event.properties.output))
+    commits.push(doneShell(event.properties.shell.id, command, event.properties.output.output))
     return out(data, commits)
   }
 

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

@@ -4,11 +4,12 @@
 // the prompt history ring. Also finds the most recently used variant for
 // the current model so the footer can pre-select it.
 import { promptCopy, promptSame } from "./prompt.shared"
+import type { Message, Part } from "@opencode-ai/sdk/v2"
 import type { RunInput, RunPrompt } from "./types"
 
 const LIMIT = 200
 
-export type SessionMessages = NonNullable<Awaited<ReturnType<RunInput["sdk"]["session"]["messages"]>>["data"]>
+export type SessionMessages = Array<{ info: Message; parts: Part[] }>
 
 type Turn = {
   prompt: RunPrompt
@@ -20,6 +21,8 @@ type Turn = {
 export type RunSession = {
   first: boolean
   turns: Turn[]
+  model?: NonNullable<RunInput["model"]>
+  variant?: string
 }
 
 function fileName(url: string, filename?: string) {
@@ -152,12 +155,61 @@ export function createSession(messages: SessionMessages): RunSession {
   }
 }
 
-export async function resolveSession(sdk: RunInput["sdk"], sessionID: string, limit = LIMIT): Promise<RunSession> {
-  const response = await sdk.session.messages({
-    sessionID,
-    limit,
-  })
-  return createSession(response.data ?? [])
+export async function resolveCurrentSession(
+  sdk: RunInput["sdk"],
+  sessionID: string,
+  limit = LIMIT,
+): Promise<RunSession> {
+  const [response, session] = await Promise.all([
+    sdk.message.list({ sessionID, limit, order: "desc" }),
+    sdk.session.get({ sessionID }),
+  ])
+  const messages = response.data.toReversed()
+  return {
+    first: messages.length === 0,
+    turns: messages.flatMap((message) => {
+      if (message.type !== "user") return []
+      return [
+        {
+          prompt: {
+            text: message.text,
+            parts: [
+              ...(message.files ?? []).map((file) => ({
+                type: "file" as const,
+                url: file.source.type === "uri" ? file.source.uri : `data:${file.mime};base64,${file.data}`,
+                mime: file.mime,
+                filename: file.name,
+                source: file.mention
+                  ? {
+                      type: "file" as const,
+                      path: file.name ?? (file.source.type === "uri" ? file.source.uri : "inline attachment"),
+                      text: { start: file.mention.start, end: file.mention.end, value: file.mention.text },
+                    }
+                  : undefined,
+              })),
+              ...(message.agents ?? []).map((agent) => ({
+                type: "agent" as const,
+                name: agent.name,
+                source: agent.mention
+                  ? { start: agent.mention.start, end: agent.mention.end, value: agent.mention.text }
+                  : undefined,
+              })),
+            ],
+          },
+          provider: session.model?.providerID,
+          model: session.model?.id,
+          variant: session.model?.variant,
+        },
+      ]
+    }),
+    ...(session.model && {
+      model: {
+        providerID: session.model.providerID,
+        modelID: session.model.id,
+      },
+      variant: session.model.variant,
+    }),
+  }
 }
 
 export function sessionHistory(session: RunSession, limit = LIMIT): RunPrompt[] {
@@ -183,6 +235,10 @@ export function sessionVariant(session: RunSession, model: RunInput["model"]): s
     return undefined
   }
 
+  if (session.model?.providerID === model.providerID && session.model.modelID === model.modelID) {
+    return session.variant
+  }
+
   for (let idx = session.turns.length - 1; idx >= 0; idx -= 1) {
     const turn = session.turns[idx]
     if (turn.provider !== model.providerID || turn.model !== model.modelID) {

packages/cli/src/mini/splash.ts

@@ -17,8 +17,8 @@ import {
   type ScrollbackSnapshot,
   type ScrollbackWriter,
 } from "@opentui/core"
-import * as Locale from "@/util/locale"
-import { go } from "@/cli/logo"
+import { Locale } from "@opencode-ai/tui/util/locale"
+import { go } from "@opencode-ai/tui/logo"
 import type { RunSplashTheme } from "./theme"
 
 export const SPLASH_TITLE_LIMIT = 50
@@ -234,7 +234,7 @@ function build(input: SplashWriterInput, kind: "entry" | "exit", ctx: Scrollback
       lines,
       body_left + label.length,
       top + 1,
-      `opencode --mini -s ${meta.session_id}`,
+      `opencode mini -s ${meta.session_id}`,
       right,
       undefined,
       TextAttributes.BOLD,

packages/cli/src/mini/stream-v2.subagent.ts

@@ -0,0 +1,783 @@
+// Current-native subagent (child Session) tracking for the mini transport.
+//
+// Discovers child Sessions of the active parent from four current sources:
+//   1. projected subagent tool output (`structured.sessionID`) during hydration
+//   2. the current session list filtered by `parentID` during hydration
+//   3. the process-local active-session map during hydration
+//   4. live events from unknown sessions whose `parentID` matches the parent
+//
+// Tracks one footer tab per child and a detail transcript for the selected
+// child, reduced from the same current live event stream the parent uses.
+// Detail transcripts rebuild from projected messages on discovery, selection,
+// and reconnect, then continue from live deltas using the same
+// projected-prefix dedup the parent transport uses.
+//
+// Per-child interruption uses `v2.session.interrupt(childID)`. Per-child
+// backgrounding is intentionally absent: subagent jobs block the parent
+// session, so only whole-session `v2.session.background(parentID)` exists.
+import type { EventSubscribeOutput, OpenCodeClient } from "@opencode-ai/client/promise"
+import type { SessionMessage, SessionMessageAssistantTool, ToolPart } from "@opencode-ai/sdk/v2"
+import { Locale } from "@opencode-ai/tui/util/locale"
+import type { FooterSubagentDetail, FooterSubagentState, FooterSubagentTab, StreamCommit } from "./types"
+
+const CHILD_MESSAGE_LIMIT = 80
+const CHILD_FRAME_LIMIT = 80
+const CHILD_EVENT_BUFFER_LIMIT = 64
+const FAMILY_LIST_LIMIT = 100
+const FALLBACK_LABEL = "Subagent"
+
+type V2Event = EventSubscribeOutput
+
+export function outputText(content: ReadonlyArray<{ type: string; text?: string }>) {
+  return content.flatMap((item) => (item.type === "text" && item.text ? [item.text] : [])).join("\n")
+}
+
+export function legacyTool(input: {
+  sessionID: string
+  messageID: string
+  tool: SessionMessageAssistantTool
+}): ToolPart {
+  const tool = input.tool
+  const providerCall =
+    tool.executed === undefined && tool.providerState === undefined
+      ? undefined
+      : { executed: tool.executed, state: tool.providerState }
+  const providerResult =
+    tool.executed === undefined && tool.providerResultState === undefined
+      ? undefined
+      : { executed: tool.executed, state: tool.providerResultState }
+  const base = {
+    id: `prt_${tool.id}`,
+    sessionID: input.sessionID,
+    messageID: input.messageID,
+    type: "tool" as const,
+    callID: tool.id,
+    tool: tool.name,
+  }
+  if (tool.state.status === "pending") {
+    return {
+      ...base,
+      state: { status: "pending", input: {}, raw: tool.state.input },
+    }
+  }
+  if (tool.state.status === "running") {
+    return {
+      ...base,
+      state: {
+        status: "running",
+        input: tool.state.input,
+        title: tool.name,
+        metadata: { structured: tool.state.structured, content: tool.state.content, providerCall },
+        time: { start: tool.time.ran ?? tool.time.created },
+      },
+    }
+  }
+  if (tool.state.status === "completed") {
+    return {
+      ...base,
+      state: {
+        status: "completed",
+        input: tool.state.input,
+        output: outputText(tool.state.content),
+        title: tool.name,
+        metadata: {
+          structured: tool.state.structured,
+          content: tool.state.content,
+          outputPaths: tool.state.outputPaths,
+          result: tool.state.result,
+          providerCall,
+          providerResult,
+        },
+        time: { start: tool.time.ran ?? tool.time.created, end: tool.time.completed ?? tool.time.created },
+      },
+    }
+  }
+  return {
+    ...base,
+    state: {
+      status: "error",
+      input: tool.state.input,
+      error: tool.state.error.message,
+      metadata: {
+        structured: tool.state.structured,
+        content: tool.state.content,
+        result: tool.state.result,
+        providerCall,
+        providerResult,
+      },
+      time: { start: tool.time.ran ?? tool.time.created, end: tool.time.completed ?? tool.time.created },
+    },
+  }
+}
+
+export function toolCommit(part: ToolPart, phase: "start" | "progress" | "final"): StreamCommit {
+  const status = part.state.status
+  const text =
+    status === "running"
+      ? part.tool === "task"
+        ? "running task"
+        : `running ${part.tool}`
+      : status === "completed"
+        ? part.state.output
+        : status === "error"
+          ? part.state.error
+          : ""
+  return {
+    kind: "tool",
+    source: "tool",
+    text,
+    phase,
+    messageID: part.messageID,
+    partID: part.id,
+    tool: part.tool,
+    part,
+    toolState: status === "error" ? "error" : status === "completed" ? "completed" : "running",
+    toolError: status === "error" ? part.state.error : undefined,
+  }
+}
+
+type Frame = {
+  key: string
+  commit: StreamCommit
+}
+
+type ToolTrack = {
+  name: string
+  input: Record<string, unknown>
+  started: number
+  providerState?: Record<string, unknown>
+}
+
+type ChildState = {
+  sessionID: string
+  label: string
+  description: string
+  status: FooterSubagentTab["status"]
+  background: boolean
+  title?: string
+  callIDs: Set<string>
+  lastUpdatedAt: number
+  frames: Frame[]
+  text: Map<string, string>
+  projectedText: Map<string, string>
+  reasoning: Map<string, string>
+  projectedReasoning: Map<string, string>
+  tools: Map<string, ToolTrack>
+  finishedTools: Set<string>
+  messageIDs: Set<string>
+  prompts: Map<string, string>
+  hydrated: boolean
+}
+
+export type SubagentTrackerInput = {
+  sdk: OpenCodeClient
+  sessionID: string
+  thinking: boolean
+  emit: () => void
+}
+
+export type SubagentTracker = {
+  main(event: V2Event): void
+  foreign(sessionID: string, event: V2Event): void
+  hydrate(next: { messages: SessionMessage[]; active: Record<string, unknown> }): Promise<void>
+  select(sessionID: string | undefined): void
+  snapshot(): FooterSubagentState
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) return value as Record<string, unknown>
+  return undefined
+}
+
+function text(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  const next = value.trim()
+  return next || undefined
+}
+
+function childSessionID(structured: Record<string, unknown> | undefined) {
+  const sessionID = text(structured?.sessionID)
+  if (!sessionID || !sessionID.startsWith("ses")) return undefined
+  const status = structured?.status
+  if (status !== "running" && status !== "completed") return undefined
+  return { sessionID, running: status === "running" }
+}
+
+function tab(child: ChildState): FooterSubagentTab {
+  return {
+    sessionID: child.sessionID,
+    partID: `subagent:${child.sessionID}`,
+    callID: `subagent:${child.sessionID}`,
+    label: child.label,
+    description: child.description || child.title || "",
+    status: child.status,
+    background: child.background ? true : undefined,
+    title: child.title,
+    toolCalls: child.callIDs.size > 0 ? child.callIDs.size : undefined,
+    lastUpdatedAt: child.lastUpdatedAt,
+  }
+}
+
+export function createSubagentTracker(input: SubagentTrackerInput): SubagentTracker {
+  const children = new Map<string, ChildState>()
+  // Live subagent tool calls in the parent, so tool.success structured output
+  // can be joined with the call's input metadata.
+  const pendingCalls = new Map<string, Record<string, unknown>>()
+  // Foreign sessions already resolved through session.get. Non-children stay
+  // cached so unrelated concurrent sessions are checked at most once.
+  const checked = new Set<string>()
+  // Foreign events buffered while a session.get discovery is in flight, so a
+  // fast child (including its settled event) is not lost mid-discovery.
+  const pendingEvents = new Map<string, V2Event[]>()
+  const hydrationEvents = new Map<string, V2Event[]>()
+  const hydrationOverflow = new Set<string>()
+  const hydrations = new Map<string, Promise<void>>()
+  let selected: string | undefined
+  const fragmentKey = (messageID: string, partID: string) => `${messageID}\u0000${partID}`
+
+  const ensureChild = (sessionID: string): ChildState => {
+    const existing = children.get(sessionID)
+    const child: ChildState = existing ?? {
+      sessionID,
+      label: FALLBACK_LABEL,
+      description: "",
+      status: "running",
+      background: false,
+      callIDs: new Set(),
+      lastUpdatedAt: Date.now(),
+      frames: [],
+      text: new Map(),
+      projectedText: new Map(),
+      reasoning: new Map(),
+      projectedReasoning: new Map(),
+      tools: new Map(),
+      finishedTools: new Set(),
+      messageIDs: new Set(),
+      prompts: new Map(),
+      hydrated: false,
+    }
+    if (!existing) children.set(sessionID, child)
+    // Adopting a child while its session.get discovery is still in flight:
+    // drain the buffered events now. They arrived before whatever the caller
+    // applies next, so replaying them first preserves bus order, and the
+    // resolved discovery can no longer replay stale events (e.g. step.started)
+    // after a terminal settled event was applied directly.
+    const buffered = pendingEvents.get(sessionID)
+    if (buffered) {
+      pendingEvents.delete(sessionID)
+      for (const event of buffered) reduce(child, event)
+    }
+    return child
+  }
+
+  const touch = (child: ChildState, timestamp?: number) => {
+    child.lastUpdatedAt = Math.max(child.lastUpdatedAt, timestamp ?? Date.now())
+  }
+
+  const notifyDetail = (child: ChildState) => {
+    if (child.sessionID === selected) input.emit()
+  }
+
+  const setFrame = (child: ChildState, key: string, commit: StreamCommit) => {
+    const index = child.frames.findIndex((item) => item.key === key)
+    if (index === -1) {
+      child.frames.push({ key, commit })
+      if (child.frames.length > CHILD_FRAME_LIMIT) child.frames.splice(0, child.frames.length - CHILD_FRAME_LIMIT)
+      return
+    }
+    child.frames[index] = { key, commit }
+  }
+
+  const applyMeta = (child: ChildState, meta: Record<string, unknown> | undefined) => {
+    if (!meta) return
+    const agent = text(meta.agent)
+    if (agent) child.label = Locale.titlecase(agent)
+    const description = text(meta.description)
+    if (description) child.description = description
+    if (meta.background === true) child.background = true
+  }
+
+  const userFrame = (child: ChildState, messageID: string, value: string) => {
+    if (child.messageIDs.has(messageID)) return false
+    child.messageIDs.add(messageID)
+    setFrame(child, `user:${messageID}`, {
+      kind: "user",
+      source: "system",
+      text: value,
+      phase: "start",
+      messageID,
+    })
+    return true
+  }
+
+  const childTool = (child: ChildState, item: SessionMessageAssistantTool, messageID: string) => {
+    const part = legacyTool({
+      sessionID: child.sessionID,
+      messageID,
+      tool: item,
+    })
+    if (item.state.status === "pending") return
+    child.callIDs.add(item.id)
+    if (item.state.status === "running") {
+      setFrame(child, `tool:${item.id}`, toolCommit(part, "start"))
+      return
+    }
+    child.finishedTools.add(item.id)
+    child.tools.delete(item.id)
+    setFrame(child, `tool:${item.id}`, toolCommit(part, "final"))
+  }
+
+  const rebuild = (child: ChildState, messages: SessionMessage[]) => {
+    child.frames = []
+    child.text.clear()
+    child.projectedText.clear()
+    child.reasoning.clear()
+    child.projectedReasoning.clear()
+    child.finishedTools.clear()
+    child.messageIDs.clear()
+    child.callIDs.clear()
+    for (const message of messages) {
+      if (message.type === "user") {
+        child.prompts.delete(message.id)
+        userFrame(child, message.id, message.text)
+        continue
+      }
+      if (message.type !== "assistant") continue
+      child.messageIDs.add(message.id)
+      let textOrdinal = 0
+      let reasoningOrdinal = 0
+      for (const item of message.content) {
+        if (item.type === "text") {
+          const id = `text:${textOrdinal++}`
+          const key = fragmentKey(message.id, id)
+          child.text.set(key, item.text)
+          child.projectedText.set(key, item.text)
+          setFrame(child, key, {
+            kind: "assistant",
+            source: "assistant",
+            text: item.text,
+            phase: "progress",
+            messageID: message.id,
+            partID: id,
+          })
+          continue
+        }
+        if (item.type === "reasoning") {
+          const id = `reasoning:${reasoningOrdinal++}`
+          const key = fragmentKey(message.id, id)
+          child.reasoning.set(key, item.text)
+          child.projectedReasoning.set(key, item.text)
+          if (input.thinking)
+            setFrame(child, key, {
+              kind: "reasoning",
+              source: "reasoning",
+              text: `Thinking: ${item.text}`,
+              phase: "progress",
+              messageID: message.id,
+              partID: id,
+            })
+          continue
+        }
+        childTool(child, item, message.id)
+      }
+      if (message.error) {
+        setFrame(child, `error:${message.id}`, {
+          kind: "error",
+          source: "system",
+          text: message.error.message,
+          phase: "start",
+          messageID: message.id,
+        })
+      }
+    }
+  }
+
+  const hydrateChild = (child: ChildState): Promise<void> => {
+    const existing = hydrations.get(child.sessionID)
+    if (existing) return existing
+    const pendingPrompts = new Map(child.prompts)
+    const pendingTools = new Map(child.tools)
+    let retry = false
+    const task = input.sdk.message
+      .list({ sessionID: child.sessionID, limit: CHILD_MESSAGE_LIMIT, order: "desc" })
+      .then((response) => {
+        const buffered = hydrationEvents.get(child.sessionID) ?? []
+        hydrationEvents.delete(child.sessionID)
+        if (hydrationOverflow.delete(child.sessionID)) {
+          child.hydrated = false
+          retry = true
+          notifyDetail(child)
+          return
+        }
+        for (const [id, prompt] of pendingPrompts) {
+          if (!child.prompts.has(id)) child.prompts.set(id, prompt)
+        }
+        rebuild(child, structuredClone(response.data).toReversed() as SessionMessage[])
+        for (const [id, tool] of pendingTools) {
+          if (!child.finishedTools.has(id) && !child.tools.has(id)) child.tools.set(id, tool)
+        }
+        for (const event of buffered) reduce(child, event)
+        child.hydrated = true
+        notifyDetail(child)
+      })
+      .catch(() => {
+        hydrationEvents.delete(child.sessionID)
+        hydrationOverflow.delete(child.sessionID)
+      })
+      .finally(() => {
+        hydrations.delete(child.sessionID)
+        if (retry) queueMicrotask(() => void hydrateChild(child))
+      })
+    hydrations.set(child.sessionID, task)
+    return task
+  }
+
+  const discover = (sessionID: string) => {
+    if (checked.has(sessionID) || children.has(sessionID) || sessionID === input.sessionID) return
+    checked.add(sessionID)
+    if (!pendingEvents.has(sessionID)) pendingEvents.set(sessionID, [])
+    void input.sdk.session
+      .get({ sessionID })
+      .then((session) => {
+        const buffered = pendingEvents.get(sessionID) ?? []
+        pendingEvents.delete(sessionID)
+        if (session.parentID !== input.sessionID) return
+        const child = ensureChild(sessionID)
+        if (session.agent) child.label = Locale.titlecase(session.agent)
+        child.title = session.title
+        for (const event of buffered) reduce(child, event)
+        touch(child)
+        input.emit()
+        void hydrateChild(child)
+      })
+      .catch(() => {
+        // Allow a later event to retry discovery after transient failures.
+        pendingEvents.delete(sessionID)
+        checked.delete(sessionID)
+      })
+  }
+
+  const reduce = (child: ChildState, event: V2Event) => {
+    if (event.type === "session.prompt.admitted") {
+      child.prompts.set(event.data.inputID, event.data.prompt.text)
+      return
+    }
+    if (event.type === "session.prompt.promoted") {
+      const prompt = child.prompts.get(event.data.inputID) ?? ""
+      child.prompts.delete(event.data.inputID)
+      if (userFrame(child, event.data.inputID, prompt)) {
+        touch(child, event.created)
+        notifyDetail(child)
+      }
+      return
+    }
+    if (event.type === "session.step.started") {
+      touch(child, event.created)
+      if (child.label === FALLBACK_LABEL && event.data.agent) child.label = Locale.titlecase(event.data.agent)
+      if (child.status !== "running") child.status = "running"
+      input.emit()
+      return
+    }
+    if (event.type === "session.text.started") {
+      return
+    }
+    if (event.type === "session.text.delta") {
+      const id = `text:${event.data.ordinal}`
+      const key = fragmentKey(event.data.assistantMessageID, id)
+      const projected = child.projectedText.get(key)
+      const covered = projected?.indexOf(event.data.delta) ?? -1
+      if (projected && covered >= 0) {
+        child.projectedText.set(key, projected.slice(covered + event.data.delta.length))
+        return
+      }
+      const next = (child.text.get(key) ?? "") + event.data.delta
+      child.text.set(key, next)
+      setFrame(child, key, {
+        kind: "assistant",
+        source: "assistant",
+        text: next,
+        phase: "progress",
+        messageID: event.data.assistantMessageID,
+        partID: id,
+      })
+      touch(child, event.created)
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.text.ended") {
+      const id = `text:${event.data.ordinal}`
+      const key = fragmentKey(event.data.assistantMessageID, id)
+      child.text.set(key, event.data.text)
+      child.projectedText.delete(key)
+      setFrame(child, key, {
+        kind: "assistant",
+        source: "assistant",
+        text: event.data.text,
+        phase: "progress",
+        messageID: event.data.assistantMessageID,
+        partID: id,
+      })
+      touch(child, event.created)
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.reasoning.started") {
+      return
+    }
+    if (event.type === "session.reasoning.delta") {
+      const id = `reasoning:${event.data.ordinal}`
+      const key = fragmentKey(event.data.assistantMessageID, id)
+      const projected = child.projectedReasoning.get(key)
+      const covered = projected?.indexOf(event.data.delta) ?? -1
+      if (projected && covered >= 0) {
+        child.projectedReasoning.set(key, projected.slice(covered + event.data.delta.length))
+        return
+      }
+      const next = (child.reasoning.get(key) ?? "") + event.data.delta
+      child.reasoning.set(key, next)
+      if (!input.thinking) return
+      setFrame(child, key, {
+        kind: "reasoning",
+        source: "reasoning",
+        text: `Thinking: ${next}`,
+        phase: "progress",
+        messageID: event.data.assistantMessageID,
+        partID: id,
+      })
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.reasoning.ended") {
+      const id = `reasoning:${event.data.ordinal}`
+      const key = fragmentKey(event.data.assistantMessageID, id)
+      child.reasoning.set(key, event.data.text)
+      child.projectedReasoning.delete(key)
+      if (!input.thinking) return
+      setFrame(child, key, {
+        kind: "reasoning",
+        source: "reasoning",
+        text: `Thinking: ${event.data.text}`,
+        phase: "progress",
+        messageID: event.data.assistantMessageID,
+        partID: id,
+      })
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.tool.input.started") {
+      if (child.finishedTools.has(event.data.callID)) return
+      child.tools.set(event.data.callID, { name: event.data.name, input: {}, started: event.created })
+      return
+    }
+    if (event.type === "session.tool.called") {
+      if (child.finishedTools.has(event.data.callID)) return
+      const current = child.tools.get(event.data.callID)
+      child.tools.set(event.data.callID, {
+        name: current?.name ?? "tool",
+        input: event.data.input,
+        started: current?.started ?? event.created,
+        providerState: event.data.state,
+      })
+      childTool(
+        child,
+        structuredClone({
+          type: "tool",
+          id: event.data.callID,
+          name: current?.name ?? "tool",
+          executed: event.data.executed,
+          providerState: event.data.state,
+          state: { status: "running", input: event.data.input, structured: {}, content: [] },
+          time: { created: current?.started ?? event.created, ran: event.created },
+        }) as SessionMessageAssistantTool,
+        event.data.assistantMessageID,
+      )
+      touch(child, event.created)
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.tool.success" || event.type === "session.tool.failed") {
+      if (child.finishedTools.has(event.data.callID)) return
+      const current = child.tools.get(event.data.callID)
+      const failed = event.type === "session.tool.failed"
+      childTool(
+        child,
+        structuredClone({
+          type: "tool",
+          id: event.data.callID,
+          name: current?.name ?? "tool",
+          executed: event.data.executed,
+          providerState: current?.providerState,
+          providerResultState: event.data.resultState,
+          state: failed
+            ? {
+                status: "error",
+                input: current?.input ?? {},
+                structured: {},
+                content: [],
+                error: event.data.error,
+                result: event.data.result,
+              }
+            : {
+                status: "completed",
+                input: current?.input ?? {},
+                structured: event.data.structured,
+                content: event.data.content,
+                outputPaths: event.data.outputPaths,
+                result: event.data.result,
+              },
+          time: {
+            created: current?.started ?? event.created,
+            ran: current?.started,
+            completed: event.created,
+          },
+        }) as SessionMessageAssistantTool,
+        event.data.assistantMessageID,
+      )
+      touch(child, event.created)
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.step.ended") return
+    if (event.type === "session.step.failed") {
+      setFrame(child, `error:step:${event.data.assistantMessageID}`, {
+        kind: "error",
+        source: "system",
+        text: event.data.error.message,
+        phase: "start",
+        messageID: event.data.assistantMessageID,
+      })
+      touch(child, event.created)
+      notifyDetail(child)
+      return
+    }
+    if (event.type === "session.execution.started") {
+      child.status = "running"
+      touch(child, event.created)
+      input.emit()
+      return
+    }
+    if (
+      event.type === "session.execution.succeeded" ||
+      event.type === "session.execution.failed" ||
+      event.type === "session.execution.interrupted"
+    ) {
+      child.status =
+        event.type === "session.execution.succeeded"
+          ? "completed"
+          : event.type === "session.execution.interrupted"
+            ? "cancelled"
+            : "error"
+      touch(child, event.created)
+      input.emit()
+    }
+  }
+
+  const mainTool = (item: SessionMessageAssistantTool, active?: Record<string, unknown>) => {
+    if (item.name !== "subagent" || item.state.status !== "completed") return
+    const found = childSessionID(record(item.state.structured))
+    if (!found) return
+    const child = ensureChild(found.sessionID)
+    applyMeta(child, record(item.state.input))
+    if (found.running) child.background = true
+    if (child.status === "running") {
+      const running = found.running && (!active || found.sessionID in active)
+      child.status = running ? "running" : "completed"
+    }
+    touch(child, item.time.completed ?? item.time.created)
+  }
+
+  return {
+    main(event) {
+      if (event.type === "session.tool.input.started") {
+        if (event.data.name === "subagent") pendingCalls.set(event.data.callID, {})
+        return
+      }
+      if (event.type === "session.tool.called") {
+        if (pendingCalls.has(event.data.callID)) pendingCalls.set(event.data.callID, event.data.input)
+        return
+      }
+      if (event.type === "session.tool.failed") {
+        pendingCalls.delete(event.data.callID)
+        return
+      }
+      if (event.type !== "session.tool.success") return
+      const pending = pendingCalls.get(event.data.callID)
+      pendingCalls.delete(event.data.callID)
+      const found = childSessionID(record(event.data.structured))
+      if (!found) return
+      const child = ensureChild(found.sessionID)
+      applyMeta(child, pending)
+      if (found.running) {
+        child.background = true
+        child.status = "running"
+      }
+      if (!found.running && child.status === "running") child.status = "completed"
+      touch(child, event.created)
+      input.emit()
+      if (!child.hydrated) void hydrateChild(child)
+    },
+    foreign(sessionID, event) {
+      const child = children.get(sessionID)
+      if (child) {
+        if (hydrations.has(sessionID)) {
+          const buffered = hydrationEvents.get(sessionID) ?? []
+          if (buffered.length < CHILD_EVENT_BUFFER_LIMIT) buffered.push(event)
+          else hydrationOverflow.add(sessionID)
+          hydrationEvents.set(sessionID, buffered)
+        }
+        reduce(child, event)
+        return
+      }
+      discover(sessionID)
+      const buffered = pendingEvents.get(sessionID)
+      if (buffered && buffered.length < CHILD_EVENT_BUFFER_LIMIT) buffered.push(event)
+    },
+    async hydrate(next) {
+      for (const message of next.messages) {
+        if (message.type !== "assistant") continue
+        for (const item of message.content) {
+          if (item.type === "tool") mainTool(item, next.active)
+        }
+      }
+      // Family index: adopt children directly from the current session list so
+      // historical subagents beyond the projected message window still get tabs.
+      const family = await input.sdk.session
+        .list({ parentID: input.sessionID, limit: FAMILY_LIST_LIMIT, order: "desc" })
+        .then((response) => response.data)
+        .catch(() => [])
+      for (const session of family) {
+        const child = ensureChild(session.id)
+        if (session.agent && child.label === FALLBACK_LABEL) child.label = Locale.titlecase(session.agent)
+        if (!child.title) child.title = session.title
+        touch(child, session.time.updated)
+      }
+      for (const sessionID of Object.keys(next.active)) discover(sessionID)
+      for (const child of children.values()) {
+        // Reconnect can miss a child's settled event; the active map is the
+        // authoritative live signal for still-running children.
+        if (child.status === "running" && !(child.sessionID in next.active)) child.status = "completed"
+      }
+      const current = selected ? children.get(selected) : undefined
+      if (current) await hydrateChild(current)
+      if (children.size > 0) input.emit()
+    },
+    select(sessionID) {
+      selected = sessionID
+      const child = sessionID ? children.get(sessionID) : undefined
+      if (child && !child.hydrated) void hydrateChild(child)
+      input.emit()
+    },
+    snapshot() {
+      const tabs = [...children.values()].map(tab).toSorted((a, b) => {
+        const active = Number(b.status === "running") - Number(a.status === "running")
+        if (active !== 0) return active
+        return b.lastUpdatedAt - a.lastUpdatedAt
+      })
+      const child = selected ? children.get(selected) : undefined
+      const details: Record<string, FooterSubagentDetail> = child
+        ? { [child.sessionID]: { sessionID: child.sessionID, commits: child.frames.map((item) => item.commit) } }
+        : {}
+      return { tabs, details, permissions: [], questions: [] }
+    },
+  }
+}

packages/cli/src/mini/tool.ts

@@ -16,25 +16,8 @@ import os from "os"
 import path from "path"
 import stripAnsi from "strip-ansi"
 import type { ToolPart } from "@opencode-ai/sdk/v2"
-import type * as Tool from "@/tool/tool"
-import type { ApplyPatchTool } from "@/tool/apply_patch"
-import type { ShellTool as BashTool } from "@/tool/shell"
-import type { EditTool } from "@/tool/edit"
-import type { GlobTool } from "@/tool/glob"
-import type { GrepTool } from "@/tool/grep"
-import type { InvalidTool } from "@/tool/invalid"
-import type { LspTool } from "@/tool/lsp"
-import type { PlanExitTool } from "@/tool/plan"
-import type { QuestionTool } from "@/tool/question"
-import type { ReadTool } from "@/tool/read"
-import type { SkillTool } from "@/tool/skill"
-import type { TaskTool } from "@/tool/task"
-import type { TodoWriteTool } from "@/tool/todo"
-import type { WebFetchTool } from "@/tool/webfetch"
-import { webSearchProviderLabel, type WebSearchTool } from "@/tool/websearch"
-import type { WriteTool } from "@/tool/write"
-import { LANGUAGE_EXTENSIONS } from "@/lsp/language"
-import * as Locale from "@/util/locale"
+import { LANGUAGE_EXTENSIONS } from "@opencode-ai/tui/util/filetype"
+import { Locale } from "@opencode-ai/tui/util/locale"
 import type { RunEntryBody, StreamCommit, ToolSnapshot } from "./types"
 
 export type ToolView = {
@@ -47,6 +30,46 @@ export type ToolPhase = "start" | "progress" | "final"
 
 export type ToolDict = Record<string, unknown>
 
+type PatchFile = {
+  type?: string
+  relativePath?: string
+  filePath?: string
+  movePath?: string
+  patch?: string
+  deletions?: number
+}
+
+type ToolInput = ToolDict & {
+  path?: string
+  pattern?: string
+  filePath?: string
+  filepath?: string
+  url?: string
+  query?: string
+  subagent_type?: string
+  description?: string
+  name?: string
+  operation?: string
+  line?: number
+  character?: number
+  content?: string
+  command?: string
+  workdir?: string
+  todos?: Array<{ status?: string; content?: string }>
+  questions?: Array<{ question?: string }>
+  diff?: string
+}
+
+type ToolMetadata = ToolDict & {
+  count?: number
+  matches?: number
+  diff?: string
+  provider?: unknown
+  files?: PatchFile[]
+  answers?: string[][]
+  exit?: number
+}
+
 export type ToolFrame = {
   raw: string
   name: string
@@ -73,15 +96,15 @@ export type ToolPermissionInfo = {
   file?: string
 }
 
-export type ToolProps<T = Tool.Info> = {
-  input: Partial<Tool.InferParameters<T>>
-  metadata: Partial<Tool.InferMetadata<T>>
+export type ToolProps = {
+  input: ToolInput
+  metadata: ToolMetadata
   frame: ToolFrame
 }
 
-type ToolPermissionProps<T = Tool.Info> = {
-  input: Partial<Tool.InferParameters<T>>
-  metadata: Partial<Tool.InferMetadata<T>>
+type ToolPermissionProps = {
+  input: ToolInput
+  metadata: ToolMetadata
   patterns: string[]
 }
 
@@ -91,40 +114,35 @@ type ToolPermissionCtx = {
   patterns: string[]
 }
 
-type ToolDefs = {
-  invalid: typeof InvalidTool
-  bash: typeof BashTool
-  write: typeof WriteTool
-  edit: typeof EditTool
-  apply_patch: typeof ApplyPatchTool
-  batch: Tool.Info
-  task: typeof TaskTool
-  todowrite: typeof TodoWriteTool
-  question: typeof QuestionTool
-  read: typeof ReadTool
-  glob: typeof GlobTool
-  grep: typeof GrepTool
-  list: Tool.Info
-  lsp: typeof LspTool
-  webfetch: typeof WebFetchTool
-  websearch: typeof WebSearchTool
-  skill: typeof SkillTool
-  plan_exit: typeof PlanExitTool
-}
+type ToolName =
+  | "invalid"
+  | "bash"
+  | "write"
+  | "edit"
+  | "apply_patch"
+  | "batch"
+  | "task"
+  | "todowrite"
+  | "question"
+  | "read"
+  | "glob"
+  | "grep"
+  | "list"
+  | "lsp"
+  | "webfetch"
+  | "websearch"
+  | "skill"
+  | "plan_exit"
 
-type ToolName = keyof ToolDefs
-
-type ToolRule<T = Tool.Info> = {
+type ToolRule = {
   view: ToolView
-  run: (props: ToolProps<T>) => ToolInline
-  scroll?: Partial<Record<ToolPhase, (props: ToolProps<T>) => string>>
-  permission?: (props: ToolPermissionProps<T>) => ToolPermissionInfo
-  snap?: (props: ToolProps<T>) => ToolSnapshot | undefined
+  run: (props: ToolProps) => ToolInline
+  scroll?: Partial<Record<ToolPhase, (props: ToolProps) => string>>
+  permission?: (props: ToolPermissionProps) => ToolPermissionInfo
+  snap?: (props: ToolProps) => ToolSnapshot | undefined
 }
 
-type ToolRegistry = {
-  [K in ToolName]: ToolRule<ToolDefs[K]>
-}
+type ToolRegistry = Record<ToolName, ToolRule>
 
 type AnyToolRule = ToolRule
 
@@ -136,22 +154,28 @@ function dict(v: unknown): ToolDict {
   return { ...v }
 }
 
-function props<T = Tool.Info>(frame: ToolFrame): ToolProps<T> {
+function props(frame: ToolFrame): ToolProps {
   return {
-    input: Object.assign(Object.create(null), frame.input),
-    metadata: Object.assign(Object.create(null), frame.meta),
+    input: frame.input,
+    metadata: frame.meta,
     frame,
   }
 }
 
-function permission<T = Tool.Info>(ctx: ToolPermissionCtx): ToolPermissionProps<T> {
+function permission(ctx: ToolPermissionCtx): ToolPermissionProps {
   return {
-    input: Object.assign(Object.create(null), ctx.input),
-    metadata: Object.assign(Object.create(null), ctx.meta),
+    input: ctx.input,
+    metadata: ctx.meta,
     patterns: ctx.patterns,
   }
 }
 
+function webSearchProviderLabel(provider: unknown) {
+  if (provider === "parallel") return "Parallel Web Search"
+  if (provider === "exa") return "Exa Web Search"
+  return "Web Search"
+}
+
 function text(v: unknown): string {
   return typeof v === "string" ? v : ""
 }
@@ -285,7 +309,7 @@ function count(n: number, label: string): string {
   return `${n} ${label}${n === 1 ? "" : "es"}`
 }
 
-function runGlob(p: ToolProps<typeof GlobTool>): ToolInline {
+function runGlob(p: ToolProps): ToolInline {
   const root = p.input.path ?? ""
   const title = `Glob "${p.input.pattern ?? ""}"`
   const suffix = root ? `in ${toolPath(root)}` : ""
@@ -298,7 +322,7 @@ function runGlob(p: ToolProps<typeof GlobTool>): ToolInline {
   }
 }
 
-function runGrep(p: ToolProps<typeof GrepTool>): ToolInline {
+function runGrep(p: ToolProps): ToolInline {
   const root = p.input.path ?? ""
   const title = `Grep "${p.input.pattern ?? ""}"`
   const suffix = root ? `in ${toolPath(root)}` : ""
@@ -319,7 +343,7 @@ function runList(p: ToolProps): ToolInline {
   }
 }
 
-function runRead(p: ToolProps<typeof ReadTool>): ToolInline {
+function runRead(p: ToolProps): ToolInline {
   const file = toolPath(p.input.filePath)
   const description = info(p.frame.input, ["filePath"]) || undefined
   return {
@@ -329,7 +353,7 @@ function runRead(p: ToolProps<typeof ReadTool>): ToolInline {
   }
 }
 
-function runWrite(p: ToolProps<typeof WriteTool>): ToolInline {
+function runWrite(p: ToolProps): ToolInline {
   return {
     icon: "←",
     title: `Write ${toolPath(p.input.filePath)}`,
@@ -338,7 +362,7 @@ function runWrite(p: ToolProps<typeof WriteTool>): ToolInline {
   }
 }
 
-function runWebfetch(p: ToolProps<typeof WebFetchTool>): ToolInline {
+function runWebfetch(p: ToolProps): ToolInline {
   const url = p.input.url ?? ""
   return {
     icon: "%",
@@ -346,7 +370,7 @@ function runWebfetch(p: ToolProps<typeof WebFetchTool>): ToolInline {
   }
 }
 
-function runEdit(p: ToolProps<typeof EditTool>): ToolInline {
+function runEdit(p: ToolProps): ToolInline {
   return {
     icon: "←",
     title: `Edit ${toolPath(p.input.filePath)}`,
@@ -355,7 +379,7 @@ function runEdit(p: ToolProps<typeof EditTool>): ToolInline {
   }
 }
 
-function runWebSearch(p: ToolProps<typeof WebSearchTool>): ToolInline {
+function runWebSearch(p: ToolProps): ToolInline {
   const title = webSearchProviderLabel(p.metadata.provider)
   return {
     icon: "◈",
@@ -363,7 +387,7 @@ function runWebSearch(p: ToolProps<typeof WebSearchTool>): ToolInline {
   }
 }
 
-function runTask(p: ToolProps<typeof TaskTool>): ToolInline {
+function runTask(p: ToolProps): ToolInline {
   const kind = Locale.titlecase(p.input.subagent_type || "unknown")
   const desc = p.input.description
   const icon = p.frame.status === "error" ? "✗" : p.frame.status === "running" ? "•" : "✓"
@@ -374,7 +398,7 @@ function runTask(p: ToolProps<typeof TaskTool>): ToolInline {
   }
 }
 
-function runTodo(p: ToolProps<typeof TodoWriteTool>): ToolInline {
+function runTodo(p: ToolProps): ToolInline {
   return {
     icon: "#",
     title: "Todos",
@@ -393,14 +417,14 @@ function runTodo(p: ToolProps<typeof TodoWriteTool>): ToolInline {
   }
 }
 
-function runSkill(p: ToolProps<typeof SkillTool>): ToolInline {
+function runSkill(p: ToolProps): ToolInline {
   return {
     icon: "→",
     title: `Skill "${p.input.name ?? ""}"`,
   }
 }
 
-function runPatch(p: ToolProps<typeof ApplyPatchTool>): ToolInline {
+function runPatch(p: ToolProps): ToolInline {
   const files = p.metadata.files?.length ?? 0
   if (files === 0) {
     return {
@@ -415,7 +439,7 @@ function runPatch(p: ToolProps<typeof ApplyPatchTool>): ToolInline {
   }
 }
 
-function runQuestion(p: ToolProps<typeof QuestionTool>): ToolInline {
+function runQuestion(p: ToolProps): ToolInline {
   const total = list(p.frame.input.questions).length
   return {
     icon: "→",
@@ -423,7 +447,7 @@ function runQuestion(p: ToolProps<typeof QuestionTool>): ToolInline {
   }
 }
 
-function runInvalid(p: ToolProps<typeof InvalidTool>): ToolInline {
+function runInvalid(p: ToolProps): ToolInline {
   return {
     icon: "✗",
     title: text(p.frame.state.title) || "Invalid Tool",
@@ -463,14 +487,14 @@ function lspTitle(
   return `LSP ${op} ${file}${pos}`
 }
 
-function runLsp(p: ToolProps<typeof LspTool>): ToolInline {
+function runLsp(p: ToolProps): ToolInline {
   return {
     icon: "→",
     title: text(p.frame.state.title) || lspTitle(p.input),
   }
 }
 
-function runPlanExit(p: ToolProps<typeof PlanExitTool>): ToolInline {
+function runPlanExit(p: ToolProps): ToolInline {
   return {
     icon: "→",
     title: text(p.frame.state.title) || "Switching to build agent",
@@ -479,8 +503,6 @@ function runPlanExit(p: ToolProps<typeof PlanExitTool>): ToolInline {
   }
 }
 
-type PatchFile = Tool.InferMetadata<typeof ApplyPatchTool>["files"][number]
-
 function patchTitle(file: PatchFile): string {
   const rel = file.relativePath
   const from = file.filePath
@@ -497,7 +519,7 @@ function patchTitle(file: PatchFile): string {
   return `# Patched ${rel || toolPath(from)}`
 }
 
-function snapWrite(p: ToolProps<typeof WriteTool>): ToolSnapshot | undefined {
+function snapWrite(p: ToolProps): ToolSnapshot | undefined {
   const file = p.input.filePath || ""
   const content = p.input.content || ""
   if (!file && !content) {
@@ -512,7 +534,7 @@ function snapWrite(p: ToolProps<typeof WriteTool>): ToolSnapshot | undefined {
   }
 }
 
-function snapEdit(p: ToolProps<typeof EditTool>): ToolSnapshot | undefined {
+function snapEdit(p: ToolProps): ToolSnapshot | undefined {
   const file = p.input.filePath || ""
   const diff = p.metadata.diff || ""
   if (!file || !diff.trim()) {
@@ -531,7 +553,7 @@ function snapEdit(p: ToolProps<typeof EditTool>): ToolSnapshot | undefined {
   }
 }
 
-function snapPatch(p: ToolProps<typeof ApplyPatchTool>): ToolSnapshot | undefined {
+function snapPatch(p: ToolProps): ToolSnapshot | undefined {
   const files = list<PatchFile>(p.frame.meta.files)
   if (files.length === 0) {
     return undefined
@@ -568,7 +590,7 @@ function snapPatch(p: ToolProps<typeof ApplyPatchTool>): ToolSnapshot | undefine
   }
 }
 
-function snapTask(p: ToolProps<typeof TaskTool>): ToolSnapshot {
+function snapTask(p: ToolProps): ToolSnapshot {
   const kind = Locale.titlecase(p.input.subagent_type || "general")
   const desc = p.input.description
   const title = text(p.frame.state.title)
@@ -582,7 +604,7 @@ function snapTask(p: ToolProps<typeof TaskTool>): ToolSnapshot {
   }
 }
 
-function snapTodo(p: ToolProps<typeof TodoWriteTool>): ToolSnapshot {
+function snapTodo(p: ToolProps): ToolSnapshot {
   const items = list<{ status?: string; content?: string }>(p.frame.input.todos).flatMap((item) => {
     const content = typeof item?.content === "string" ? item.content : ""
     if (!content) {
@@ -604,7 +626,7 @@ function snapTodo(p: ToolProps<typeof TodoWriteTool>): ToolSnapshot {
   }
 }
 
-function snapQuestion(p: ToolProps<typeof QuestionTool>): ToolSnapshot {
+function snapQuestion(p: ToolProps): ToolSnapshot {
   const answers = list<unknown[]>(p.frame.meta.answers)
   const items = list<{ question?: string }>(p.frame.input.questions).map((item, i) => {
     const answer = list<string>(answers[i]).filter((entry) => typeof entry === "string")
@@ -621,7 +643,7 @@ function snapQuestion(p: ToolProps<typeof QuestionTool>): ToolSnapshot {
   }
 }
 
-function scrollBashStart(p: ToolProps<typeof BashTool>): string {
+function scrollBashStart(p: ToolProps): string {
   const cmd = p.input.command ?? ""
   const wd = p.input.workdir ?? ""
   const formatted = wd && wd !== "." ? toolPath(wd) : ""
@@ -637,7 +659,7 @@ function scrollBashStart(p: ToolProps<typeof BashTool>): string {
   return `# Running in ${dir}\n$ ${cmd}`
 }
 
-function scrollBashProgress(p: ToolProps<typeof BashTool>): string {
+function scrollBashProgress(p: ToolProps): string {
   const out = stripAnsi(p.frame.raw)
   const cmd = (p.input.command ?? "").trim()
   const fmt = (text: string) => {
@@ -670,7 +692,11 @@ function scrollBashProgress(p: ToolProps<typeof BashTool>): string {
   return fmt(out)
 }
 
-function scrollBashFinal(p: ToolProps<typeof BashTool>): string {
+function scrollBashFinal(p: ToolProps): string {
+  if (p.frame.status === "error") {
+    return fail(p.frame)
+  }
+
   const code = p.metadata.exit ?? num(p.frame.meta.exitCode) ?? num(p.frame.meta.exit_code)
   const time = span(p.frame.state)
   if (code === undefined) {
@@ -684,22 +710,22 @@ function scrollBashFinal(p: ToolProps<typeof BashTool>): string {
   return `bash completed (exit ${code})${time ? ` · ${time}` : ""}`
 }
 
-function scrollReadStart(p: ToolProps<typeof ReadTool>): string {
+function scrollReadStart(p: ToolProps): string {
   const file = toolPath(p.input.filePath)
   const extra = info(p.frame.input, ["filePath"])
   const tail = extra ? ` ${extra}` : ""
   return `→ Read ${file}${tail}`.trim()
 }
 
-function scrollWriteStart(_: ToolProps<typeof WriteTool>): string {
+function scrollWriteStart(_: ToolProps): string {
   return ""
 }
 
-function scrollEditStart(_: ToolProps<typeof EditTool>): string {
+function scrollEditStart(_: ToolProps): string {
   return ""
 }
 
-function scrollPatchStart(_: ToolProps<typeof ApplyPatchTool>): string {
+function scrollPatchStart(_: ToolProps): string {
   return ""
 }
 
@@ -723,7 +749,7 @@ function patchLine(file: PatchFile): string {
   return `~ Patched ${rel || toolPath(from)}`
 }
 
-function scrollPatchFinal(p: ToolProps<typeof ApplyPatchTool>): string {
+function scrollPatchFinal(p: ToolProps): string {
   if (p.frame.status === "error") {
     return fail(p.frame)
   }
@@ -752,7 +778,7 @@ function scrollPatchFinal(p: ToolProps<typeof ApplyPatchTool>): string {
   return patchLine(files[0]!)
 }
 
-function scrollTaskStart(_: ToolProps<typeof TaskTool>): string {
+function scrollTaskStart(_: ToolProps): string {
   return ""
 }
 
@@ -774,7 +800,7 @@ function taskResult(output: string): string | undefined {
   return next || undefined
 }
 
-function scrollTaskFinal(p: ToolProps<typeof TaskTool>): string {
+function scrollTaskFinal(p: ToolProps): string {
   if (p.frame.status === "error") {
     return fail(p.frame)
   }
@@ -788,11 +814,11 @@ function scrollTaskFinal(p: ToolProps<typeof TaskTool>): string {
   return `# ${kind} Task\n${row}`
 }
 
-function scrollTodoStart(_: ToolProps<typeof TodoWriteTool>): string {
+function scrollTodoStart(_: ToolProps): string {
   return ""
 }
 
-function scrollTodoFinal(p: ToolProps<typeof TodoWriteTool>): string {
+function scrollTodoFinal(p: ToolProps): string {
   const items = list<{ status?: string }>(p.input.todos)
   const time = span(p.frame.state)
   if (items.length === 0) {
@@ -824,11 +850,11 @@ function scrollTodoFinal(p: ToolProps<typeof TodoWriteTool>): string {
   return tail.join(" · ")
 }
 
-function scrollQuestionStart(_: ToolProps<typeof QuestionTool>): string {
+function scrollQuestionStart(_: ToolProps): string {
   return ""
 }
 
-function scrollQuestionFinal(p: ToolProps<typeof QuestionTool>): string {
+function scrollQuestionFinal(p: ToolProps): string {
   const q = p.input.questions ?? []
   const a = p.metadata.answers ?? []
   const time = span(p.frame.state)
@@ -855,15 +881,15 @@ function scrollQuestionFinal(p: ToolProps<typeof QuestionTool>): string {
   return rows.join("\n")
 }
 
-function scrollLspStart(p: ToolProps<typeof LspTool>): string {
+function scrollLspStart(p: ToolProps): string {
   return `→ ${lspTitle(p.input)}`
 }
 
-function scrollSkillStart(p: ToolProps<typeof SkillTool>): string {
+function scrollSkillStart(p: ToolProps): string {
   return `→ Skill "${p.input.name ?? ""}"`
 }
 
-function scrollGlobStart(p: ToolProps<typeof GlobTool>): string {
+function scrollGlobStart(p: ToolProps): string {
   const pattern = p.input.pattern ?? ""
   const head = pattern ? `✱ Glob "${pattern}"` : "✱ Glob"
   const dir = p.input.path ?? ""
@@ -874,11 +900,11 @@ function scrollGlobStart(p: ToolProps<typeof GlobTool>): string {
   return `${head} in ${toolPath(dir)}`
 }
 
-function scrollGlobFinal(p: ToolProps<typeof GlobTool>): string {
+function scrollGlobFinal(p: ToolProps): string {
   return toolError(p.frame) || fail(p.frame)
 }
 
-function scrollGrepStart(p: ToolProps<typeof GrepTool>): string {
+function scrollGrepStart(p: ToolProps): string {
   const pattern = p.input.pattern ?? ""
   const head = pattern ? `✱ Grep "${pattern}"` : "✱ Grep"
   const dir = p.input.path ?? ""
@@ -898,7 +924,7 @@ function scrollListStart(p: ToolProps): string {
   return `→ List ${toolPath(dir)}`
 }
 
-function scrollWebfetchStart(p: ToolProps<typeof WebFetchTool>): string {
+function scrollWebfetchStart(p: ToolProps): string {
   const url = p.input.url ?? ""
   if (!url) {
     return "% WebFetch"
@@ -907,7 +933,7 @@ function scrollWebfetchStart(p: ToolProps<typeof WebFetchTool>): string {
   return `% WebFetch ${url}`
 }
 
-function scrollWebSearchStart(p: ToolProps<typeof WebSearchTool>): string {
+function scrollWebSearchStart(p: ToolProps): string {
   const title = webSearchProviderLabel(p.metadata.provider)
   const query = p.input.query ?? ""
   if (!query) {
@@ -917,7 +943,7 @@ function scrollWebSearchStart(p: ToolProps<typeof WebSearchTool>): string {
   return `◈ ${title} "${query}"`
 }
 
-function permEdit(p: ToolPermissionProps<typeof EditTool>): ToolPermissionInfo {
+function permEdit(p: ToolPermissionProps): ToolPermissionInfo {
   const input = p.input as { filePath?: string; filepath?: string; diff?: string }
   const file = input.filePath || input.filepath || p.patterns[0] || ""
   return {
@@ -929,7 +955,7 @@ function permEdit(p: ToolPermissionProps<typeof EditTool>): ToolPermissionInfo {
   }
 }
 
-function permRead(p: ToolPermissionProps<typeof ReadTool>): ToolPermissionInfo {
+function permRead(p: ToolPermissionProps): ToolPermissionInfo {
   const file = p.input.filePath || p.patterns[0] || ""
   return {
     icon: "→",
@@ -938,7 +964,7 @@ function permRead(p: ToolPermissionProps<typeof ReadTool>): ToolPermissionInfo {
   }
 }
 
-function permGlob(p: ToolPermissionProps<typeof GlobTool>): ToolPermissionInfo {
+function permGlob(p: ToolPermissionProps): ToolPermissionInfo {
   const pattern = p.input.pattern || p.patterns[0] || ""
   return {
     icon: "✱",
@@ -947,7 +973,7 @@ function permGlob(p: ToolPermissionProps<typeof GlobTool>): ToolPermissionInfo {
   }
 }
 
-function permGrep(p: ToolPermissionProps<typeof GrepTool>): ToolPermissionInfo {
+function permGrep(p: ToolPermissionProps): ToolPermissionInfo {
   const pattern = p.input.pattern || p.patterns[0] || ""
   return {
     icon: "✱",
@@ -965,7 +991,7 @@ function permList(p: ToolPermissionProps): ToolPermissionInfo {
   }
 }
 
-function permBash(p: ToolPermissionProps<typeof BashTool>): ToolPermissionInfo {
+function permBash(p: ToolPermissionProps): ToolPermissionInfo {
   const cmd = p.input.command || ""
   return {
     icon: "#",
@@ -974,7 +1000,7 @@ function permBash(p: ToolPermissionProps<typeof BashTool>): ToolPermissionInfo {
   }
 }
 
-function permTask(p: ToolPermissionProps<typeof TaskTool>): ToolPermissionInfo {
+function permTask(p: ToolPermissionProps): ToolPermissionInfo {
   const type = p.input.subagent_type || "general"
   const desc = p.input.description
   return {
@@ -984,7 +1010,7 @@ function permTask(p: ToolPermissionProps<typeof TaskTool>): ToolPermissionInfo {
   }
 }
 
-function permWebfetch(p: ToolPermissionProps<typeof WebFetchTool>): ToolPermissionInfo {
+function permWebfetch(p: ToolPermissionProps): ToolPermissionInfo {
   const url = p.input.url || ""
   return {
     icon: "%",
@@ -993,7 +1019,7 @@ function permWebfetch(p: ToolPermissionProps<typeof WebFetchTool>): ToolPermissi
   }
 }
 
-function permWebSearch(p: ToolPermissionProps<typeof WebSearchTool>): ToolPermissionInfo {
+function permWebSearch(p: ToolPermissionProps): ToolPermissionInfo {
   const query = p.input.query || ""
   const title = webSearchProviderLabel(p.metadata.provider)
   return {
@@ -1003,7 +1029,7 @@ function permWebSearch(p: ToolPermissionProps<typeof WebSearchTool>): ToolPermis
   }
 }
 
-function permLsp(p: ToolPermissionProps<typeof LspTool>): ToolPermissionInfo {
+function permLsp(p: ToolPermissionProps): ToolPermissionInfo {
   const file = p.input.filePath || ""
   const line = typeof p.input.line === "number" ? p.input.line : undefined
   const char = typeof p.input.character === "number" ? p.input.character : undefined
@@ -1269,7 +1295,7 @@ export function toolFrame(commit: StreamCommit, raw: string): ToolFrame {
   }
 }
 
-function runBash(p: ToolProps<typeof BashTool>): ToolInline {
+function runBash(p: ToolProps): ToolInline {
   return {
     icon: "$",
     title: p.input.command || "",
@@ -1427,6 +1453,11 @@ export function toolEntryBody(commit: StreamCommit, raw: string): RunEntryBody |
       return textBody(shellOutput(commit.shell.command, raw) ?? "")
     }
 
+    if (commit.toolState === "error") {
+      const ctx = toolFrame(commit, raw)
+      return textBody(toolScroll("final", ctx))
+    }
+
     return undefined
   }
 

packages/cli/src/mini/turn-summary.ts

@@ -0,0 +1,21 @@
+import type { StreamCommit } from "./types"
+
+export function turnSummaryCommit(input: {
+  agent: string
+  model: string
+  duration: string
+  messageID?: string
+}): StreamCommit {
+  return {
+    kind: "system",
+    text: `${input.agent} · ${input.model} · ${input.duration}`,
+    phase: "final",
+    source: "system",
+    summary: {
+      agent: input.agent,
+      model: input.model,
+      duration: input.duration,
+    },
+    messageID: input.messageID,
+  }
+}

packages/cli/src/mini/types.ts

@@ -1,4 +1,4 @@
-// Shared type vocabulary for the direct interactive mode (`opencode --mini`).
+// Shared type vocabulary for the direct interactive mode (`opencode mini`).
 //
 // Direct mode uses a split-footer terminal layout: immutable scrollback for the
 // session transcript, and a mutable footer for prompt input, status, and
@@ -11,7 +11,8 @@
 //     → stream.ts bridges to footer API
 //       → footer.ts queues commits and patches the footer view
 //         → OpenTUI split-footer renderer writes to terminal
-import type { OpencodeClient, PermissionRequest, QuestionRequest, ToolPart } from "@opencode-ai/sdk/v2"
+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"
 
 export type RunFilePart = {
@@ -21,14 +22,75 @@ export type RunFilePart = {
   mime: string
 }
 
-type PromptModel = Parameters<OpencodeClient["session"]["prompt"]>[0]["model"]
-type PromptInput = Parameters<OpencodeClient["session"]["prompt"]>[0]
+type PromptModel = { providerID: string; modelID: string }
 
-export type RunPromptPart = NonNullable<PromptInput["parts"]>[number]
+export type RunPromptPart =
+  | {
+      type: "file"
+      url: string
+      filename?: string
+      mime?: string
+      source?: FilePart["source"]
+    }
+  | { type: "agent"; name: string; source?: { start: number; end: number; value: string } }
 
-export type RunCommand = NonNullable<Awaited<ReturnType<OpencodeClient["command"]["list"]>>["data"]>[number]
+export type RunCommand = {
+  name: string
+  description?: string
+  source?: string
+  template?: string
+  hints?: unknown[]
+  agent?: string
+  model?: {
+    [key: string]: unknown
+  }
+  subtask?: boolean
+}
 
-export type RunProvider = NonNullable<Awaited<ReturnType<OpencodeClient["provider"]["list"]>>["data"]>["all"][number]
+export type RunProviderModel = {
+  id: string
+  providerID: string
+  api?: {
+    [key: string]: unknown
+  }
+  name?: string
+  capabilities?: {
+    [key: string]: unknown
+  }
+  cost?: {
+    input: number
+    output?: number
+    cache?: {
+      read: number
+      write: number
+    }
+  }
+  limit?: {
+    context: number
+    input?: number
+    output?: number
+  }
+  status?: string
+  options?: {
+    [key: string]: unknown
+  }
+  headers?: {
+    [key: string]: string
+  }
+  release_date?: string
+  variants?: Record<string, unknown>
+}
+
+export type RunProvider = {
+  id: string
+  name: string
+  source?: string
+  env?: string[]
+  options?: {
+    [key: string]: unknown
+  }
+  models: Record<string, RunProviderModel>
+}
 
 export type RunPrompt = {
   messageID?: string
@@ -39,6 +101,8 @@ export type RunPrompt = {
   command?: {
     name: string
     arguments: string
+    // Catalog source of the matched slash entry ("skill" routes to session.skill).
+    source?: string
   }
 }
 
@@ -48,14 +112,17 @@ export type FooterQueuedPrompt = {
   prompt: RunPrompt
 }
 
-export type RunAgent = NonNullable<Awaited<ReturnType<OpencodeClient["app"]["agents"]>>["data"]>[number]
+export type RunAgent = {
+  name: string
+  description?: string
+  mode: "subagent" | "primary" | "all"
+  hidden: boolean
+}
 
-type RunResourceMap = NonNullable<Awaited<ReturnType<OpencodeClient["experimental"]["resource"]["list"]>>["data"]>
-
-export type RunResource = RunResourceMap[string]
+export type RunReference = ReferenceListOutput["data"][number]
 
 export type RunInput = {
-  sdk: OpencodeClient
+  sdk: OpenCodeClient
   directory: string
   sessionID: string
   sessionTitle?: string
@@ -221,10 +288,14 @@ export type FooterOutput = {
 // transport both emit these to update footer state without reaching into
 // internal signals directly.
 export type FooterEvent =
+  | {
+      type: "history"
+      history: RunPrompt[]
+    }
   | {
       type: "catalog"
       agents: RunAgent[]
-      resources: RunResource[]
+      references: RunReference[]
       commands?: RunCommand[]
     }
   | {
@@ -251,6 +322,7 @@ export type FooterEvent =
   | {
       type: "model"
       model: string
+      selection: NonNullable<RunInput["model"]>
     }
   | {
       type: "turn.send"
@@ -280,11 +352,14 @@ export type FooterEvent =
       state: FooterSubagentState
     }
 
-export type PermissionReply = Parameters<OpencodeClient["permission"]["reply"]>[0]
+export type PermissionReply = Omit<Parameters<OpenCodeClient["permission"]["reply"]>[0], "sessionID">
 
-export type QuestionReply = Parameters<OpencodeClient["question"]["reply"]>[0]
+export type QuestionReply = {
+  requestID: string
+  answers: string[][]
+}
 
-export type QuestionReject = Parameters<OpencodeClient["question"]["reject"]>[0]
+export type QuestionReject = Omit<Parameters<OpenCodeClient["question"]["reject"]>[0], "sessionID">
 
 export type RunTuiConfig = Pick<TuiConfig.Resolved, "keybinds" | "leader_timeout" | "diff_style">
 

packages/cli/src/mini/ui.ts

@@ -0,0 +1,27 @@
+import { EOL } from "node:os"
+
+export const Style = {
+  TEXT_DIM: "\x1b[90m",
+  TEXT_NORMAL: "\x1b[0m",
+  TEXT_WARNING_BOLD: "\x1b[93m\x1b[1m",
+  TEXT_DANGER_BOLD: "\x1b[91m\x1b[1m",
+}
+
+export function println(...message: string[]) {
+  process.stderr.write(message.join(" ") + EOL)
+}
+
+let blank = false
+
+export function empty() {
+  if (blank) return
+  println(Style.TEXT_NORMAL)
+  blank = true
+}
+
+export function error(message: string) {
+  if (message.startsWith("Error: ")) message = message.slice("Error: ".length)
+  println(Style.TEXT_DANGER_BOLD + "Error: " + Style.TEXT_NORMAL + message)
+}
+
+export * as UI from "./ui"

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

@@ -10,9 +10,10 @@ import path from "path"
 import { FSUtil } from "@opencode-ai/core/fs-util"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { Context, Effect, Layer } from "effect"
-import { makeRuntime } from "@/effect/run-service"
+import { LayerNode } from "@opencode-ai/core/effect/layer-node"
+import { makeGlobalNode } from "@opencode-ai/core/effect/app-node"
+import { makeRuntime } from "@opencode-ai/core/effect/runtime"
 import { Global } from "@opencode-ai/core/global"
-import { isRecord } from "@/util/record"
 import { createSession, sessionVariant, type RunSession, type SessionMessages } from "./session.shared"
 import type { RunInput, RunProvider } from "./types"
 
@@ -30,6 +31,10 @@ type VariantRuntime = {
   saveVariant(model: RunInput["model"], variant: string | undefined): Promise<void>
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+}
+
 class Service extends Context.Service<Service, VariantService>()("@opencode/RunVariant") {}
 
 function modelKey(provider: string, model: string): string {
@@ -136,69 +141,69 @@ function state(value: unknown): ModelState {
   }
 }
 
-function createLayer(fs = AppNodeBuilder.build(FSUtil.node)) {
-  return Layer.fresh(
-    Layer.effect(
-      Service,
-      Effect.gen(function* () {
-        const file = yield* FSUtil.Service
+const layer = Layer.fresh(
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const file = yield* FSUtil.Service
 
-        const read = Effect.fn("RunVariant.read")(function* () {
-          return yield* file.readJson(MODEL_FILE).pipe(
-            Effect.map(state),
-            Effect.catchCause(() => Effect.succeed(state(undefined))),
-          )
-        })
+      const read = Effect.fn("RunVariant.read")(function* () {
+        return yield* file.readJson(MODEL_FILE).pipe(
+          Effect.map(state),
+          Effect.catchCause(() => Effect.succeed(state(undefined))),
+        )
+      })
 
-        const resolveSavedVariant = Effect.fn("RunVariant.resolveSavedVariant")(function* (model: RunInput["model"]) {
-          if (!model) {
-            return undefined
-          }
+      const resolveSavedVariant = Effect.fn("RunVariant.resolveSavedVariant")(function* (model: RunInput["model"]) {
+        if (!model) {
+          return undefined
+        }
 
-          return (yield* read()).variant?.[variantKey(model)]
-        })
+        return (yield* read()).variant?.[variantKey(model)]
+      })
 
-        const saveVariant = Effect.fn("RunVariant.saveVariant")(function* (
-          model: RunInput["model"],
-          variant: string | undefined,
-        ) {
-          if (!model) {
-            return
-          }
+      const saveVariant = Effect.fn("RunVariant.saveVariant")(function* (
+        model: RunInput["model"],
+        variant: string | undefined,
+      ) {
+        if (!model) {
+          return
+        }
 
-          const current = yield* read()
-          const next = {
-            ...current.variant,
-          }
-          const key = variantKey(model)
-          if (variant) {
-            next[key] = variant
-          }
+        const current = yield* read()
+        const next = {
+          ...current.variant,
+        }
+        const key = variantKey(model)
+        if (variant) {
+          next[key] = variant
+        }
 
-          if (!variant) {
-            delete next[key]
-          }
+        if (!variant) {
+          delete next[key]
+        }
 
-          yield* file
-            .writeJson(MODEL_FILE, {
-              ...current,
-              variant: next,
-            })
-            .pipe(Effect.orElseSucceed(() => undefined))
-        })
+        yield* file
+          .writeJson(MODEL_FILE, {
+            ...current,
+            variant: next,
+          })
+          .pipe(Effect.orElseSucceed(() => undefined))
+      })
 
-        return Service.of({
-          resolveSavedVariant,
-          saveVariant,
-        })
-      }),
-    ).pipe(Layer.provide(fs)),
-  )
-}
+      return Service.of({
+        resolveSavedVariant,
+        saveVariant,
+      })
+    }),
+  ),
+)
+
+const node = makeGlobalNode({ service: Service, layer, deps: [FSUtil.node] })
 
 /** @internal Exported for testing. */
-export function createVariantRuntime(fs = AppNodeBuilder.build(FSUtil.node)): VariantRuntime {
-  const runtime = makeRuntime(Service, createLayer(fs))
+export function createVariantRuntime(replacements?: readonly LayerNode.Replacement[]): VariantRuntime {
+  const runtime = makeRuntime(Service, AppNodeBuilder.build(node, replacements))
   return {
     resolveSavedVariant: (model) => runtime.runPromise((svc) => svc.resolveSavedVariant(model)).catch(() => undefined),
     saveVariant: (model, variant) => runtime.runPromise((svc) => svc.saveVariant(model, variant)).catch(() => {}),

packages/cli/src/server-process.ts

@@ -0,0 +1,136 @@
+export * as ServerProcess from "./server-process"
+
+import { NodeServices } from "@effect/platform-node"
+import { Service } from "@opencode-ai/client/effect"
+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 { InstallationVersion } from "@opencode-ai/core/installation/version"
+import { AppProcess } from "@opencode-ai/core/process"
+import { Flock } from "@opencode-ai/core/util/flock"
+import { start } from "@opencode-ai/server/process"
+import { randomBytes, randomUUID } from "node:crypto"
+import path from "node:path"
+import { Effect, FileSystem, Logger, Option, Redacted, Schedule, Schema } from "effect"
+import { HttpServer } from "effect/unstable/http"
+import { CodeModeHost } from "./code-mode"
+import { Env } from "./env"
+import { ServiceConfig } from "./services/service-config"
+import { Updater } from "./services/updater"
+
+export type Mode = "default" | "service" | "stdio"
+
+export type Options = {
+  readonly mode: Mode
+  readonly hostname?: string
+  readonly port?: number
+}
+
+export const run = Effect.fn("cli.server-process.run")((options: Options) =>
+  processEffect(options).pipe(
+    Effect.provide(Updater.layer),
+    Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node]))),
+    Effect.provide(NodeServices.layer),
+  ),
+)
+
+const processEffect = Effect.fnUntraced(function* (options: Options) {
+  if (options.mode === "service") yield* Effect.sync(() => process.chdir(Global.Path.home))
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      if (options.mode === "service") {
+        const service = yield* ServiceConfig.options()
+        yield* Flock.effect(path.basename(service.file, ".json") + "-process", {
+          dir: path.dirname(service.file),
+          staleMs: 3_000,
+          timeoutMs: 15_000,
+        })
+      }
+      const environmentPassword = yield* Env.password
+      // Keep the lease credential out of the environment inherited by tools.
+      if (options.mode === "stdio") {
+        delete process.env.OPENCODE_PASSWORD
+        delete process.env.OPENCODE_SERVER_PASSWORD
+      }
+      const config = options.mode === "service" ? yield* ServiceConfig.read() : {}
+      const password =
+        options.mode === "service"
+          ? yield* ServiceConfig.password()
+          : environmentPassword
+            ? Redacted.value(environmentPassword)
+            : randomBytes(32).toString("base64url")
+      if (!password) return yield* Effect.fail(new Error("Missing server password"))
+      const address = yield* start({
+        hostname: options.hostname ?? config.hostname ?? "127.0.0.1",
+        port: Option.fromNullishOr(options.port ?? config.port),
+        password,
+        replacements: (server) => CodeModeHost.replacements(server, password),
+      }).pipe(Effect.provide(Logger.layer([], { mergeWithExisting: false })))
+      if (options.mode === "service") yield* register(address, password)
+      const url = HttpServer.formatAddress(address)
+      console.log(options.mode === "stdio" ? JSON.stringify({ url }) : `server listening on ${url}`)
+      if (options.mode === "default" && !environmentPassword) console.log(`server password ${password}`)
+      const updater = yield* Updater.Service
+      yield* updater.check().pipe(Effect.schedule(Schedule.spaced("10 minutes")), Effect.forkScoped)
+      return yield* options.mode === "stdio" ? waitForStdinClose() : Effect.never
+    }).pipe(Effect.annotateLogs({ role: "server" })),
+  )
+})
+
+// The latest atomic registration wins. A displaced process notices the new id,
+// exits, and cannot remove its successor's registration from its finalizer.
+const infoJson = Schema.fromJsonString(Service.Info)
+const encodeInfo = Schema.encodeEffect(infoJson)
+const decodeInfo = Schema.decodeUnknownEffect(infoJson)
+
+const register = Effect.fnUntraced(function* (address: HttpServer.Address, password: string) {
+  const fs = yield* FileSystem.FileSystem
+  const options = yield* ServiceConfig.options()
+  const id = randomUUID()
+  const temp = options.file + "." + id + ".tmp"
+  yield* fs.makeDirectory(path.dirname(options.file), { recursive: true })
+  const encoded = yield* encodeInfo({
+    id,
+    version: InstallationVersion,
+    url: HttpServer.formatAddress(address),
+    pid: process.pid,
+    password,
+  })
+  yield* fs.writeFileString(temp, encoded, { mode: 0o600 })
+  yield* fs.rename(temp, options.file)
+  const currentID = fs.readFileString(options.file).pipe(
+    Effect.flatMap(decodeInfo),
+    Effect.map((info) => info.id),
+    Effect.orElseSucceed(() => undefined),
+  )
+  yield* currentID.pipe(
+    Effect.flatMap((current) =>
+      current === id
+        ? Effect.void
+        : Effect.try({ try: () => process.kill(process.pid, "SIGTERM"), catch: (cause) => cause }).pipe(Effect.ignore),
+    ),
+    Effect.repeat(Schedule.spaced("10 seconds")),
+    Effect.forkScoped,
+  )
+  yield* Effect.addFinalizer(() =>
+    currentID.pipe(
+      Effect.flatMap((current) => (current === id ? fs.remove(options.file) : Effect.void)),
+      Effect.ignore,
+    ),
+  )
+})
+
+function waitForStdinClose() {
+  return Effect.callback<void>((resume) => {
+    const close = () => resume(Effect.void)
+    process.stdin.once("end", close)
+    process.stdin.once("close", close)
+    process.stdin.resume()
+    if (process.stdin.readableEnded || process.stdin.destroyed) close()
+    return Effect.sync(() => {
+      process.stdin.off("end", close)
+      process.stdin.off("close", close)
+      process.stdin.pause()
+    })
+  })
+}

packages/cli/src/services/daemon.ts

@@ -1,192 +0,0 @@
-import { Global } from "@opencode-ai/core/global"
-import { InstallationVersion } from "@opencode-ai/core/installation/version"
-import { createOpencodeClient } from "@opencode-ai/sdk/v2/client"
-import { ServerAuth } from "@opencode-ai/server/auth"
-import { Context, Effect, FileSystem, Layer, Option, Schedule, Schema, Scope } from "effect"
-import { HttpServer } from "effect/unstable/http"
-import { randomBytes, randomUUID } from "crypto"
-import { spawn } from "node:child_process"
-import path from "path"
-
-export interface Interface {
-  readonly client: () => Effect.Effect<ReturnType<typeof createOpencodeClient>, unknown>
-  readonly transport: () => Effect.Effect<{ url: string; headers: RequestInit["headers"] }, unknown>
-  readonly start: () => Effect.Effect<string, Error>
-  readonly status: () => Effect.Effect<string | undefined>
-  readonly stop: () => Effect.Effect<void, unknown>
-  readonly password: (value?: string) => Effect.Effect<string, unknown>
-  readonly register: (address: HttpServer.Address) => Effect.Effect<void, unknown, Scope.Scope>
-}
-
-export class Service extends Context.Service<Service, Interface>()("@opencode/cli/Daemon") {}
-
-const Registration = Schema.Struct({
-  id: Schema.optional(Schema.String),
-  version: Schema.optional(Schema.String),
-  url: Schema.String,
-  pid: Schema.Int.check(Schema.isGreaterThan(0)),
-})
-type Registration = typeof Registration.Type
-
-function sameRegistration(left: Registration, right: Registration) {
-  return left.id === right.id && left.version === right.version && left.url === right.url && left.pid === right.pid
-}
-
-export const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem
-    const directory = Global.Path.state
-    const file = path.join(directory, "server.json")
-    const passwordFile = path.join(directory, "password")
-    const decodeRegistration = Schema.decodeUnknownEffect(Schema.fromJsonString(Registration))
-
-    const password = Effect.fn("cli.daemon.password")(function* (value?: string) {
-      const existing = yield* fs.readFileString(passwordFile).pipe(Effect.catch(() => Effect.succeed(undefined)))
-      if (value === undefined && existing) return existing
-
-      // Keep one private credential across server restarts so discovered clients
-      // can reconnect without exposing a password flag or environment variable.
-      const generated = value ?? randomBytes(32).toString("base64url")
-      const temp = passwordFile + ".tmp"
-      yield* fs.makeDirectory(directory, { recursive: true })
-      yield* fs.writeFileString(temp, generated, { mode: 0o600 })
-      yield* fs.rename(temp, passwordFile)
-      return generated
-    })
-
-    const registration = Effect.fnUntraced(function* () {
-      return yield* fs.readFileString(file).pipe(Effect.flatMap(decodeRegistration))
-    })
-
-    const createClient = Effect.fnUntraced(function* (url: string) {
-      return createOpencodeClient({ baseUrl: url, headers: ServerAuth.headers({ password: yield* password() }) })
-    })
-
-    const healthy = Effect.fnUntraced(function* () {
-      const info = yield* registration()
-      const client = yield* createClient(info.url)
-      const response = yield* Effect.tryPromise(() => client.v2.health.get({ signal: AbortSignal.timeout(2_000) }))
-      if (response.data?.healthy === true) return info
-      return yield* Effect.fail(new Error("Registered server is not healthy"))
-    })
-
-    const compatible = Effect.fnUntraced(function* () {
-      const info = yield* healthy()
-      if (info.version === InstallationVersion) return info
-      return yield* Effect.fail(new Error("Registered server version does not match the client"))
-    })
-
-    const signal = (pid: number, signal: NodeJS.Signals) =>
-      Effect.try({ try: () => process.kill(pid, signal), catch: (cause) => cause }).pipe(Effect.ignore)
-
-    const awaitStopped = Effect.fnUntraced(function* (pid: number) {
-      const running = yield* Effect.try({ try: () => process.kill(pid, 0), catch: () => false }).pipe(
-        Effect.orElseSucceed(() => false),
-      )
-      if (!running) return true
-      return yield* Effect.fail(new Error(`Server process ${pid} is still running`))
-    })
-
-    const stopProcess = Effect.fnUntraced(function* (info: Registration) {
-      const current = yield* healthy().pipe(Effect.option)
-      if (Option.isNone(current) || !sameRegistration(current.value, info)) return
-
-      yield* signal(info.pid, "SIGTERM")
-      const stopped = yield* awaitStopped(info.pid).pipe(
-        Effect.retry(Schedule.spaced("50 millis").pipe(Schedule.both(Schedule.recurs(100)))),
-        Effect.option,
-      )
-      if (Option.isSome(stopped)) return
-
-      const latest = yield* healthy().pipe(Effect.option)
-      if (Option.isNone(latest) || !sameRegistration(latest.value, info)) return
-      yield* signal(info.pid, "SIGKILL")
-      yield* awaitStopped(info.pid).pipe(
-        Effect.retry(Schedule.spaced("50 millis").pipe(Schedule.both(Schedule.recurs(100)))),
-      )
-    })
-
-    const start = Effect.fn("cli.daemon.start")(function* () {
-      const existing = yield* healthy().pipe(Effect.option)
-      const found = Option.getOrUndefined(existing)
-      const compiled = path.basename(process.execPath).replace(/\.exe$/, "") !== "bun"
-      if (found?.version === InstallationVersion && compiled) return found.url
-      if (found) yield* stopProcess(found).pipe(Effect.ignore)
-
-      const entrypoint = compiled ? undefined : process.argv[1]
-      if (!compiled && entrypoint === undefined)
-        return yield* Effect.fail(new Error("Failed to resolve CLI entrypoint"))
-      yield* Effect.try({
-        try: () => {
-          spawn(process.execPath, [...(entrypoint ? [entrypoint] : []), "serve", "--register"], {
-            detached: true,
-            stdio: "ignore",
-          }).unref()
-        },
-        catch: (cause) => new Error("Failed to start server", { cause }),
-      })
-
-      return yield* compatible().pipe(
-        Effect.retry(Schedule.spaced("50 millis").pipe(Schedule.both(Schedule.recurs(100)))),
-        Effect.map((info) => info.url),
-        Effect.mapError(() => new Error("Failed to start server")),
-      )
-    })
-
-    const transport = Effect.fn("cli.daemon.transport")(function* () {
-      return { url: yield* start(), headers: ServerAuth.headers({ password: yield* password() }) }
-    })
-
-    const client = Effect.fn("cli.daemon.client")(function* () {
-      const connection = yield* transport()
-      return createOpencodeClient({ baseUrl: connection.url, headers: connection.headers })
-    })
-
-    const status = Effect.fn("cli.daemon.status")(function* () {
-      const existing = yield* healthy().pipe(Effect.option)
-      const found = Option.getOrUndefined(existing)
-      if (found?.version === InstallationVersion) return found.url
-      if (found) return undefined
-      yield* fs.remove(file).pipe(Effect.ignore)
-      return undefined
-    })
-
-    const stop = Effect.fn("cli.daemon.stop")(function* () {
-      const existing = yield* healthy().pipe(Effect.option)
-      // A stale registration may point at a PID that has since been reused by
-      // another process. Only signal the PID after authenticating the server.
-      if (Option.isNone(existing)) return yield* fs.remove(file).pipe(Effect.ignore)
-      yield* stopProcess(existing.value)
-      yield* fs.remove(file).pipe(Effect.ignore)
-    })
-
-    const register = Effect.fn("cli.daemon.register")(function* (address: HttpServer.Address) {
-      const id = randomUUID()
-      const temp = file + "." + id + ".tmp"
-      yield* fs.makeDirectory(directory, { recursive: true })
-      yield* fs.writeFileString(
-        temp,
-        JSON.stringify({ id, version: InstallationVersion, url: HttpServer.formatAddress(address), pid: process.pid }),
-        { mode: 0o600 },
-      )
-      yield* fs.rename(temp, file)
-      yield* registration().pipe(
-        Effect.flatMap((info) => (info.id === id ? Effect.void : signal(process.pid, "SIGTERM"))),
-        Effect.catch(() => signal(process.pid, "SIGTERM")),
-        Effect.repeat(Schedule.spaced("10 seconds")),
-        Effect.forkScoped,
-      )
-      yield* Effect.addFinalizer(() =>
-        registration().pipe(
-          Effect.flatMap((info) => (info.id === id ? fs.remove(file) : Effect.void)),
-          Effect.ignore,
-        ),
-      )
-    })
-
-    return Service.of({ client, transport, start, status, stop, password, register })
-  }),
-)
-
-export * as Daemon from "./daemon"

packages/cli/src/services/service-config.ts

@@ -0,0 +1,143 @@
+import { Global } from "@opencode-ai/core/global"
+import { InstallationChannel, InstallationVersion } from "@opencode-ai/core/installation/version"
+import { Service } from "@opencode-ai/client/effect"
+import { Effect, FileSystem, Schema } from "effect"
+import { randomBytes } from "crypto"
+import path from "path"
+
+// The CLI's service configuration file, plus the Service.Options binding that
+// points the client package's service operations at this CLI: which
+// registration file (by channel), which version, and how to spawn opencode.
+
+export const Info = Schema.Struct({
+  hostname: Schema.optional(Schema.String),
+  port: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(65_535))),
+  password: Schema.optional(Schema.String),
+})
+export type Info = typeof Info.Type
+
+const keys = ["hostname", "port", "password"] as const
+type Key = (typeof keys)[number]
+
+const decodeInfo = Schema.decodeUnknownEffect(Schema.fromJsonString(Info))
+
+function configKey(key: string): Key {
+  if (keys.includes(key as Key)) return key as Key
+  throw new Error(`Unknown service config key: ${key}`)
+}
+
+const env = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  const global = yield* Global.Service
+  const filename = InstallationChannel === "local" ? "service-local.json" : "service.json"
+  return {
+    fs,
+    file: path.join(global.state, filename),
+    configFile: path.join(global.config, filename),
+  }
+})
+
+export const options = Effect.fnUntraced(function* () {
+  const { file } = yield* env
+  const compiled = path.basename(process.execPath).replace(/\.exe$/, "") !== "bun"
+  const entrypoint = compiled ? undefined : process.argv[1]
+  if (!compiled && entrypoint === undefined) return yield* Effect.fail(new Error("Failed to resolve CLI entrypoint"))
+  return {
+    file,
+    version: InstallationVersion,
+    command: [process.execPath, ...(entrypoint ? [entrypoint] : []), "serve", "--service"],
+  }
+})
+
+export const read = Effect.fn("cli.service-config.read")(function* () {
+  const { fs, configFile } = yield* env
+  return yield* fs.readFileString(configFile).pipe(
+    Effect.flatMap(decodeInfo),
+    Effect.catch(() => Effect.succeed({} as Info)),
+  )
+})
+
+const write = Effect.fn("cli.service-config.write")(function* (value: Info) {
+  const { fs, configFile } = yield* env
+  const temp = configFile + ".tmp"
+  yield* fs.makeDirectory(path.dirname(configFile), { recursive: true })
+  yield* fs.writeFileString(temp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 })
+  yield* fs.rename(temp, configFile)
+})
+
+export const password = Effect.fn("cli.service-config.password")(function* (value?: string) {
+  const existing = yield* read()
+  if (value === undefined && existing.password) return existing.password
+  const next = value ?? randomBytes(32).toString("base64url")
+
+  // Keep one private credential across server restarts so discovered clients
+  // can reconnect without exposing a password flag or environment variable.
+  yield* write({ ...existing, password: next })
+  return next
+})
+
+export const get = Effect.fn("cli.service-config.get")(function* (key?: string) {
+  if (key === undefined) {
+    const { password: _password, ...safe } = yield* read()
+    return JSON.stringify(safe, null, 2)
+  }
+  switch (configKey(key)) {
+    case "hostname": {
+      return (yield* read()).hostname ?? ""
+    }
+    case "port": {
+      const port = (yield* read()).port
+      return port === undefined ? "" : String(port)
+    }
+    case "password": {
+      return yield* password()
+    }
+  }
+})
+
+export const set = Effect.fn("cli.service-config.set")(function* (key: string, value: string) {
+  switch (configKey(key)) {
+    case "hostname": {
+      yield* Service.stop(yield* options())
+      yield* write({ ...(yield* read()), hostname: value })
+      return
+    }
+    case "port": {
+      const port = Number(value)
+      if (!Number.isInteger(port) || port < 1 || port > 65_535) throw new Error("Port must be between 1 and 65535")
+      yield* Service.stop(yield* options())
+      yield* write({ ...(yield* read()), port })
+      return
+    }
+    case "password": {
+      yield* Service.stop(yield* options())
+      yield* password(value)
+      return
+    }
+  }
+})
+
+export const unset = Effect.fn("cli.service-config.unset")(function* (key: string) {
+  switch (configKey(key)) {
+    case "hostname": {
+      yield* Service.stop(yield* options())
+      const { hostname: _hostname, ...next } = yield* read()
+      yield* write(next)
+      return
+    }
+    case "port": {
+      yield* Service.stop(yield* options())
+      const { port: _port, ...next } = yield* read()
+      yield* write(next)
+      return
+    }
+    case "password": {
+      yield* Service.stop(yield* options())
+      const { password: _password, ...next } = yield* read()
+      yield* write(next)
+      return
+    }
+  }
+})
+
+export * as ServiceConfig from "./service-config"

packages/cli/src/services/standalone.ts

@@ -0,0 +1,54 @@
+import { ServerAuth } from "@opencode-ai/server/auth"
+import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Effect, Schema, Stream } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+import { randomBytes } from "node:crypto"
+import path from "node:path"
+
+const Ready = Schema.Struct({ url: Schema.String })
+const decodeReady = Schema.decodeUnknownPromise(Schema.fromJsonString(Ready))
+
+type Options = {
+  readonly command?: ReadonlyArray<string>
+}
+
+function command(password: string, options: Options) {
+  const compiled = path.basename(process.execPath).replace(/\.exe$/, "") !== "bun"
+  const entrypoint = compiled ? [] : process.argv[1] ? [process.argv[1]] : []
+  if (!compiled && entrypoint.length === 0) throw new Error("Failed to resolve CLI entrypoint")
+  const [executable, ...args] = options.command ?? [process.execPath, ...entrypoint, "serve"]
+  if (!executable) throw new Error("Failed to resolve standalone server command")
+  return ChildProcess.make(executable, [...args, "--stdio", "--port", "0"], {
+    cwd: process.cwd(),
+    // Explicit entry wins over anything inherited, so a user-exported
+    // OPENCODE_PASSWORD cannot shadow the child's lease credential.
+    env: { OPENCODE_PASSWORD: password },
+    extendEnv: true,
+    // The server treats EOF on this pipe as the end of its ownership lease.
+    // The OS closes it even when the TUI is killed before Effect finalizers run.
+    stdin: "pipe",
+    stderr: "ignore",
+    killSignal: "SIGTERM",
+    forceKillAfter: "3 seconds",
+  })
+}
+
+const makeTransport = Effect.fn("cli.standalone.transport")(
+  function* (options: Options) {
+    const password = randomBytes(32).toString("base64url")
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+    const proc = yield* spawner.spawn(command(password, options))
+    const output = yield* proc.stdout.pipe(Stream.decodeText(), Stream.splitLines, Stream.take(1), Stream.mkString)
+    if (!output) return yield* Effect.fail(new Error("Standalone server exited before reporting readiness"))
+    const ready = yield* Effect.tryPromise(() => decodeReady(output))
+    return { url: ready.url, headers: ServerAuth.headers({ password, username: "opencode" }), pid: proc.pid }
+  },
+  Effect.provide(AppNodeBuilder.build(CrossSpawnSpawner.node)),
+)
+
+export function transport(options: Options = {}) {
+  return makeTransport(options)
+}
+
+export * as Standalone from "./standalone"

packages/cli/src/services/updater.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test"
+import { action, decodePolicy } from "./updater"
+
+describe("updater", () => {
+  test("reads autoupdate from JSONC", () => {
+    expect(decodePolicy('{ // preference\n "autoupdate": "notify",\n}')).toBe("notify")
+    expect(decodePolicy('{ "autoupdate": false }')).toBe(false)
+    expect(decodePolicy('{ "autoupdate": "invalid" }')).toBeUndefined()
+  })
+
+  test("automatically updates patches and minors", () => {
+    expect(action("1.2.3", "1.2.4", true)).toBe("upgrade")
+    expect(action("1.2.3", "1.3.0", true)).toBe("upgrade")
+    expect(action("1.2.3", "1.2.4", "notify")).toBe("upgrade")
+    expect(action("1.2.3", "1.3.0", "notify")).toBe("upgrade")
+  })
+
+  test("skips when autoupdate is disabled", () => {
+    expect(action("1.2.3", "1.2.4", false)).toBe("none")
+  })
+
+  test("never automatically updates majors", () => {
+    expect(action("1.2.3", "2.0.0", true)).toBe("none")
+  })
+
+  test("reports up-to-date only when versions match", () => {
+    expect(action("1.2.3", "1.2.3", true)).toBe("none")
+  })
+
+  test("upgrades when latest is lower (rollback)", () => {
+    expect(action("1.2.4", "1.2.3", true)).toBe("upgrade")
+  })
+})

packages/cli/src/services/updater.ts

@@ -0,0 +1,156 @@
+import { Global } from "@opencode-ai/core/global"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import { AppProcess } from "@opencode-ai/core/process"
+import {
+  InstallationChannel,
+  InstallationLocal,
+  InstallationVersion,
+} from "@opencode-ai/core/installation/version"
+import { Context, Duration, Effect, FileSystem, Layer } from "effect"
+import { ChildProcess } from "effect/unstable/process"
+import { parse, type ParseError } from "jsonc-parser"
+import path from "node:path"
+import semver from "semver"
+
+export type Policy = boolean | "notify"
+export type Action = "none" | "upgrade"
+type Method = "npm" | "pnpm" | "bun" | "yarn"
+
+const packageName = "@opencode-ai/cli"
+
+export interface Interface {
+  readonly check: () => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/cli/Updater") {}
+
+export function decodePolicy(text: string): Policy | undefined {
+  // The CLI only projects this host-level preference instead of initializing
+  // the location-scoped server configuration graph.
+  const errors: ParseError[] = []
+  const input: unknown = parse(text, errors, { allowTrailingComma: true })
+  if (errors.length || typeof input !== "object" || input === null || !("autoupdate" in input)) return
+  const value = input.autoupdate
+  if (typeof value === "boolean" || value === "notify") return value
+}
+
+export function action(current: string, latest: string, policy: Policy): Action {
+  if (policy === false) return "none"
+  if (!semver.valid(current) || !semver.valid(latest) || semver.eq(latest, current)) return "none"
+  // Major upgrades are never installed automatically.
+  if (semver.major(latest) !== semver.major(current)) return "none"
+  return "upgrade"
+}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const global = yield* Global.Service
+    const appProcess = yield* AppProcess.Service
+    const channel = InstallationChannel.replace(/[^a-zA-Z0-9._-]/g, "-")
+
+    const readPolicy = Effect.fnUntraced(function* () {
+      const values = yield* Effect.forEach(["config.json", "opencode.json", "opencode.jsonc"], (name) =>
+        fs
+          .readFileString(path.join(global.config, name))
+          .pipe(Effect.map(decodePolicy), Effect.catch(() => Effect.succeed(undefined))),
+      )
+      return values.findLast((value) => value !== undefined) ?? true
+    })
+
+    const run = Effect.fnUntraced(function* (command: string[], timeout: Duration.Input = "10 seconds") {
+      return yield* appProcess
+        .run(ChildProcess.make(command[0], command.slice(1)), {
+          timeout,
+          maxOutputBytes: 100_000,
+          maxErrorBytes: 100_000,
+        })
+        .pipe(
+          Effect.map((result) => ({
+            code: result.exitCode,
+            stdout: result.stdout.toString("utf8"),
+            stderr: result.stderr.toString("utf8"),
+          })),
+          Effect.catch(() => Effect.succeed({ code: 1, stdout: "", stderr: "" })),
+        )
+    })
+
+    const method = Effect.fnUntraced(function* () {
+      const checks: ReadonlyArray<{ method: Method; command: string[] }> = [
+        { method: "npm", command: ["npm", "list", "-g", "--depth=0", packageName] },
+        { method: "pnpm", command: ["pnpm", "list", "-g", "--depth=0", packageName] },
+        { method: "bun", command: ["bun", "pm", "ls", "-g"] },
+        { method: "yarn", command: ["yarn", "global", "list"] },
+      ]
+      const results = yield* Effect.forEach(
+        checks,
+        (check) => run(check.command).pipe(Effect.map((result) => ({ check, result }))),
+        { concurrency: "unbounded" },
+      )
+      return results.find((result) => result.result.stdout.includes(packageName))?.check.method
+    })
+
+    const latest = Effect.fnUntraced(function* () {
+      const response = yield* Effect.tryPromise({
+        try: () =>
+          fetch(
+            `https://registry.npmjs.org/${encodeURIComponent(packageName)}/${encodeURIComponent(InstallationChannel)}`,
+            { headers: { "User-Agent": `opencode/${InstallationVersion}` }, signal: AbortSignal.timeout(10_000) },
+          ),
+        catch: (cause) => new Error("Failed to check for updates", { cause }),
+      })
+      if (!response.ok) return yield* Effect.fail(new Error(`Update check failed with status ${response.status}`))
+      const data = yield* Effect.tryPromise({
+        try: () => response.json(),
+        catch: (cause) => new Error("Failed to read update information", { cause }),
+      })
+      if (typeof data !== "object" || data === null || !("version" in data) || typeof data.version !== "string") {
+        return yield* Effect.fail(new Error("Update information did not include a version"))
+      }
+      return data.version
+    })
+
+    const upgrade = Effect.fnUntraced(function* (method: Method, version: string) {
+      const target = `${packageName}@${version}`
+      const commands: Record<Method, string[]> = {
+        npm: ["npm", "install", "--global", target],
+        pnpm: ["pnpm", "install", "--global", target],
+        bun: ["bun", "install", "--global", target],
+        yarn: ["yarn", "global", "add", target],
+      }
+      const result = yield* run(commands[method], "5 minutes")
+      if (result.code === 0) return
+      return yield* Effect.fail(new Error(result.stderr.trim() || `Failed to update with ${method}`))
+    })
+
+    const check = Effect.fn("cli.updater.check")(function* () {
+      if (InstallationLocal || Flag.OPENCODE_DISABLE_AUTOUPDATE)
+        return yield* Effect.logInfo("update check skipped", {
+          reason: InstallationLocal ? "local-install" : "disabled",
+          version: InstallationVersion,
+          channel: InstallationChannel,
+        })
+      const policy = yield* readPolicy()
+      if (policy === false) return yield* Effect.logInfo("update check skipped", { reason: "policy-disabled" })
+
+      return yield* Effect.gen(function* () {
+        const version = yield* latest()
+        yield* Effect.logInfo("update check", {
+          current: InstallationVersion,
+          latest: version,
+        })
+        const next = action(InstallationVersion, version, policy)
+        if (next === "none") return yield* Effect.logInfo("update check done", { action: "up-to-date" })
+        const detected = yield* method()
+        if (!detected) return yield* Effect.logWarning("automatic update skipped: installation method not found")
+        yield* upgrade(detected, version)
+        yield* Effect.logInfo("updated OpenCode", { from: InstallationVersion, to: version, method: detected })
+      })
+    }, Effect.catchCause((cause) => Effect.logWarning("automatic update failed", { cause })))
+
+    return Service.of({ check })
+  }),
+)
+
+export * as Updater from "./updater"

packages/cli/src/tui.ts

@@ -3,35 +3,52 @@ import { TuiConfig } from "@opencode-ai/tui/config"
 import { Effect } from "effect"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { Global } from "@opencode-ai/core/global"
+import { loadBuiltinPlugins } from "@opencode-ai/tui/builtins"
+import { OpenCode } from "@opencode-ai/client/promise"
+import type { Service } from "@opencode-ai/client/effect"
+import { createOpencodeClient } from "@opencode-ai/sdk/v2/client"
+import type { Args } from "@opencode-ai/tui/context/args"
 
-export function runTui(transport: { url: string; headers: RequestInit["headers"] }) {
+export function runTui(
+  transport: Service.Transport,
+  args: Args,
+  discover?: () => Promise<Service.Transport>,
+  reload?: () => Promise<void>,
+) {
   const config = TuiConfig.resolve({}, { terminalSuspend: false })
-  return run({
-    ...transport,
-    args: {},
-    config,
-    fetch: gracefulFetch,
-    pluginHost: {
-      async start() {},
-      async dispose() {},
-    },
+  let disposeSlots: (() => void) | undefined
+  return Effect.gen(function* () {
+    const options = { baseUrl: transport.url, headers: transport.headers }
+    const api = OpenCode.make(options)
+    const directory = yield* Effect.tryPromise(() => api.file.list({ location: { directory: process.cwd() } })).pipe(
+      Effect.map((response) => response.location.directory),
+      Effect.catch(() =>
+        Effect.tryPromise(() => api.location.get()).pipe(Effect.map((response) => response.directory)),
+      ),
+    )
+    return yield* run({
+      client: createOpencodeClient({ ...options, directory }),
+      api,
+      discover: discover
+        ? async () => {
+            const next = await discover()
+            return {
+              client: createOpencodeClient({ baseUrl: next.url, headers: next.headers, directory }),
+              api: OpenCode.make({ baseUrl: next.url, headers: next.headers }),
+            }
+          }
+        : undefined,
+      reload,
+      args,
+      config,
+      pluginHost: {
+        async start(input) {
+          disposeSlots = await loadBuiltinPlugins(input.api, input.runtime)
+        },
+        async dispose() {
+          disposeSlots?.()
+        },
+      },
+    })
   }).pipe(Effect.provide(AppNodeBuilder.build(Global.node)))
 }
-
-const legacyDefaults: Record<string, unknown> = {
-  "/config/providers": { providers: [], default: {} },
-  "/provider": { all: [], default: {}, connected: [] },
-  "/agent": [],
-  "/config": {},
-}
-
-const gracefulFetch = Object.assign(
-  async (input: RequestInfo | URL, init?: RequestInit) => {
-    const response = await fetch(input, init)
-    if (response.status !== 404) return response
-    const fallback = legacyDefaults[new URL(input instanceof Request ? input.url : input).pathname]
-    if (fallback === undefined) return response
-    return Response.json(fallback)
-  },
-  { preconnect: fetch.preconnect },
-)

packages/cli/test/code-mode.test.ts

@@ -0,0 +1,39 @@
+import { expect, test } from "bun:test"
+import { CodeMode } from "@opencode-ai/codemode"
+import { Effect, Layer } from "effect"
+import { HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { CodeModeHost } from "../src/code-mode"
+
+test("exposes the authenticated OpenCode API through CodeMode", async () => {
+  const requests: Array<{ readonly url: string; readonly authorization?: string }> = []
+  const client = Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => {
+      requests.push({ url: request.url, authorization: request.headers.authorization })
+      return Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          Response.json(
+            { healthy: true, version: "test", pid: 1 },
+            { headers: { "content-type": "application/json" } },
+          ),
+        ),
+      )
+    }),
+  )
+  const result = await CodeMode.make({ tools: CodeModeHost.makeTools(client, "secret") })
+    .execute("return await tools.opencode.v2.health.get({})")
+    .pipe(Effect.runPromise)
+
+  expect(result).toEqual({
+    ok: true,
+    value: { healthy: true, version: "test", pid: 1 },
+    toolCalls: [{ name: "opencode.v2.health.get" }],
+  })
+  expect(requests).toEqual([
+    {
+      url: "http://opencode.local/api/health",
+      authorization: `Basic ${Buffer.from("opencode:secret").toString("base64")}`,
+    },
+  ])
+})

packages/cli/test/fixture/standalone-owner.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect"
+import path from "node:path"
+import { Standalone } from "../../src/services/standalone"
+
+process.argv[1] = path.join(import.meta.dir, "../../src/index.ts")
+
+await Effect.runPromise(
+  Effect.scoped(
+    Effect.gen(function* () {
+      const transport = yield* Standalone.transport()
+      const response = yield* Effect.promise(() => fetch(new URL("/api/health", transport.url), { headers: transport.headers }))
+      console.log(`${transport.pid} ${transport.url} ${response.status}`)
+      return yield* Effect.never
+    }),
+  ),
+)

packages/cli/test/mini.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, test } from "bun:test"
+import { InstallationVersion } from "@opencode-ai/core/installation/version"
+import path from "node:path"
+import { mergeInteractiveInput, mergeNonInteractiveInput, pickRunModel } from "../src/mini"
+
+async function cli(args: string[]) {
+  const child = Bun.spawn([process.execPath, "run", "src/index.ts", ...args], {
+    cwd: path.join(import.meta.dir, ".."),
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  return { stdout, stderr, exitCode }
+}
+
+describe("mini command", () => {
+  test("uses piped stdin as the initial prompt", () => {
+    expect(mergeInteractiveInput("from stdin", undefined)).toBe("from stdin")
+    expect(mergeInteractiveInput("from stdin", "from flag")).toBe("from stdin\nfrom flag")
+  })
+
+  test("keeps run as mini's non-interactive input mode", () => {
+    expect(mergeNonInteractiveInput("from args", "from stdin")).toBe("from args\nfrom stdin")
+    expect(mergeNonInteractiveInput(undefined, "from stdin")).toBe("from stdin")
+  })
+
+  test("applies a variant to a resumed session's model", () => {
+    expect(
+      pickRunModel(
+        undefined,
+        "high",
+        { providerID: "session-provider", modelID: "session-model" },
+        { providerID: "default-provider", modelID: "default-model" },
+      ),
+    ).toEqual({ providerID: "session-provider", modelID: "session-model" })
+  })
+
+  test("is registered in the preview CLI", async () => {
+    const result = await cli(["--help"])
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain("mini       Start the minimal interactive interface")
+    expect(result.stdout).toContain("run        Run OpenCode with a message")
+  })
+
+  test("exposes run without legacy attach or command modes", async () => {
+    const result = await cli(["run", "--help"])
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain("--server string")
+    expect(result.stdout).not.toContain("--attach")
+    expect(result.stdout).not.toContain("--command")
+  })
+
+  test("keeps option-like prompt text after the argument separator", async () => {
+    const result = await cli(["run", "--server", "http://127.0.0.1:1", "--", "--foo"])
+
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).not.toContain("You must provide a message")
+  })
+
+  test("preserves a run failure exit code", async () => {
+    let modelRequests = 0
+    const server = Bun.serve({
+      port: 0,
+      fetch(request) {
+        const url = new URL(request.url)
+        if (url.pathname === "/api/health")
+          return Response.json({ healthy: true, version: InstallationVersion, pid: process.pid })
+        if (url.pathname === "/api/model") {
+          modelRequests++
+          return Response.json({
+            location: { directory: process.cwd(), project: { id: "global", directory: process.cwd() } },
+            data: modelRequests === 1 ? [{ id: "missing", providerID: "definitely" }] : [],
+          })
+        }
+        return new Response(undefined, { status: 404 })
+      },
+    })
+
+    try {
+      const result = await cli([
+        "run",
+        "--server",
+        server.url.toString(),
+        "--dir",
+        process.cwd(),
+        "--model",
+        "definitely/missing",
+        "hi",
+      ])
+
+      expect(result.exitCode).toBe(1)
+      expect(result.stderr).toContain("Model unavailable: definitely/missing")
+    } finally {
+      server.stop(true)
+    }
+  })
+
+  test("reports pre-admission errors as JSON", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({ healthy: true, version: "incompatible", pid: process.pid })
+      },
+    })
+
+    try {
+      const result = await cli(["run", "--format", "json", "--server", server.url.toString(), "hi"])
+
+      expect(result.exitCode).toBe(1)
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        type: "error",
+        sessionID: "",
+        error: { type: "unknown", message: "Failed to resolve server directory" },
+      })
+    } finally {
+      server.stop(true)
+    }
+  })
+
+  test("uses the shared V2 server option instead of an attach command", async () => {
+    const result = await cli(["mini", "--help"])
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain("--server string")
+    expect(result.stdout).not.toContain("SUBCOMMANDS")
+  })
+
+  test("routes local and explicit-server invocations into mini", async () => {
+    for (const args of [["mini"], ["mini", "--server", "http://127.0.0.1:1"]]) {
+      const result = await cli(args)
+
+      expect(result.exitCode).toBe(1)
+      expect(result.stderr).toContain("opencode mini requires a TTY stdout")
+    }
+  })
+})