@jmanuelcorral/openteam 0.18.1 → 0.20.0

package/README.md

@@ -2,7 +2,7 @@
 
 > 🌐 **Language / Idioma:** **English** (this document) · [Español](README.es.md)
 
-**openteam — a cost-aware, local-first routing plugin for [opencode](https://opencode.ai) with cheapest-capable FRONTIER fallback and on-demand multi-agent orchestration.**
+**openteam — operator-controlled local, frontier, and mixed model execution for [opencode](https://opencode.ai), with cheapest-capable automatic selection and on-demand multi-agent orchestration.**
 
 [![CI](https://github.com/jmanuelcorral/openteam/actions/workflows/ci.yml/badge.svg)](https://github.com/jmanuelcorral/openteam/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@jmanuelcorral/openteam.svg)](https://www.npmjs.com/package/@jmanuelcorral/openteam)
@@ -35,21 +35,29 @@
 
 ## What it is and why it exists
 
-openteam adds a routing and orchestration layer to opencode to **save frontier tokens and cost without sacrificing quality or privacy**. The default strategy is **local-first**: trivial tasks, summaries, simple docs and small diffs try local runtimes first; architecture, security, multi-file refactors, critical tool calling and ambiguous debugging escalate to **cheapest-capable FRONTIER**.
+openteam adds a routing and orchestration layer to opencode. The operator chooses
+a global **local**, **frontier**, or **mixed** execution domain; primary and
+worker policies can select an exact model or use cheapest-capable `"auto"`
+selection inside that domain.
 
-The router keeps a privacy guarantee: with `privacyMode: "forceLocalOnSensitive"`, a task flagged as `privacySensitive` never escalates to frontier.
+openteam does **not** inspect prompt content to infer sensitivity before a
+frontier call. Frontier egress is controlled explicitly: use `local` globally,
+or narrow an agent to `local` under global `mixed`, when frontier is prohibited.
 
 ## Features
 
 - Per-turn routing from the `chat.message` hook, mutating `output.message.model` before opencode persists the message.
 - Registration of OpenAI-compatible local runtimes: **Ollama**, **LM Studio**, **Lemonade Server** and **Foundry Local**.
-- Local JSON classifier with a deterministic heuristic fallback.
 - Capability profiles from [Models.dev](https://models.dev), with cache and a curated fallback when the catalog is unavailable.
-- **Cheapest-capable** frontier selection by blended cost `0.75 * inputUSD + 0.25 * outputUSD`.
+- **Cheapest-capable** automatic selection by cost, availability, tool support, and context requirements inside the allowed domain.
 - Budgets per session, per month and per frontier tokens per session.
 - Hash-only `CostRecord` JSONL telemetry: stores `promptHash`, cost/decision metrics — **never raw prompts**.
-- Multi-agent orchestration with `runRoleTask` / `runRoleTasks`, SDK child sessions and an explicit model in `client.session.prompt({ body: { model } })`.
+- Per-agent exact pins or `"auto"`, optional ordered fallbacks, and bounded cross-model handoff for an incomplete node.
+- Multi-agent orchestration with SDK child sessions and an explicit model in `client.session.prompt({ body: { model } })`.
 - Local availability refresh at startup and on `session.created` / `session.idle` events.
+- A metadata-only [agent timeline](docs/guide/agent-timeline.md) with durable
+  coordinator/attempt history, historical cursor inspection, and live
+  invalidation hints.
 - A local web **Console** aggregating every opencode session (cost, tokens, tool calls, routing, decisions) — redacted, loopback-only.
 - A read-only **MCP server** exposing aggregated team memory, plus opt-in semantic recall.
 
@@ -89,46 +97,16 @@ For direct opencode loading, reference the package name:
   "$schema": "https://opencode.ai/config.json",
   "model": "anthropic/claude-sonnet-4-5",
   "small_model": "ollama/qwen3:8b",
-  "plugin": [
-    [
-      "@jmanuelcorral/openteam",
-      {
-        "baseline": {
-          "mode": "auto",
-          "pinnedModel": null,
-          "hardDefault": { "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }
-        },
-        "router": {
-          "mode": "balanced",
-          "localDefault": { "providerID": "ollama", "modelID": "qwen3:8b" },
-          "trivialPromptMaxChars": 280,
-          "frontierPromptMinChars": 2000
-        },
-        "local": {
-          "runtimes": [
-            {
-              "id": "ollama",
-              "enabled": true,
-              "baseURL": "http://localhost:11434/v1",
-              "defaultModel": { "providerID": "ollama", "modelID": "qwen3:8b" }
-            }
-          ]
-        },
-        "budgets": {
-          "sessionUSD": 2,
-          "monthlyUSD": 30,
-          "frontierTokensPerSession": 250000,
-          "hardStopOnBudgetExhaustion": false
-        },
-        "privacyMode": "forceLocalOnSensitive",
-        "telemetry": { "enabled": true, "path": ".opencode/openteam-local/telemetry.jsonl" }
-      }
-    ]
-  ]
+  "plugin": ["@jmanuelcorral/openteam"]
 }
 ```
 
-The fastest way to get a repository ready is the interactive `openteam setup` command (below), which generates this configuration for you.
+Those model identifiers must exist in your configured opencode providers;
+replace them with available equivalents when needed.
+
+Keep operator routing policy in `.opencode/openteam.json`, not in the plugin
+declaration. The fastest way to create both files is the interactive
+`openteam setup` command below.
 
 ### Option B: development path
 
@@ -137,33 +115,29 @@ During development you can load a local plugin from `.opencode/plugins/openteam.
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": [
-    [
-      "./.opencode/plugins/openteam.ts",
-      {
-        "router": {
-          "mode": "balanced",
-          "localDefault": {
-            "providerID": "ollama",
-            "modelID": "qwen3:8b"
-          }
-        },
-        "telemetry": {
-          "path": ".opencode/openteam-local/telemetry.jsonl"
-        }
-      }
-    ]
-  ]
+  "plugin": ["./.opencode/plugins/openteam.ts"]
 }
 ```
 
-## Quickstart: `openteam setup`
+Development-path loading does not change the configuration boundary: keep
+operator policy in `.opencode/openteam.json`.
 
-`openteam setup` detects the installed local runtimes (Ollama, LM Studio, Lemonade Server, Foundry Local — all optional), lets you pick the local models and the **frontier baseline** model (sorted cheapest-capable first), and writes three files:
+## Quickstart: `openteam setup`
 
-- `opencode.json` at the repo root: declares the `@jmanuelcorral/openteam` plugin, the OpenAI-compatible local `provider`s, the frontier `model` and the local `small_model`.
-- `.opencode/openteam.json`: openteam's validated runtime configuration (baseline, routing, local runtimes, orchestrator roles and privacy).
+`openteam setup` detects the installed local runtimes (Ollama, LM Studio,
+Lemonade Server, Foundry Local — all optional), lets you pick local models and
+the **frontier baseline** (sorted cheapest-capable first), and writes the
+project configuration and generated agent/command artifacts:
+
+- `.opencode/opencode.json` for a new project, or the existing
+  `.opencode/opencode.json` / root `opencode.json`: declares the plugin, local
+  providers, frontier `model`, and local `small_model`.
+- `.opencode/openteam.json`: openteam's validated runtime configuration
+  (execution domain, local runtimes, primary/role model policies, budgets, and
+  bounded retries/handoffs).
 - `.opencode/agent/openteam.md`: the **primary `openteam` agent**, visible in the Tab switcher.
+- `.opencode/agent/<role>.md` for the standard dispatch targets, plus generated
+  `.opencode/command/*.md` entries and the local `.opencode/.gitignore`.
 
 ```powershell
 # One-off, without a global install
@@ -176,25 +150,66 @@ openteam setup
 
 The wizard:
 
-1. Probes local runtimes and marks the detected ones.
-2. Lets you enable runtimes (or **none** — frontier-only) and, per enabled runtime, choose whether it runs **on this machine** or **on another machine on the LAN** (by entering its URL, e.g. `http://192.168.1.50:11434/v1`), then pick each default model. If you run **more than one machine of the same kind** (e.g. two LM Studio hosts), it declares each as a separate instance with its own id (`lmstudio-a`, `lmstudio-b`), URL and models. For every instance it also asks how many **concurrent generation slots** the runtime has (defaulting to `4`), so you can leave a slot free for interactive work instead of saturating the server.
-3. Offers the frontier baseline from the **full [Models.dev](https://models.dev) catalog** that openteam integrates: a quick list with the **cheapest-capable first** (including **free** models, tagged `free`), a "Browse all models by provider…" option, and "Other (custom)" to type a `provider/model`. If the catalog can't be loaded (offline), it falls back to the curated list.
-4. Asks for the routing mode (`balanced` / `economy` / `quality`), the privacy policy, and whether to enable **YOLO mode** (auto-approve opencode permissions). If you enable no local runtime, it warns you are in **frontier-only mode** and recommends `consentBeforeFrontier`.
-5. If `opencode.json` or `.opencode/openteam.json` already exist, it asks for confirmation before overwriting.
-
-After `setup`, authenticate the frontier provider (`opencode auth login`), make sure your local runtime is reachable if you enabled one, and open opencode in the repo: openteam routes local-first automatically. Re-tune the baseline later with `openteam baseline set <provider/model>` or `openteam baseline auto`.
+1. Probes local runtimes, then first asks which ones to enable. Choosing
+   **None** selects global `frontier` directly; it does not ask a redundant
+   three-way mode question and proceeds to frontier model selection.
+2. For each enabled runtime, choose this machine or another LAN host, its
+   default/thinking/coder models, and concurrency. Multiple instances retain
+   distinct runtime and provider identities.
+3. With at least one local runtime, choose the team execution mode (default
+   `mixed`). `local` pins the primary to the first enabled runtime's thinking
+   model or default; `frontier` asks for a frontier model; `mixed` asks whether
+   the primary uses that local model or the selected frontier model. Frontier
+   choices come from Models.dev cheapest-capable ordering, with browse/custom
+   and curated-offline fallbacks.
+4. Setup writes an exact primary policy with `fallbacks: []`, persists each
+   worker as the compact partial policy `{ "model": "auto" }`, and writes the
+   `2`/`2` retry/model limits. Primary `"auto"` and primary fallbacks are
+   supported by the schema and manual config, but setup does not prompt for
+   them.
+5. Choose whether to enable **YOLO mode**. Existing config files require
+   overwrite confirmation.
+
+After `setup`, authenticate a frontier provider if the configured policies allow
+frontier, make sure each configured local runtime is reachable, and open
+opencode in the repo. Re-tune the baseline later with
+`openteam baseline set <provider/model>` or `openteam baseline auto`.
+
+> **Upgrade note:** `privacyMode` is deprecated, ignored metadata and no longer prevents
+> frontier execution. Convert any required restriction to
+> `router.executionMode: "local"` or an agent `executionMode: "local"` under
+> global `mixed`.
 
 ## The `openteam` agent
 
-`openteam setup` generates a single **primary agent** named `openteam`. Press **Tab** in opencode to select it: you explicitly know you are in openteam mode while the plugin keeps optimizing the model underneath.
-
-That orchestrator ships **no pre-created subagents**. On **every request** its first action is to check whether a team already exists (`.opencode/openteam/roster.md` + subagents in `.opencode/agent/`). If it does, it hands work to the right specialists; if not, it understands the tasks your request implies, designs the minimal team and **creates it on demand** (writing `.opencode/agent/<name>.md` with `mode: subagent`), reusing existing agents before creating new ones. Mechanical/bulk roles are left to route to local models; only architecture, security or ambiguous debugging escalate to frontier. (This on-demand, themed-team model is inspired by [Squad](https://bradygaster.github.io/squad/) — see [Acknowledgements](#acknowledgements).)
+`openteam setup` generates a single **primary agent** named `openteam`. Press
+**Tab** in opencode to select it: you explicitly know you are in openteam mode.
+Its model follows the resolved global and primary-agent policy; the prompt does
+not select a domain by being judged sensitive or complex.
+
+The generated primary frontmatter and `opencode.json.model` use the same exact
+bootstrap model. Generated workers intentionally omit frontmatter `model`; their
+policies in `.opencode/openteam.json` are authoritative. Guardian, scribe, and
+ralph are not forced local by name.
+
+That orchestrator ships **no project-specific pre-created subagents**. On every
+request it checks whether a team already exists
+(`.opencode/openteam/roster.md` + subagents in `.opencode/agent/`). If needed,
+it designs the minimal team and creates it on demand, reusing existing agents
+first. Model placement comes from the global and per-agent policies, not from
+automatic sensitivity classification. The unified router may still derive
+capability and complexity requirements inside the permitted domain. (This
+on-demand, themed-team model is inspired by
+[Squad](https://bradygaster.github.io/squad/) — see
+[Acknowledgements](#acknowledgements).)
 
 The team has a **themed identity**: the orchestrator picks (or asks for) a **universe** and names each agent after a character, recording the cast in `.opencode/openteam/roster.md` so names **persist** across sessions. Besides project-specific roles, it plans three **standard roles** created on demand:
 
-- **scribe** — silent memory: logs decisions and learnings to `.opencode/openteam/decisions.md` without touching code (local model).
+- **scribe** — silent memory: logs decisions and learnings to `.opencode/openteam/decisions.md` without touching code.
 - **ralph** — automation and triage: monitors the backlog, prioritizes, coordinates execution and **escalates to the human** on blockers or approvals.
-- **guardian** — security and privacy: **detects and masks sensitive data** (PII, secrets, API keys, tokens) before it reaches frontier; always runs locally and respects `forceLocalOnSensitive`.
+- **guardian** — security review and operator-policy advice. It is not an
+  automatic pre-frontier content gate and has no built-in local requirement.
+  Configure `executionMode: "local"` explicitly if the role must stay local.
 
 Before delegating, the orchestrator **plans dependencies and parallelizes**: it splits the request into tasks and, since opencode runs all `task` calls emitted in a single turn in parallel (Vercel AI SDK), it launches independent tasks together and sequences only the dependent ones into waves. Work that collides on the same files is separated into distinct waves to avoid conflicts. In the **todo list** each entry shows the responsible agent via a name prefix, e.g. `[@Basher] Implement the router`.
 
@@ -230,7 +245,9 @@ To install and try openteam on another machine that already has [opencode](https
 
 4. **Start your local runtime** if you enabled one and it was not already up (e.g. `ollama serve`, or open LM Studio / Foundry Local). If you pointed at a runtime on **another machine on the LAN**, make sure it is reachable from this machine (host exposed and port open); for Ollama this usually means starting it with `OLLAMA_HOST=0.0.0.0 ollama serve` on the remote machine. If you configured **frontier-only**, skip this step.
 
-5. **Open opencode in the repo**, press **Tab** and pick the `openteam` agent. Give it the first prompt: it will create the subagent team on demand and route local-first automatically.
+5. **Open opencode in the repo**, press **Tab** and pick the `openteam` agent.
+   Give it the first prompt: it creates the subagent team on demand and runs
+   each agent within the configured execution domain.
 
 Check the status with `openteam doctor` (runtimes + config) and the savings with `openteam report`.
 
@@ -260,11 +277,19 @@ Notes when updating:
 
 ## Configuration
 
-The canonical runtime configuration lives in `.opencode/openteam.json`; this repo ships `.opencode/openteam.example.json` as a complete example. The Zod-validated shape is in `src/config/schema.ts`. `telemetry` is a plugin option read by `src/index.ts`, not part of the persisted `OpenTeamConfig`.
+The canonical runtime configuration lives in `.opencode/openteam.json`; this
+repo ships `.opencode/openteam.example.json` as a complete minimal v2 example,
+not as a byte-for-byte contract for every setup choice. Canonical v2
+serialization is compact: it omits default legacy heuristic values, retains
+non-default heuristic overrides for policy-less compatibility, and compacts
+resolved role profiles to partial policies relative to their built-in or
+synthesized baselines. The Zod-validated shape is in `src/config/schema.ts`.
+`telemetry` is a plugin option read by `src/index.ts`, not part of the persisted
+`OpenTeamConfig`.
 
 Config files are strict: unknown keys fail closed in both the CLI and plugin
 instead of being silently ignored. Errors name each rejected path (for example
-`router.trivialPromptMxChars`) and include a nearest-key hint when available.
+`router.executionMod`) and include a nearest-key hint when available.
 This strict validation applies to the config file on both paths; programmatic
 plugin options are a separate surface and are not yet strictly validated (#102).
 Existing configs without `configVersion` remain valid because openteam migrates
@@ -310,13 +335,15 @@ configured" and should `cd` to the project root first.
 
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
+| `configVersion` | `2`, optional input | canonical `2` | Missing means v1 and migrates before validation. Non-integer or below `1` is unknown; above `2` is unsupported. |
 | `baseline.mode` | `"auto" \| "pinned"` | `"auto"` | In `auto`, uses cheapest-capable frontier profiles when passed to the router; in `pinned`, uses `baseline.pinnedModel` if set. |
 | `baseline.pinnedModel` | `ModelRef \| null` | `null` | Explicitly pinned frontier model. `ModelRef` is `{ "providerID": string, "modelID": string }`. |
-| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }` | Frontier fallback when there are no cheapest-capable profiles or a valid pin. |
-| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Validated routing mode reserved for policy. |
+| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "google", "modelID": "gemini-3.5-flash" }` | Operator-configurable offline/curated fallback when no usable live or catalog profile drives automatic selection. It is not preferred over supplied profiles; `setup` may write the selected frontier model, and explicit per-agent pins remain allowed. |
+| `router.executionMode` | `"local" \| "frontier" \| "mixed"`, optional | effective `"mixed"` | Hard global execution-domain upper bound. Canonical serialization writes `"mixed"` when omitted. Agent policy may narrow `mixed`, never broaden `local` or `frontier`. |
+| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Canonical legacy heuristic setting for callers with no v2 agent policy. It is not per-agent model selection and never overrides `executionMode` or adds sensitivity routing. |
+| `router.trivialPromptMaxChars` | positive integer | `280` | Legacy policy-less mixed-routing threshold. Retained for compatible callers that supply no v2 agent policy; generated v2 policies do not rely on it. |
+| `router.frontierPromptMinChars` | positive integer | `2000` | Legacy policy-less mixed-routing threshold. Retained for compatible callers that supply no v2 agent policy; generated v2 policies do not rely on it. |
 | `router.localDefault` | `ModelRef \| null` | `null` | Primary local model. Not set by default — no local model is routed until you configure one via `openteam setup` or by hand. |
-| `router.trivialPromptMaxChars` | positive integer | `280` | Code-free prompts up to this size prefer local. |
-| `router.frontierPromptMinChars` | positive integer | `2000` | Prompts from this size are frontier candidates if no guards apply. |
 | `local.runtimes` | `LocalRuntime[]` | `[]` | Local runtimes to probe. Empty by default — no runtime is configured until you run `openteam setup` or add an entry by hand. |
 | `local.runtimes[].id` | string | required | Instance identity, unique within the array. Free-form (`lmstudio-a`, `lemonade-lan`) so two machines of the same kind are distinct; when `kind` is omitted it must itself be a runtime kind (back-compat). |
 | `local.runtimes[].kind` | `"ollama" \| "lmstudio" \| "foundry-local" \| "lemonade"` optional | migrates from `id` | Runtime kind selecting the adapter. Optional: when absent, `id` is treated as the kind, so pre-existing configs keep working unchanged. |
@@ -329,57 +356,118 @@ configured" and should `cd` to the project root first.
 | `budgets.sessionUSD` | positive number, optional | unlimited | Frontier budget per session. |
 | `budgets.monthlyUSD` | positive number, optional | unlimited | Monthly frontier budget. |
 | `budgets.frontierTokensPerSession` | positive integer, optional | unlimited | Frontier token limit per session. |
-| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | If `true`, an exhausted budget returns `blockFrontier`; if `false`, it forces local. |
-| `privacyMode` | `"forceLocalOnSensitive" \| "consentBeforeFrontier" \| "off"` | `"forceLocalOnSensitive"` | Privacy policy for sensitive tasks. |
-| `orchestrator.roles` | `Record<string, AgentRoleProfile>` | `{}` | Custom or overridden role profiles keyed by role ID. Config entries are validated with the same strict role profile schema as built-in roles and take precedence over `TEAM_ROLES`; if an entry omits `roleID`, the map key is used. Unknown roles not declared here still use the neutral fallback and warn once. |
+| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | Controls the configured budget action. It never authorizes leaving the execution domain. |
+| `orchestrator` | object, optional | absent | Holds primary/role policy and pass limits. |
+| `orchestrator.maxRetries` | non-negative integer, optional | effective `2` | Upper bound of extra openteam passes per authorized model; effective `2` permits up to three passes. The default is applied at runtime, not materialized by the schema. |
+| `orchestrator.maxModelsPerNode` | positive integer, optional | effective `2` | Total model candidates used by one node: the selected model plus at most one fallback by default. The runtime default is not materialized; with retry defaults it permits at most six attempts. |
+| `orchestrator.primary` | partial `ExecutionPolicy`, optional | absent | Policy for the primary coordinator. Every field is optional. |
+| `orchestrator.roles` | raw `Record<string, partial AgentRoleProfile>` | `{}` when `orchestrator` exists | Raw entries may be partial. Loaded entries are fully merged and validated: built-in profile first, otherwise a synthesized profile, then the raw override. |
 | `orchestrator.roles.<role>.opencodeAgent` | non-empty string, optional | role ID | opencode agent name to dispatch for that role. |
-| `orchestrator.roles.<role>.defaultTier` | `"trivial" \| "simple" \| "moderate" \| "hard"` | required | Baseline complexity tier used before heuristic and permission elevation. |
-| `orchestrator.roles.<role>.minReasoningTier` | `1`–`5` | required | Minimum reasoning capability for frontier candidates. |
-| `orchestrator.roles.<role>.minCodeQualityTier` | `1`–`5` | required | Minimum code-quality capability for frontier candidates. |
-| `orchestrator.roles.<role>.needsToolCallingByDefault` | `boolean` | required | Whether this role requires tool-calling capability unless the task says otherwise. |
-| `orchestrator.roles.<role>.preferredFrontierModels` | `Array<ModelRef \| "auto">` | required | Preferred frontier models; use `[]` for a local-first role with no explicit frontier preference. |
-| `orchestrator.roles.<role>.localFirst` | `boolean` | required | Whether the role should keep the normal local-first posture instead of forcing hard frontier routing. |
+| `orchestrator.primary.executionMode` / `orchestrator.roles.<role>.executionMode` | `"local" \| "frontier" \| "mixed"`, optional | inherited | May narrow global `mixed`; cannot contradict global `local` or `frontier`. |
+| `orchestrator.primary.model` / `orchestrator.roles.<role>.model` | `ModelRef \| "auto"`, optional | omitted means `"auto"` | Exact selection or deterministic capable/available in-domain automatic selection. Mixed mode is local-first where capable, then cheapest-capable when catalog cost exists. Static unconfigured, out-of-domain, or known-incapable pins fail validation; transiently offline candidates are skipped only at runtime. Missing costs are not treated as zero. |
+| `orchestrator.primary.fallbacks` / `orchestrator.roles.<role>.fallbacks` | `ModelRef[]`, optional | derived for auto; none for an exact pin | An explicit list replaces derived auto fallbacks and retains declared order after de-duplication and skipping the selected model. Every entry receives static identity/domain/capability validation before capping. A temporarily offline backup does not invalidate a healthy primary; it is skipped in favor of the next authorized candidate. |
+| `privacyMode` | legacy/deprecated | none | Accepted only as ignored compatibility metadata and removed on canonical persistence. Loading it emits one `privacy-mode-ignored` migration warning explaining frontier-egress risk and the `executionMode: "local"` remedy; the notice never changes routing. |
 | `telemetry.enabled` | `boolean` (plugin option) | `true` | Enable/disable JSONL writing. |
 | `telemetry.path` | `string` (plugin option) | `.opencode/openteam-local/telemetry.jsonl` | Path of the `CostRecord` JSONL log. |
 
-Example custom privacy/security auditor:
+Legacy `router.localOnly` and `router.frontierOnly` remain optional parse
+aliases so old files load; migration and canonical writes replace them with
+`executionMode`. `TaskSignals.privacySensitive?` likewise remains an optional
+historical caller field, but classification, scoring, rationale, and routing
+ignore it.
+
+Example explicit coordinator and worker policies:
+
+Exact policy models are always objects such as
+`{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }`, never a
+`"provider/model"` scalar. The slash/CLI baseline command and opencode's own
+`model` field use the scalar notation instead. Every example model must already
+exist in the operator's configured providers. A runtime instance ID such as
+`lmstudio-b` and a provider ID such as `lmstudio` are distinct concepts; use
+the provider identity configured for opencode.
 
 ```jsonc
 {
+  "configVersion": 2,
+  "router": { "executionMode": "mixed" },
   "orchestrator": {
+    "maxRetries": 2,
+    "maxModelsPerNode": 2,
+    "primary": {
+      "executionMode": "frontier",
+      "model": "auto"
+    },
     "roles": {
-      "galadriel": {
-        "opencodeAgent": "galadriel",
-        "defaultTier": "moderate",
-        "minReasoningTier": 3,
-        "minCodeQualityTier": 3,
-        "needsToolCallingByDefault": true,
-        "preferredFrontierModels": [],
-        "localFirst": true
+      "scribe": {
+        "executionMode": "local",
+        "model": { "providerID": "ollama", "modelID": "qwen3:8b" }
+      },
+      "integration": {
+        "executionMode": "frontier",
+        "model": { "providerID": "anthropic", "modelID": "claude-sonnet-4-5" },
+        "fallbacks": [
+          { "providerID": "google", "modelID": "gemini-3.5-flash" }
+        ]
       }
     }
   }
 }
 ```
 
+The resolved `routeKind` is always concrete `local`, `frontier`, or `blocked`,
+never `mixed`. Only the selected model and returned fallback chain may execute.
+A blocked decision does not dispatch; its selected identity is a cost/reference
+value only. Budget narrowing cannot substitute an unapproved local model: if no
+authorized candidate remains, routing blocks.
+
 ## Usage
 
-On each turn, openteam derives signals from the prompt (`promptChars`, `hasCode`, `privacySensitive`, `requiresTools` and a model override if present), runs `chooseModel` and assigns `output.message.model`.
+On each turn, openteam resolves the global and agent execution policy, filters
+available models by domain, tool support and context, ranks `"auto"` candidates
+by cost against the unified router's capability/complexity requirements, and
+assigns `output.message.model`. Prompt sensitivity and Graph privacy metadata
+are not routing inputs.
 
 Multi-agent orchestration uses static roles and opencode subsessions:
 
-| Role | opencode agent | Base tier | Policy |
-| --- | --- | --- | --- |
-| `rusty` | `architect` | `hard` | Architecture and high-risk decisions; frontier auto. |
-| `livingston` | `integration` | `moderate` | TS/opencode integration; tool calling by default. |
-| `yen` | `local-runtime` | `moderate` | Local runtimes; local-first with frontier fallback. |
-| `basher` | `routing-cost` | `moderate` | Router, cost and budget; local-first. |
-| `scribe` | `scribe` | `trivial` | Documentation and summaries; local-first. |
-| `linus` | `tester` | `simple` | Tests and contracts; local-first with tools. |
+For coordinator-owned work, the role's `defaultTier` and capability minima are
+floors. Ordinary task capability/complexity classification may raise the
+effective requirement for harder work, but it cannot weaken the role
+requirement. The effective tier drives routing and telemetry. Sensitivity
+vocabulary and Graph privacy metadata have no routing effect.
 
-`runRoleTask` runs a single subsession; `runRoleTasks` runs several with a `batchID`. Roles with `destructive` or `multiFileEdit` elevate the tier before choosing a model.
-
-To see savings and decisions, read the telemetry JSONL. Key fields: `promptHash`, `promptChars`, `tier`, `routeKind`, `selected`, `rationale`, `estimatedCostUSD`, `baselineCostUSD`, `estimatedSavingsUSD`, `budgetAction`, `tokensIn` and `tokensOut`.
+| Role | opencode agent | Typical policy |
+| --- | --- | --- | --- |
+| `rusty` | `architect` | Configure `"auto"` or an exact in-domain model. |
+| `livingston` | `integration` | Usually requires tool support; domain is explicit. |
+| `yen` | `local-runtime` | May be narrowed to `local` under global `mixed`. |
+| `basher` | `routing-cost` | Auto selection may optimize cost inside the domain. |
+| `scribe` | `scribe` | No built-in local restriction; set one explicitly if required. |
+| `linus` | `tester` | Configure models with the required tools/context. |
+
+`runRoleTask` runs a single subsession; `runRoleTasks` runs several with a
+`batchID`. Direct and batched attempts use the same stable logical report path
+and must prove a current, changed-when-required, substantive durable report
+before success. Permission and review policy remain separate from model
+placement.
+
+SDK child dispatch uses a plugin-scoped, one-shot model authorization keyed by
+the exact child session, agent alias, and model. When the public SDK prompt
+re-enters `chat.message`, only that matching claim preserves the
+coordinator-authorized worker model; the authorization is released when the
+prompt settles. Unmatched and user-initiated messages still follow normal
+routing. This mechanism cannot broaden an execution domain or authorize a
+model outside `selected` plus `fallbackChain`.
+
+To inspect actual model use, handoff reasons, and cost/savings estimates when
+available, read the telemetry JSONL. Key fields include `promptHash`,
+`promptChars`, `routeKind`, `selected`, `rationale`, `estimatedCostUSD`,
+`baselineCostUSD`, `estimatedSavingsUSD`, `budgetAction`, `tokensIn`, and
+`tokensOut`. Unknown model costs remain `null`/unknown rather than becoming
+free; savings are unknown when either required estimate is unavailable. For
+coordinator auto routing, the effective capability requirement—the role floor
+plus any upward task classification—determines both candidate capability and
+the capable frontier baseline used for cost comparison.
 
 ## Runtime commands
 
@@ -392,8 +480,9 @@ The plugin registers the `openteam` tool. Ask the agent to use it, or install th
 - `show` — show the effective baseline.
 - `set` (with `model` as `provider/model`) — pin the baseline (`pinned` mode).
 - `auto` — return to cheapest-capable (`auto` mode).
-- `doctor` — diagnostics for local runtimes, privacy and telemetry.
-- `report` — cost and savings summary from telemetry.
+- `doctor` — diagnostics for execution policy, model availability, and telemetry.
+- `report` — available cost and savings estimates from telemetry; unknown
+  values remain unknown.
 
 `set` / `auto` changes are persisted to `.opencode/openteam.json` and apply on the next plugin start.
 
@@ -420,7 +509,7 @@ The package exposes the `openteam` binary. With a global install:
 ```powershell
 bun add --global @jmanuelcorral/openteam@latest
 openteam baseline show
-openteam baseline set openai/gpt-5-mini
+openteam baseline set anthropic/claude-sonnet-4-5
 openteam doctor --config .opencode/openteam.json
 openteam agents
 openteam console
@@ -438,7 +527,11 @@ Flags: `--config <path>` and `--telemetry <path>` override the default paths; `-
 
 ### See each agent's LLM: `openteam agents`
 
-Lists the agents in `.opencode/agent/`, showing **which LLM each one uses**: whether it is **local** (Ollama/LM Studio/Lemonade/Foundry, no token cost) or **frontier** (consumes your subscription), and the provider. Agents without their own `model` **inherit** the `opencode.json` default (which openteam routes local-first per message).
+Lists the agents in `.opencode/agent/`, showing their configured model and
+provider. Agents without their own `model` inherit the `opencode.json` default.
+That inherited/default model is not permission to escape the resolved
+execution domain; effective primary/role policies in `.opencode/openteam.json`
+remain authoritative.
 
 ### YOLO mode (auto-approve permissions)
 
@@ -452,27 +545,32 @@ openteam yolo off      # disable YOLO
 
 > **The agent permission overrides the global one.** opencode merges each agent's frontmatter permission **after** the global one and the last matching rule wins, so `openteam yolo on/off` regenerates `.opencode/agent/openteam.md` to keep its `permission` in sync. After changing mode, **restart or reload opencode**.
 
-> **YOLO does not disable openteam privacy.** It only affects opencode permission approvals; with `privacyMode: "forceLocalOnSensitive"`, sensitive prompts still never leave for frontier. Use it only in trusted environments.
+> **YOLO does not change the execution domain.** It only affects opencode
+> permission approvals, and it does not add a sensitivity screen. In
+> `frontier` or `mixed`, prompt content may be sent to frontier. Use it only in
+> trusted environments.
 
 ### Routing mode: `openteam local`
 
-Use `openteam local` to switch between the three global routing modes without
+Use `openteam local` to switch between the three global execution domains without
 re-running setup:
 
 ```powershell
-openteam local status   # local-first, local-only, or frontier-only? + configured runtimes
-openteam local off      # frontier-only (disable local-first routing)
+openteam local status   # mixed, local, or frontier? + configured runtimes
+openteam local off      # frontier
 openteam local only     # local-only (never escalate to frontier)
-openteam local on       # back to local-first routing
+openteam local on       # mixed
 ```
 
-`local off` persists `router.frontierOnly=true`: the router picks the
-**cheapest-capable frontier**, but still respects privacy, budgets and explicit
-per-task overrides. Sensitive prompts with `forceLocalOnSensitive` don't leave
-for frontier; `local off` degrades that policy to `consentBeforeFrontier` (local
-can't be forced without a runtime) and tells you about the change. `local only`
-persists `router.localOnly=true` and clears `frontierOnly`; it refuses to write
-the config unless at least one local runtime is enabled.
+The commands persist `router.executionMode`. `local only` is a hard upper
+bound: no primary/worker pin or fallback can reach frontier, and the command is
+rejected without an enabled local runtime. `local off` needs no local runtime.
+`local on` allows both domains, and each agent may narrow itself to one of them.
+Before any mode change is written, exact primary, role, and fallback policies
+are validated against the proposed domain; a conflict rejects the command and
+leaves config unchanged.
+Every write removes legacy `localOnly`, `frontierOnly`, and root `privacyMode`;
+`local status` shows the effective mode and enabled runtime identities.
 
 ### Updating the plugin and clearing the cache: `openteam clear-cache`
 
@@ -500,13 +598,57 @@ explanation of the freeze mechanism and a step-by-step update procedure.
 
 ### Iterative work under `openteam-orchestrate` 🎯
 
-Unattended, backlog-style work is driven **entirely from orchestration** — iteration is a property of the graph, not a separate command. When the coordinator dispatches a role, that graph node keeps working across successive passes until it declares `openteam-status: done` in its report artifact (the **output contract**) or it reaches its retry bound. The bound is configurable via `orchestrator.maxRetries` in `.opencode/openteam.json`: it counts retries, so the default `2` means **three passes per node** and `0` disables iteration (a single pass). A node that never declares completion is re-dispatched up to the bound rather than assumed finished, and a **durability gate** verifies in code that each role actually persisted a non-empty report — so no pass silently discards work. Wave-level concurrency and dependency cancellation are unchanged. See **[docs/guide/commands.md](docs/guide/commands.md)** for the full contract.
+Unattended, backlog-style work is driven entirely from orchestration. The
+current model gets `orchestrator.maxRetries` extra passes (effective runtime
+default `2`, so up to three passes per model). Persistent incompleteness uses
+that model's pass budget before handing the **same node** to the next authorized
+model. A recognized retry-safe prompt transport/capacity failure
+(`prompt-timeout`, `prompt-rate-limited`, `prompt-connection`,
+`prompt-server`, or `prompt-context-length`) is retried on that same model
+within its pass allowance; create-stage retry recognizes the same transport
+classes except context length. `maxRetries` is an upper bound, not a required
+repeat floor: after confirmed stop, an eligible transport failure may consume
+the remaining same-model allowance or hand off earlier to the next authorized
+candidate. Auth,
+content-filter, validation/invalid-model, generic rejection, and missing-session
+or unclassified failures are terminal. A candidate found unavailable before
+dispatch may be skipped because no attempt started. `maxModelsPerNode` has the
+effective runtime default `2`; together the defaults cap a node at up to six
+openteam passes. Neither default is materialized by the schema. This is not a
+guaranteed pass/HTTP-call count or a statement about provider-internal SDK
+retries.
+The batch, objective, report path, and durable work state are preserved. An
+exact pin without `fallbacks` authorizes no second model.
+
+Every pass, including a single pass with `maxRetries: 0`, needs a standalone
+`openteam-status: done` declaration **and** a durable report with at least 40
+substantive body characters after actual declaration lines are removed. The
+last standalone declaration outside fenced code wins; quoted or fenced examples
+remain body text and cannot declare completion. A marker alone is not
+completion. The coordinator reads the report text only to parse that status and
+test substance; it does not copy the body into role results, routing telemetry,
+diagnostics, or the reference-only projection.
+
+After a timed-out or otherwise thrown/uncertain prompt dispatch, the prior SDK
+request must settle and server stop must be confirmed before any same-model
+retry or model handoff. After a successful abort, bounded polling confirms stop
+when the exact session is `idle` or is absent from a valid sparse status
+snapshot; malformed/missing status payloads and sessions that remain `busy` or
+`retry` block continuation. Status evidence alone does not replace request
+settlement. Exhaustion is terminal failure/incomplete, and dependents do not
+run. See
+**[docs/guide/commands.md](docs/guide/commands.md)**.
 
 ### Multi-session web Console: `openteam console`
 
 openteam exposes a **local web Console** you launch from the CLI with `openteam console`. It aggregates **all** opencode sessions at once (one tab per session, plus "All"), because each plugin **writes redacted events** to per-session JSONL logs that the Console watches (`fs.watch`) and aggregates.
 
-It shows live: **real cost and tokens per message** (input/output/reasoning/cache), **tool calls with duration** and ok/fail, recent routing (cost/savings and chosen model — **prompt hashes only, never text**), agent **decisions** (scribe) and **meetings** (multi-agent batches), orchestration and iteration progress, the agent team and latest commits. It updates over **SSE** (with polling fallback).
+It shows live: **recorded token usage and cost estimates per message**
+(input/output/reasoning/cache), **tool calls with duration** and ok/fail, recent
+routing (cost/savings and chosen model — **prompt hashes only, never text**),
+agent decisions and meetings, orchestration progress, the team, and commits.
+These controls and estimates are finite/auditable, but they are not provider
+invoice accounting.
 
 Each session tab also includes a **"Session" view**: a console where you can **watch the live output** (SSE) and **send prompts** or **answer permissions** for that opencode session, authenticated with an **ephemeral token** per launch. Optionally, with the `terminal.pty` flag, a **"Terminal" view** opens a **real shell** in the workspace via opencode's PTY API (no `node-pty`).
 
@@ -541,7 +683,11 @@ block):
 }
 ```
 
-**Live agent-graph view.** The Console can also render a live **agent graph** of a Graph run; it is **on by default in shadow mode** and can be hidden with `console.graphView.enabled: false` — see [Graph observability web](docs/guide/graph-observability-web.md) for setup and the full requirements.
+**Agent tree and timeline.** `console.graphView.enabled` defaults to `true`.
+Native lifecycle history is composed independently of Graph execution
+authority; the separate Graph DAG follows the effective `graph.mode`. See
+[Agent timeline](docs/guide/agent-timeline.md) and
+[Graph observability web](docs/guide/graph-observability-web.md).
 
 > **Security**: the server listens **on loopback only** (`127.0.0.1`/`localhost`, Zod-validated) and **never exposes prompts** (only `promptHash`), tool-call args or message content — only counters, costs and redacted summaries. The "Session"/"Terminal" view requires the ephemeral token. If the port is busy and `autoPortFallback` is `true`, it tries the next free one. Remote access via `openteam tunnel` was **removed from the MVP** (2026-08-31) and will be redefined later; the Console has no built-in remote-exposure path.
 
@@ -549,7 +695,7 @@ block):
 
 ### Team memory over MCP (read-only): `openteam mcp`
 
-`openteam mcp` starts a **read-only MCP server** (JSON-RPC 2.0 over stdio, no dependencies) that exposes the team memory aggregated from per-session events. It uses the same `StorageProvider` as the Console and **never** exposes raw prompts. Tools: `list_decisions` (filterable by `agent`/`tag`), `list_meetings`, `list_sessions` and `cost_summary` (real cost/tokens + estimated savings vs the all-frontier baseline).
+`openteam mcp` starts a **read-only MCP server** (JSON-RPC 2.0 over stdio, no dependencies) that exposes the team memory aggregated from per-session events. It uses the same `StorageProvider` as the Console and **never** exposes raw prompts. Tools: `list_decisions` (filterable by `agent`/`tag`), `list_meetings`, `list_sessions` and `cost_summary` (recorded usage and available cost/savings estimates against the all-frontier baseline, with unknown costs retained as unknown; not an invoice).
 
 Register it in `opencode.json` like any local MCP server:
 
@@ -561,6 +707,12 @@ Register it in `opencode.json` like any local MCP server:
 }
 ```
 
+The plugin's **`openteam-memory` write tool** is separate from this read-only
+MCP server and from the general scribe role's model policy. Its extraction
+transport is explicitly local-only and requires a reachable configured local
+runtime. Global `frontier` execution refuses the memory-model call; the tool
+does not add a frontier memory path or silently fall back to frontier.
+
 #### Semantic recall (opt-in): `recall_facts`, `recall_preferences`, `similar_tasks`
 
 Beyond team memory, `openteam mcp` can expose **semantic recall** of the long-term knowledge memory (facts, preferences, similar tasks). It is **disabled by default**; enable it with the `memory.semantic` block in `.opencode/openteam.json`:
@@ -692,16 +844,24 @@ and remove its inherited GitHub Actions secret.
 
 ## Privacy
 
-With `privacyMode: "forceLocalOnSensitive"`, if `TaskSignals.privacySensitive` is `true`, `chooseModel` uses local and does not allow frontier fallback. If no usable local runtime exists, the decision keeps the local route and records the reason in `rationale`.
+openteam does **not** detect prompt sensitivity or promise to intercept sensitive
+content before a frontier call. `privacyMode` is deprecated and has no routing
+authority. `frontier` and `mixed` deliberately permit frontier egress under the
+configured agent policy. To prohibit it, configure
+`router.executionMode: "local"` globally, or narrow the relevant agent to
+`local` under global `mixed`.
 
-Telemetry uses `hashPrompt` (currently `fnv1a32:<hash>`) and never serializes the full prompt. See [SECURITY.md](SECURITY.md) for the full privacy stance and how to report vulnerabilities.
+Credential redaction, prompt-hash telemetry, reference-only shared storage,
+loopback/access controls, and finite budget/model/pass limits remain in force.
+Telemetry uses `hashPrompt` (currently `fnv1a32:<hash>`) and never serializes the
+full prompt. See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 
 ## Quality
 
 Non-negotiable gates (see [docs/testing-and-quality.md](docs/testing-and-quality.md)):
 
 - `bun test`
-- Global coverage: lines `>= 85%`, branches `>= 80%`.
+- Global coverage: lines/functions `>= 85%`.
 - Coverage of `src/router/**` and `src/memory/**`: `100%` lines and functions (enforced by `bun run coverage:check`).
 - `bun run typecheck`
 - `biome check .` (or `bun run lint` + `bun run format:check`)
@@ -714,7 +874,7 @@ See [docs/compatibility.md](docs/compatibility.md). Verified summary as of `2026
 
 | Surface | Version / contract |
 | --- | --- |
-| openteam | `0.18.1`; current package version |
+| openteam | `0.20.0`; current package version |
 | `@opencode-ai/plugin` | `1.18.19` |
 | `@opencode-ai/sdk` | `1.18.19` |
 | Routing hook | `chat.message`; not `chat.params` for model changes |
@@ -729,12 +889,13 @@ Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for th
 | Phase | Status | Deliverables |
 | --- | --- | --- |
 | 0. Scaffold / PoC | Done | TS/Bun, minimal plugin, `chat.message` hook. |
-| 1. Local registry + heuristic router | Done | Ollama/LM Studio/Lemonade/Foundry, probes and deterministic `chooseModel`. |
-| 2. Classifier + profiles + budget + telemetry | Done | Local classifier, `ModelCapabilityProfile`, budgets and `CostRecord`. |
+| 1. Local registry + router | Done | Ollama/LM Studio/Lemonade/Foundry, probes and deterministic `chooseModel`. |
+| 2. Profiles + budget + telemetry | Done | `ModelCapabilityProfile`, budgets and `CostRecord`. |
 | 3. Multi-agent orchestration | Done | Coordinator, roles, child sessions and permissions. |
 | 4. npm packaging + docs | Done | Exportable package, README, Windows examples and compatibility matrix. |
 | 5. Runtime commands | Done | `baseline show/set/auto`, `doctor` and `report` via tool, `/openteam` and CLI `bin`. |
 | 6. Web Console + MCP memory | Done | The multi-session Console is loopback-only and gate-covered; read-only MCP server and semantic recall are stable. |
+| Agent-stack MVP | In progress | Config v2 execution domains, per-agent model policies, bounded model handoff, removal of sensitivity routing, and retirement of duplicate Graph-local policy resolution. Unified router capability/complexity routing remains. LangGraph migration issues remain separate and pending. |
 
 ## License