coding-os 0.3.8__tar.gz → 0.3.9__tar.gz

{coding_os-0.3.8 → coding_os-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-os
-Version: 0.3.8
+Version: 0.3.9
 Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
 Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
 License-Expression: Apache-2.0
@@ -474,6 +474,31 @@ Deep dive: [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-qu
 Parity matrix + reasoning: [docs/engineering/adapter-parity.md](./docs/engineering/adapter-parity.md)
 (the 2026-04-25 workflow audit is a historical snapshot predating Codex parity).
 
+## Agent supervision — pick the model per role (opt-in)
+
+Off by default. Turn it on and each of the 11 semantic roles can run on its own
+adapter, model, and reasoning effort — a cheap model reviewing, an expensive one
+architecting. It works with a **single** adapter too: routing across Claude's own
+model tiers is the common case, not a fallback.
+
+```bash
+cos supervision enable
+cos supervision set --orchestrator-model claude-sonnet-5     # project default
+cos supervision set --role reviewer  --role-model claude-haiku-4-5 --role-effort low
+cos supervision set --role architect --role-model claude-opus-4-8  --role-effort xhigh
+cos supervision show
+```
+
+Adapters and their model catalogs are discovered from `adapter.yaml`, so a new
+runtime is configurable the day it is installed. When a provider reports a rate
+or capacity limit, that adapter is put on a persistent cooldown with a single
+half-open recovery probe instead of retry-storming a limit that cannot succeed.
+Same policy from the Hub (**Config → Settings**), the CLI, or MCP — no Hub
+required. Disabled means disabled: no probe, no state write, no tokens.
+
+Full contract: [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)
+· operator guide: [docs/playbooks/agent-supervision-setup.md](./docs/playbooks/agent-supervision-setup.md)
+
 ## Configuration
 
 `.coding-os.yaml` at every project root:
@@ -526,6 +551,7 @@ CI runs the matrix on every PR. See `.github/workflows/ci.yml`.
 | [docs/governance/agent-workflow.md](./docs/governance/agent-workflow.md)            | Domain routing, task protocol, memory contract              |
 | [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-queries.md)      | When to query the graph vs grep                             |
 | [docs/engineering/hub-architecture.md](./docs/engineering/hub-architecture.md)      | Hub: FastAPI ↔ React SPA contract                           |
+| [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)    | Per-role adapter/model routing, capacity breaker, trigger modes |
 | [docs/playbooks/](./docs/playbooks/)                                                | Hook authoring · adapter authoring · template authoring · MCP tool authoring |
 | [docs/adapters/](./docs/adapters/)                                                  | Claude SDK · Codex CLI integration                          |
 | [CONTRIBUTING.md](./CONTRIBUTING.md)                                                | Setup, contribution loop, PR checklist                      |

{coding_os-0.3.8 → coding_os-0.3.9}/README.md

@@ -408,6 +408,31 @@ Deep dive: [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-qu
 Parity matrix + reasoning: [docs/engineering/adapter-parity.md](./docs/engineering/adapter-parity.md)
 (the 2026-04-25 workflow audit is a historical snapshot predating Codex parity).
 
+## Agent supervision — pick the model per role (opt-in)
+
+Off by default. Turn it on and each of the 11 semantic roles can run on its own
+adapter, model, and reasoning effort — a cheap model reviewing, an expensive one
+architecting. It works with a **single** adapter too: routing across Claude's own
+model tiers is the common case, not a fallback.
+
+```bash
+cos supervision enable
+cos supervision set --orchestrator-model claude-sonnet-5     # project default
+cos supervision set --role reviewer  --role-model claude-haiku-4-5 --role-effort low
+cos supervision set --role architect --role-model claude-opus-4-8  --role-effort xhigh
+cos supervision show
+```
+
+Adapters and their model catalogs are discovered from `adapter.yaml`, so a new
+runtime is configurable the day it is installed. When a provider reports a rate
+or capacity limit, that adapter is put on a persistent cooldown with a single
+half-open recovery probe instead of retry-storming a limit that cannot succeed.
+Same policy from the Hub (**Config → Settings**), the CLI, or MCP — no Hub
+required. Disabled means disabled: no probe, no state write, no tokens.
+
+Full contract: [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)
+· operator guide: [docs/playbooks/agent-supervision-setup.md](./docs/playbooks/agent-supervision-setup.md)
+
 ## Configuration
 
 `.coding-os.yaml` at every project root:
@@ -460,6 +485,7 @@ CI runs the matrix on every PR. See `.github/workflows/ci.yml`.
 | [docs/governance/agent-workflow.md](./docs/governance/agent-workflow.md)            | Domain routing, task protocol, memory contract              |
 | [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-queries.md)      | When to query the graph vs grep                             |
 | [docs/engineering/hub-architecture.md](./docs/engineering/hub-architecture.md)      | Hub: FastAPI ↔ React SPA contract                           |
+| [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)    | Per-role adapter/model routing, capacity breaker, trigger modes |
 | [docs/playbooks/](./docs/playbooks/)                                                | Hook authoring · adapter authoring · template authoring · MCP tool authoring |
 | [docs/adapters/](./docs/adapters/)                                                  | Claude SDK · Codex CLI integration                          |
 | [CONTRIBUTING.md](./CONTRIBUTING.md)                                                | Setup, contribution loop, PR checklist                      |

{coding_os-0.3.8 → coding_os-0.3.9}/coding_os.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-os
-Version: 0.3.8
+Version: 0.3.9
 Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
 Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
 License-Expression: Apache-2.0
@@ -474,6 +474,31 @@ Deep dive: [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-qu
 Parity matrix + reasoning: [docs/engineering/adapter-parity.md](./docs/engineering/adapter-parity.md)
 (the 2026-04-25 workflow audit is a historical snapshot predating Codex parity).
 
+## Agent supervision — pick the model per role (opt-in)
+
+Off by default. Turn it on and each of the 11 semantic roles can run on its own
+adapter, model, and reasoning effort — a cheap model reviewing, an expensive one
+architecting. It works with a **single** adapter too: routing across Claude's own
+model tiers is the common case, not a fallback.
+
+```bash
+cos supervision enable
+cos supervision set --orchestrator-model claude-sonnet-5     # project default
+cos supervision set --role reviewer  --role-model claude-haiku-4-5 --role-effort low
+cos supervision set --role architect --role-model claude-opus-4-8  --role-effort xhigh
+cos supervision show
+```
+
+Adapters and their model catalogs are discovered from `adapter.yaml`, so a new
+runtime is configurable the day it is installed. When a provider reports a rate
+or capacity limit, that adapter is put on a persistent cooldown with a single
+half-open recovery probe instead of retry-storming a limit that cannot succeed.
+Same policy from the Hub (**Config → Settings**), the CLI, or MCP — no Hub
+required. Disabled means disabled: no probe, no state write, no tokens.
+
+Full contract: [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)
+· operator guide: [docs/playbooks/agent-supervision-setup.md](./docs/playbooks/agent-supervision-setup.md)
+
 ## Configuration
 
 `.coding-os.yaml` at every project root:
@@ -526,6 +551,7 @@ CI runs the matrix on every PR. See `.github/workflows/ci.yml`.
 | [docs/governance/agent-workflow.md](./docs/governance/agent-workflow.md)            | Domain routing, task protocol, memory contract              |
 | [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-queries.md)      | When to query the graph vs grep                             |
 | [docs/engineering/hub-architecture.md](./docs/engineering/hub-architecture.md)      | Hub: FastAPI ↔ React SPA contract                           |
+| [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)    | Per-role adapter/model routing, capacity breaker, trigger modes |
 | [docs/playbooks/](./docs/playbooks/)                                                | Hook authoring · adapter authoring · template authoring · MCP tool authoring |
 | [docs/adapters/](./docs/adapters/)                                                  | Claude SDK · Codex CLI integration                          |
 | [CONTRIBUTING.md](./CONTRIBUTING.md)                                                | Setup, contribution loop, PR checklist                      |

{coding_os-0.3.8 → coding_os-0.3.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "coding-os"
-version = "0.3.8"
+version = "0.3.9"
 description = "The cognitive operating system that gives AI agents memory, structure, and discipline"
 readme = "README.md"
 requires-python = ">=3.10"

{coding_os-0.3.8 → coding_os-0.3.9}/src/adapters/claude/adapter.yaml

@@ -8,16 +8,24 @@ runtime: in_process
 runtime_entrypoints:
   dispatch: sdk_dispatcher.py
   capabilities: [dispatch, model_selection, effort_selection, structured_output]
+# `bucket` names the provider's rate-limit pool. Anthropic applies limits
+# separately per model, and Opus 4.x share one pool while Opus 5 has its own
+# (docs.claude.com/en/api/rate-limits) — so a limit on one bucket must not
+# take the others out of service.
 models:
   - id: claude-fable-5
     label: "Fable 5"
+    bucket: fable-5
   - id: claude-opus-4-8
     label: "Opus 4.8"
     default: true
+    bucket: opus-4x
   - id: claude-sonnet-5
     label: "Sonnet 5"
+    bucket: sonnet-5
   - id: claude-haiku-4-5
     label: "Haiku 4.5"
+    bucket: haiku-4-5
 # Reasoning-effort levels the Claude Agent SDK accepts (EffortLevel) — shown in
 # the Hub chat composer so a turn can be weighted per adapter.
 efforts: [low, medium, high, xhigh, max]

{coding_os-0.3.8 → coding_os-0.3.9}/src/adapters/claude/sdk_dispatcher.py

@@ -95,6 +95,11 @@ def _failure_fields(status: str, error: str | None) -> dict[str, Any]:
         for token in ("unauthorized", "authentication", "not logged in", "401", "403")
     ):
         return {"error_category": "auth", "outcome": "known_failed"}
+    # Provider-side overload (529) and internal errors (5xx) are NOT your quota,
+    # so they must not open the capacity breaker — but they are the most
+    # retryable class there is, and reporting them non-retryable is wrong.
+    if any(token in message for token in ("overloaded", "529", "api_error", "500", "502", "503")):
+        return {"error_category": "provider", "retryable": True, "outcome": "unknown"}
     if any(token in message for token in ("not importable", "not found")):
         return {"error_category": "unavailable", "outcome": "known_failed"}
     if any(token in message for token in ("must be absolute", "max_budget_usd", "max_turns")):

{coding_os-0.3.8 → coding_os-0.3.9}/src/adapters/codex/adapter.yaml

@@ -9,7 +9,7 @@ runtime: roadmap
 runtime_entrypoints:
   dispatch: sdk_dispatcher.py
   transcript: chat_provider.py
-  capabilities: [dispatch, model_selection, structured_output]
+  capabilities: [dispatch, transcript, model_selection, structured_output]
 models: []
 
 presence:

{coding_os-0.3.8 → coding_os-0.3.9}/src/adapters/codex/sdk_dispatcher.py

@@ -50,6 +50,11 @@ def _failure_fields(status: str, error: str | None) -> dict[str, Any]:
         for token in ("unauthorized", "authentication", "not logged in", "401", "403")
     ):
         return {"error_category": "auth", "outcome": "known_failed"}
+    # Provider-side overload (529) and internal errors (5xx) are NOT your quota,
+    # so they must not open the capacity breaker — but they are the most
+    # retryable class there is, and reporting them non-retryable is wrong.
+    if any(token in message for token in ("overloaded", "529", "api_error", "500", "502", "503")):
+        return {"error_category": "provider", "retryable": True, "outcome": "unknown"}
     if any(token in message for token in ("not in path", "not importable", "unsupported")):
         return {"error_category": "unavailable", "outcome": "known_failed"}
     if any(token in message for token in ("must be absolute", "cannot enforce", "invalid")):

{coding_os-0.3.8 → coding_os-0.3.9}/src/cli/supervision_commands.py

@@ -178,6 +178,12 @@ def supervision_set(
     }
     if (role_values or clear_role) and not role:
         raise click.UsageError("--role is required with role options or --clear-role")
+    if clear_role and role_values:
+        raise click.UsageError("--clear-role cannot be combined with --role-adapter/model/effort")
+    if orchestrator and clear_orchestrator:
+        raise click.UsageError(
+            "--clear-orchestrator cannot be combined with --orchestrator-adapter/model/effort"
+        )
     if role_values and role:
         patch["roles"] = {role: role_values}
     if not patch and not clear_role and not clear_orchestrator:

{coding_os-0.3.8 → coding_os-0.3.9}/src/cli/update.py

@@ -161,10 +161,21 @@ def _build_target_assets(agent: str, templates: list[str]) -> dict[str, list[Ass
         "commands": [],
     }
 
-    # Hooks — always use src/core/hooks/ regardless of agent (path may differ).
+    # Hooks — the agent-agnostic core set, PLUS the adapter's own hooks. Omitting
+    # the adapter-owned ones made them look unknown to the diff, so `cos update`
+    # deleted them: for Codex that is every dispatcher, i.e. its whole hook
+    # parity mechanism. Helper .py files sit beside the .sh and link the same way.
     hooks_dir_rel = adapter.hooks_dir
     if hooks_dir_rel:
-        for hook in sorted((CORE_DIR / "hooks").glob("*.sh")):
+        sources = [*sorted((CORE_DIR / "hooks").glob("*.sh"))]
+        adapter_hooks = ADAPTERS_DIR / agent / "hooks"
+        if adapter_hooks.is_dir():
+            sources += sorted(
+                path
+                for path in adapter_hooks.iterdir()
+                if path.is_file() and path.suffix in (".sh", ".py")
+            )
+        for hook in sources:
             result["hooks"].append(
                 AssetRef(
                     name=hook.name,

{coding_os-0.3.8 → coding_os-0.3.9}/src/core/board_os/transition_gates_cli.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import logging
 import os
 import sqlite3
 import sys
@@ -18,6 +19,8 @@ from board_os.transition_gates_validator import (
     validate_transition,
 )
 
+logger = logging.getLogger("coding_os.board_os.gates")
+
 
 def _read_stdin_payload() -> dict:
     """Read the hook payload from stdin (≤2 s timeout matches our hooks)."""
@@ -73,6 +76,19 @@ def _load_body_for_task(task_id: str, file_path: Path | None) -> tuple[str, str]
     return "", str(row[1] or "feature")
 
 
+def _verify_ledger_path() -> Path | None:
+    state_dir = Path(os.environ.get("COS_STATE_DIR", ".coding-os"))
+    if state_dir.is_absolute():
+        return state_dir / ".last-verify.json"
+    try:
+        from thinking_os.database import project_root  # type: ignore
+
+        return project_root() / state_dir / ".last-verify.json"
+    except Exception as exc:
+        logger.debug("project-root ledger resolution unavailable: %s", exc)
+        return state_dir / ".last-verify.json"
+
+
 def _verify_state() -> tuple[bool, int | None]:
     """Most-recent PASS in .last-verify.json (freshness gate, not a forge wall).
 
@@ -84,9 +100,12 @@ def _verify_state() -> tuple[bool, int | None]:
     it catches the FORGOTTEN run, not a deliberate forge. The real wall is the
     server-side required CI check in pr-mode, not this local marker. (TASK-620)
     """
-    state_dir = os.environ.get("COS_STATE_DIR", ".coding-os")
-    path = Path(state_dir) / ".last-verify.json"
-    if not path.exists():
+    # COS_STATE_DIR is routinely a RELATIVE path, so resolving it against the
+    # gate process's cwd read a different file than the verify runners wrote —
+    # the MCP/board process does not share the agent's working directory. Anchor
+    # it to the project root, the same way every other kernel path is resolved.
+    path = _verify_ledger_path()
+    if path is None or not path.exists():
         return False, None
     try:
         data = json.loads(path.read_text(encoding="utf-8"))

{coding_os-0.3.8 → coding_os-0.3.9}/src/core/rules/model-routing.md

@@ -7,10 +7,10 @@ CLI and desktop sessions receive the same project policy through the once-per-se
 ## The contract
 
 1. **Toggle off (default)** — nothing fires; dispatch behaviour is unchanged.
-2. **Explicit** — dispatch only when the operator or active procedure requests a child run.
-3. **Suggest** — propose the adapter/model/role route and wait for operator approval.
-4. **Adaptive** — after classification, supervise work at or above the configured complexity threshold.
-5. **Dispatch** — explicit request fields override per-role policy, then preset and role defaults. Every parallel role resolves its own adapter.
+2. **Explicit** (default mode) — the configured policy always applies; what is configured is what runs.
+3. **Suggest** — resolve the route and return `status="skipped"` with `proposed_route`, executing nothing. A dry run, not an approval prompt.
+4. **Adaptive** — apply the policy only at or above the configured complexity threshold; pass the gate level to the run tools, or the request stays unclassified and below every gate.
+5. **Dispatch** — explicit request fields override per-role policy, which overrides the project orchestrator default, then preset and role defaults. Every parallel role resolves its own adapter. The capacity breaker is never gated by trigger mode.
 6. **Capacity** — a normalized usage-limit failure pauses only that adapter. The dispatcher uses an eligible fallback only when the failed run is known not to have started; timeout or unknown outcomes are never replayed.
 7. **Recovery** — after cooldown, one half-open probe is allowed. Success restores normal routing; another capacity failure extends cooldown.
 

{coding_os-0.3.8 → coding_os-0.3.9}/src/core/schemas/adapter.schema.json

@@ -251,7 +251,7 @@
     },
     "models": {
       "type": "array",
-      "description": "Chat models this adapter offers, grouped under the adapter in the Hub chat model picker. Empty for roadmap adapters (no fabricated IDs — P7).",
+      "description": "Model catalog this adapter offers — drives the Hub pickers and supervision write-time validation. Empty means either a roadmap adapter or a runtime that forwards any model string; core never fabricates IDs (P7), so an empty catalog accepts any non-empty string and the Hub renders a free-text field.",
       "items": {
         "type": "object",
         "required": ["id"],
@@ -259,7 +259,8 @@
         "properties": {
           "id": {"type": "string", "minLength": 1, "description": "Model identifier passed to the agent runtime."},
           "label": {"type": "string", "description": "Human-facing model name shown in the picker."},
-          "default": {"type": "boolean", "description": "Whether this is the adapter's default model. At most one per adapter."}
+          "default": {"type": "boolean", "description": "Whether this is the adapter's default model. At most one per adapter."},
+          "bucket": {"type": "string", "minLength": 1, "description": "Provider rate-limit pool this model draws from. Models sharing a pool share one capacity cooldown; models in different pools stay independent when one is limited. Absent = the adapter is treated as a single pool."}
         }
       }
     },

{coding_os-0.3.8 → coding_os-0.3.9}/src/core/thinking_os/adapter_registry.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import importlib.util
 import logging
+import os
 from dataclasses import dataclass
 from pathlib import Path
 from types import ModuleType
@@ -13,14 +14,16 @@ logger = logging.getLogger("coding_os.adapter_registry")
 
 
 def _resolve_adapters_dir(module_path: Path) -> Path:
+    # COS_CODING_OS_ROOT wins: a consumer project points at the coding-os
+    # checkout that owns src/adapters, which is not a parent of this module.
+    configured = os.environ.get("COS_CODING_OS_ROOT", "").strip()
+    default = module_path.resolve().parents[2] / "adapters"
     candidates = (
-        module_path.resolve().parents[2] / "adapters",
+        *((Path(configured).resolve() / "src" / "adapters",) if configured else ()),
+        default,
         module_path.resolve().parents[1] / "adapters",
     )
-    return next((candidate for candidate in candidates if candidate.is_dir()), candidates[0])
-
-
-ADAPTERS_DIR = _resolve_adapters_dir(Path(__file__))
+    return next((candidate for candidate in candidates if candidate.is_dir()), default)
 
 
 @dataclass(frozen=True)
@@ -51,7 +54,7 @@ class AdapterRecord:
 
 
 def load_adapter_records(adapters_dir: Path | None = None) -> dict[str, AdapterRecord]:
-    root = adapters_dir or ADAPTERS_DIR
+    root = adapters_dir or _resolve_adapters_dir(Path(__file__))
     records: dict[str, AdapterRecord] = {}
     if not root.is_dir():
         return records
@@ -94,10 +97,24 @@ def entrypoint_path(record: AdapterRecord, capability: str) -> Path | None:
     return path if path.is_file() else None
 
 
+_MODULE_CACHE: dict[tuple[str, str], tuple[float, ModuleType]] = {}
+
+
 def load_entrypoint_module(record: AdapterRecord, capability: str) -> ModuleType | None:
     path = entrypoint_path(record, capability)
     if path is None:
         return None
+    # Executing an adapter entrypoint re-imports its provider SDK, which is far
+    # too expensive for a polled Hub route. Keyed on mtime so an edited adapter
+    # still reloads rather than serving a stale module.
+    key = (record.id, capability)
+    try:
+        stamp = path.stat().st_mtime
+    except OSError:
+        stamp = 0.0
+    cached = _MODULE_CACHE.get(key)
+    if cached is not None and cached[0] == stamp:
+        return cached[1]
     module_name = f"coding_os_adapter_{record.id}_{capability}"
     spec = importlib.util.spec_from_file_location(module_name, path)
     if spec is None or spec.loader is None:
@@ -108,4 +125,5 @@ def load_entrypoint_module(record: AdapterRecord, capability: str) -> ModuleType
     except Exception as exc:
         logger.warning("%s %s entrypoint load failed: %s", record.id, capability, exc)
         return None
+    _MODULE_CACHE[key] = (stamp, module)
     return module

{coding_os-0.3.8 → coding_os-0.3.9}/src/core/thinking_os/dispatcher.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import os
 from pathlib import Path
@@ -33,6 +34,10 @@ class DispatchRequest(BaseModel):
     # generic so non-Claude adapters can use their own model strings.
     model: str | None = None
     effort: str | None = None
+    # Cynefin level of the originating request (CLEAR/COMPLICATED/COMPLEX/
+    # CHAOTIC). Empty means unclassified, which never satisfies an adaptive
+    # supervision gate — an unknown request is not escalated by accident.
+    complexity: str = ""
     # Per-call cost ceiling (USD). None = no ceiling. Adapters that
     # cannot enforce this MUST surface a warning rather than silently
     # dropping the cap. The Claude adapter forwards this to
@@ -113,7 +118,7 @@ def _known_agents() -> set[str]:
 def _detect_agent() -> str:
     known = _known_agents()
     explicit = os.environ.get("COS_AGENT", "").strip().lower()
-    if explicit:
+    if explicit in known:
         return explicit
 
     agent_dir = os.environ.get("COS_AGENT_DIR", "")
@@ -191,6 +196,23 @@ def _default_model(record) -> str | None:
     return None
 
 
+def _with_fleet_recovery_hint(
+    last_result: DispatchResult, capacity_waits: list[tuple[str, int | None]]
+) -> DispatchResult:
+    if len(capacity_waits) < 2 or last_result.error_category != "capacity":
+        return last_result
+    waits = [seconds for _, seconds in capacity_waits if seconds is not None]
+    soonest = min(waits) if waits else None
+    names = ", ".join(scope for scope, _ in capacity_waits)
+    recovery = f"soonest recovery in {soonest}s" if soonest is not None else "recovery time unknown"
+    return last_result.model_copy(
+        update={
+            "error": f"every eligible model pool is at capacity ({names}); {recovery}",
+            "retry_after_s": soonest,
+        }
+    )
+
+
 async def dispatch_request(request: DispatchRequest, db_path: str | Path) -> DispatchResult:
     from thinking_os import supervision
 
@@ -198,9 +220,10 @@ async def dispatch_request(request: DispatchRequest, db_path: str | Path) -> Dis
         Path(request.cwd).resolve() if request.cwd else supervision.current_project_root()
     )
     policy = supervision.load_policy(project_root)
-    if policy.get("enabled") is not True:
+    if not supervision.policy_applies(policy, request.complexity):
         return await get_dispatcher(request=request).dispatch(request)
 
+    propose_only = str(policy.get("mode") or "explicit") == "suggest"
     records = {record.id: record for record in supervision.eligible_records(project_root)}
     target = request.adapter or _detect_agent()
     candidates = [target] if target in records else []
@@ -219,22 +242,15 @@ async def dispatch_request(request: DispatchRequest, db_path: str | Path) -> Dis
         )
 
     last_result: DispatchResult | None = None
+    # Every adapter refused for capacity, with the wait it reported. The caller
+    # needs the SOONEST recovery across the fleet, not whichever adapter the
+    # loop happened to check last.
+    capacity_waits: list[tuple[str, int | None]] = []
     for adapter_id in candidates:
         record = records[adapter_id]
-        decision = supervision.check_capacity(db_path, adapter_id)
-        if not decision.allowed:
-            last_result = DispatchResult(
-                formula_id=request.formula_id,
-                status="error",
-                error=decision.reason or f"{adapter_id} is cooling down",
-                error_category="capacity",
-                retryable=True,
-                retry_after_s=decision.retry_after_s,
-                dispatcher_name="supervisor",
-                outcome="known_failed",
-            )
-            continue
-
+        # Request-shape validation runs BEFORE check_capacity: a capacity check
+        # consumes the single half-open recovery probe, so a request that can
+        # never reach the adapter must not starve its recovery.
         selected = request.model_copy(update={"adapter": adapter_id})
         if selected.effort and "effort_selection" not in record.capabilities:
             last_result = DispatchResult(
@@ -283,10 +299,65 @@ async def dispatch_request(request: DispatchRequest, db_path: str | Path) -> Dis
             )
             continue
 
-        result = await runtime.dispatch(selected)
-        supervision.record_result(
+        if propose_only:
+            return DispatchResult(
+                formula_id=request.formula_id,
+                status="skipped",
+                dispatcher_name="supervisor",
+                output_json={
+                    "proposed_route": {
+                        "adapter": adapter_id,
+                        "model": selected.model,
+                        "effort": selected.effort,
+                    },
+                    "reason": (
+                        "supervision mode 'suggest' resolves the route without "
+                        "executing it; switch to 'explicit' or 'adaptive' to run"
+                    ),
+                },
+            )
+
+        # sqlite here is synchronous and takes a write lock; off-loading keeps a
+        # parallel fan-out from serializing the event loop on the breaker.
+        scope = supervision.capacity_key(record, selected.model or _default_model(record))
+        # The lease must cover the probe, but timeout_s is caller-supplied and
+        # unbounded — clamp it to the same ceiling that bounds a cooldown.
+        lease = min(float(request.timeout_s), float(policy["cooldown"]["maximum_seconds"]))
+        decision = await asyncio.to_thread(
+            supervision.check_capacity, db_path, scope, lease_seconds=lease
+        )
+        if not decision.allowed:
+            capacity_waits.append((scope, decision.retry_after_s))
+            last_result = DispatchResult(
+                formula_id=request.formula_id,
+                status="error",
+                error=decision.reason or f"{adapter_id} is cooling down",
+                error_category="capacity",
+                retryable=True,
+                retry_after_s=decision.retry_after_s,
+                dispatcher_name="supervisor",
+                outcome="known_failed",
+            )
+            continue
+
+        try:
+            result = await runtime.dispatch(selected)
+        except Exception:
+            # An adapter that raises never reaches record_result, so the probe
+            # lease it holds would strand recovery for the whole lease window.
+            await asyncio.to_thread(supervision.release_probe, db_path, scope)
+            raise
+        if result.status == "error" and result.error_category is None:
+            logger.warning(
+                "%s returned an unclassified failure, so the capacity breaker "
+                "cannot protect it (dispatcher-contract.md rule 7): %s",
+                adapter_id,
+                (result.error or "")[:120],
+            )
+        await asyncio.to_thread(
+            supervision.record_result,
             db_path,
-            adapter_id,
+            scope,
             success=result.status == "ok",
             error_category=result.error_category,
             retryable=result.retryable,
@@ -296,11 +367,18 @@ async def dispatch_request(request: DispatchRequest, db_path: str | Path) -> Dis
         )
         meta = result.output_json.setdefault("_meta", {})
         if isinstance(meta, dict):
+            # Identity uses the OpenTelemetry GenAI attribute names so a future
+            # runtime learns what to emit from a public spec rather than from
+            # this repo's docs, and any OTel-aware tool can read the envelope.
             meta.update(
                 {
                     "adapter": adapter_id,
                     "model": selected.model,
                     "effort": selected.effort,
+                    "gen_ai.provider.name": adapter_id,
+                    "gen_ai.agent.id": request.formula_id,
+                    "gen_ai.request.model": selected.model,
+                    "capacity_scope": scope,
                     "health_state": decision.state,
                     "health_probe": decision.probe,
                     "error_category": result.error_category,
@@ -314,11 +392,15 @@ async def dispatch_request(request: DispatchRequest, db_path: str | Path) -> Dis
             and result.outcome == "known_failed"
             and policy.get("fallback_policy") == "next_eligible"
         ):
+            capacity_waits.append((scope, result.retry_after_s))
             last_result = result
             continue
         return result
 
-    return last_result or DispatchResult(
+    if last_result is not None:
+        return _with_fleet_recovery_hint(last_result, capacity_waits)
+
+    return DispatchResult(
         formula_id=request.formula_id,
         status="error",
         error="no dispatch adapter accepted the request",