@octocodeai/freellama-mcp-server 0.1.0 → 0.6.0

package/docs/CLI.md

@@ -1,8 +1,9 @@
 # CLI reference
 
-The `freellama` command exposes local diagnostics, deterministic model routing, managed task
-execution, benchmarking, and the Ollama-compatible proxy. The front page covers the shortest path;
-this page is the complete command map.
+The `freellama` command starts and inspects the local management layer that agents use to offload
+work. It exposes diagnostics, model routing, managed execution, resource controls, benchmarking,
+and Ollama-compatible passthrough. Use the [README CLI section](https://github.com/bgauryy/FreeLlama/blob/main/README.md#or-use-the-cli) for first
+use and this reference to look up commands and controls.
 
 ## Choose a command
 
@@ -11,34 +12,34 @@ flowchart TD
     Q{"What do you need?"}
     Q -->|"Prepare first use"| I["init"]
     Q -->|"Inspect this machine"| D["doctor or machine"]
-    Q -->|"Inspect or choose a model"| M["models, route, or recommend"]
-    Q -->|"Execute a managed request"| T["session, natural-route, or task"]
+    Q -->|"Inspect or choose a model"| M["models or route"]
+    Q -->|"Execute a managed request"| T["session or task"]
     Q -->|"Run the control plane"| S["serve"]
     Q -->|"Preserve only Ollama APIs"| P["proxy"]
-    Q -->|"Measure or compare"| B["bench-all, run, or eval"]
-    Q -->|"Create a routing policy"| E["policy-from-eval"]
-    Q -->|"Compare CLI and MCP"| L["tools"]
+    Q -->|"Measure models"| B["bench-all"]
+    Q -->|"Write a routing policy"| PE["policy from-eval"]
 ```
 
 | Command | Purpose | Needs `freellama serve` |
 |---|---|---|
-| `init` | Inspect prerequisites and print a side-effect-free first-run plan | No |
+| `init` | Inspect prerequisites and print a side-effect-free first-run plan with readiness flags | No |
 | `serve` | Run the control plane and Ollama-compatible proxy | Starts it |
 | `auth-token` | Create a new mode-0600 bearer-token file without printing the secret | No |
 | `models` | List installed models, capabilities, residency, and evidence | Yes |
 | `machine` | Print portable host RAM, CPU, OS, architecture, disk, and the local Ollama endpoint | Yes |
-| `session` | Create an affinity scope for related tasks | Yes |
+| `status` | Live queues (also as a page at `http://127.0.0.1:11435/_freellama/ui`), current and adaptive limits, circuit breakers, loaded models, host memory, Ollama's effective settings, today's usage | Yes |
+| `usage` | Task and token totals per day and per model (`--days`, default 7) | Yes |
+| `config` | Effective runtime settings and the source of each; `--reload` re-reads the runtime file | Yes |
+| `session` | Create model affinity for related tasks | Yes |
+| `scope` | Create, inspect, fork, or delete bounded message history | Yes |
+| `warm` | Warm an installed model through managed admission | Yes |
 | `route` | Choose a model and request profile without executing it | Yes |
-| `recommend` | Return an installed route or a reviewed installation plan | Yes |
-| `natural-route` | Convert natural language to a route intent locally, then route it | Yes |
 | `task` | Route and execute one nonstreaming task | Yes |
+| `jobs` | List, inspect, cancel, or remove deferred tasks and warming operations | Yes |
 | `proxy` | Run only the Ollama-compatible retry and telemetry sidecar | No |
 | `bench-all` | Measure installed models by capability group | No |
-| `policy-from-eval` | Generate policy from quality-evaluation pass rates | No |
-| `tools` | Print MCP tools and their CLI equivalents | No |
+| `policy from-eval` | Write a task policy (`platform.toml`) from a quality-evaluation aggregate and the installed tags | No |
 | `doctor` | Inspect Ollama, hardware, versions, and effective settings | No |
-| `run` | Run a frozen suite against one Ollama build | No |
-| `eval` | Compare the same frozen suite against stock and candidate builds | No |
 
 Run `npx @octocodeai/freellama <command> --help` for every accepted flag and enum value. The executable's help
 is authoritative; this page explains how the commands fit together.
@@ -46,13 +47,16 @@ is authoritative; this page explains how the commands fit together.
 ## Start the control plane
 
 ```bash
-npx @octocodeai/freellama serve --recommendation-catalog recommendations.example.toml
+npx @octocodeai/freellama serve
 ```
 
 The default listener is `http://127.0.0.1:11435`, and the default Ollama upstream is
 `http://127.0.0.1:11434`. Use `--listen` and `--upstream` to change them. Nonloopback listeners
 require `--allow-remote` and a token from `--auth-token-file` or
-`FREELLAMA_AUTH_TOKEN_FILE`. Authentication applies to managed and passthrough routes.
+`FREELLAMA_AUTH_TOKEN_FILE`. Authentication applies to managed and passthrough routes. The token
+file must be a regular file, not a symlink, and hold one token of at least 32 bytes; surrounding
+whitespace is trimmed. On Unix it must also be owner-only (mode 0600). Windows file permissions
+(ACLs) are not checked, so protect the file with your user profile's permissions there.
 
 `serve` persists bounded adaptive feedback under the platform data directory by default. Override
 the path with `--feedback-file`; use `--ephemeral-feedback` only for disposable runs. See the
@@ -91,20 +95,80 @@ placement.
 
 ### Bound admission
 
-`--max-concurrent-tasks` is the primary/GPU cost budget, not a request count; it defaults to 2.
-`--cpu-max-concurrent-tasks` controls the independent CPU pool and defaults to 1. Embedding costs 1,
-chat costs 2, and vision costs 4 (capped to the selected backend's pool). A saturated GPU pool does
+`--max-concurrent-tasks` is the primary/GPU cost budget, not a request count. Without a flag or
+runtime-file value it defaults to 2 units per `OLLAMA_NUM_PARALLEL` slot of
+the Ollama server (read from its process environment where visible; Ollama's own default is 1, so 2).
+`freellama config` shows the effective value and where it came from.
+`--cpu-max-concurrent-tasks` controls the independent CPU pool and defaults to 1. Default base costs
+are embedding 1, chat 2, and vision 4. Embeddings multiply their base by `ceil(input_items/4)`;
+the acquired charge is capped to the selected backend's pool. Configure overrides in `[task_costs]`;
+see [monitoring controls](MONITORING.md#adaptive-concurrency). A saturated GPU pool does
 not consume CPU permits. `--max-queue-wait-seconds` defaults to 120; when no permit becomes
-available, FreeLlama refuses the task with HTTP 503 instead of waiting forever.
+available, FreeLlama refuses the task with HTTP 503 (`admission_timeout`) instead of waiting forever.
+A task can ask for a shorter wait with `max_wait_seconds` (`maxWaitSeconds` in MCP); it can never
+exceed the configured one. Omit it to use the server's waiting budget.
+That deadline covers weighted admission, host-resource waiting, and model-transition locking together.
+`--max-queued-tasks` (default 16) and `--cpu-max-queued-tasks` (default 8) also bound how many
+parsed requests can be retained per backend; a full queue receives 429 (`admission_queue_full`)
+immediately, and cancelled clients release their waiter. Every capacity refusal carries a
+`Retry-After` header and `retry_after_seconds`, estimated from queue depth and the backend's recent
+task duration, so clients back off instead of retrying hot. Health exposes the queue depth, oldest wait, in-flight work, and
+refusal/timeout/cancellation counters.
 
 These are conservative workload-unit defaults, not detected core or RAM counts. Tune them from
 queue-wait receipts and resident-memory observations on the target host. Ollama still controls
 decoding concurrency with `OLLAMA_NUM_PARALLEL`. It also owns a separate internal queue through
 `OLLAMA_MAX_QUEUE`: managed tasks enter that queue only after FreeLlama admission, while raw proxy
 traffic enters it directly. Start an unmeasured deployment with one loaded model and one parallel
-stream per Ollama process.
-
-`route`, `recommend`, and `task` accept
+stream per Ollama process. In `serve`, raw passthrough defaults to one full-lifetime streaming
+request; override with `--raw-proxy-max-concurrent-requests` only after measurement. A raw request
+over the cap waits up to `--raw-queue-wait-seconds` (default 10) and is then refused with 429 and
+`Retry-After`; `0` restores immediate refusal.
+
+All of these, plus pinned models, idle eviction, adaptive concurrency, the circuit breaker, and
+context sizing, can also live in a runtime file (`--runtime-config`) that `serve` re-reads when it
+changes. See [Monitoring and live tuning](MONITORING.md). The standalone
+`proxy` command keeps its cap opt-in for compatibility.
+
+The local host-pressure gate reports low available RAM below 15% and clears it above 20% after two
+healthy samples; minimum reserves are 1 GiB and 2 GiB, respectively. Tune the percentages with
+`--resource-hold-available-percent` and `--resource-resume-available-percent`; the hold value must be
+lower than the resume value, and neither can exceed 100. Health reports the policy, sampled signals,
+unknown measurements, and reserved memory. These flags do not change Ollama or OS settings.
+
+On macOS, low available RAM is advisory and never refuses a task. Effective available RAM is free
+memory plus a bounded reclaimable estimate, so it can be far lower than what the OS can actually
+reclaim. When it does not cover already-reserved bytes, the task's estimated bytes, and the reserve,
+FreeLlama first unloads idle unpinned runners, then dispatches anyway: the receipt reports
+`status: "admitted_low_memory_estimate"` and `assessment.memory_advisory: "below_reserve"` with
+`required_with_reserve_bytes` and `effective_available_bytes`. Ollama and the OS decide whether the
+load fits. On Linux, Windows, and other platforms, where available RAM already counts reclaimable
+cache (and is the hard cap in a container), the same shortfall unloads idle runners and then holds the
+new load with `held_insufficient_capacity` until capacity returns, refusing with 503 at its deadline.
+OS memory pressure holds work on every platform. Active swapping and low RAM hold new loads only:
+an already-resident runner adds no memory and stays admitted. CPU-load (one-minute load at or above
+1.5 per logical CPU) and thermal-throttling holds apply to CPU-assigned work and to cold loads, which
+decode weights on the host cores and add a new heat source; a bounded request on a runner already
+resident on the GPU neither waits for the cores nor cools the package by waiting, so it proceeds. The receipt's `resource_admission.assessment.held_by`
+lists the holds that applied to the request.
+Both `serve` and `proxy` accept `--resource-telemetry-policy`:
+
+- `require-memory` (default): wait or refuse local inference when available RAM is unknown, including
+  raw requests with zero forecast bytes. Missing thermal data alone does not block this policy.
+- `require-all`: require all signals applicable to the collector. The built-in Linux collector does
+  not provide OS pressure or thermal signals and marks those as unsupported; custom collectors must
+  provide them. Unsupported signals are not evidence of healthy hardware.
+- `best-effort`: explicitly permit unknown telemetry unless an observed pressure hold is active.
+
+Remote upstreams bypass local host policy. Raw metadata and empty unload requests remain available
+during a hold. Route receipts separate `queue_readiness` from `resource_readiness`, and include
+`resource_assessment` without acquiring a permit. Resource refusals return a human-readable `error`,
+a stable `code`, and an object-valued `resource_admission`; timeout during metadata inspection reports
+its phase and omits estimates that were not obtained.
+
+See [resource admission](ARCHITECTURE.md#managed-task-execution) for scope and limitations.
+
+`route` and `task` accept
 `--execution-preference auto|prefer-cpu|prefer-gpu`. This is a fallback-capable hint over models
 already assigned by the operator; it never rewrites raw passthrough and never makes an ineligible
 model eligible. Preview the route and inspect the `execution` receipt to confirm whether the hint
@@ -115,6 +179,10 @@ placement; the default `configured` accepts the operator assignment and observes
 
 Start with the read-only guided receipt, then inspect available models. `init` never pulls a model;
 it stops at exact-tag approval and prints the next prerequisite, serve, managed-task, and MCP steps.
+Its `status` is `blocked` when Ollama is unavailable, `setup_required` when the managed service or
+installed models are missing, and `ready` when all three are present. Separate `readiness` flags
+identify the missing part. Readiness does not qualify a model for a particular task; use a route
+preview to inspect eligibility and rejection reasons.
 
 ```bash
 npx @octocodeai/freellama init
@@ -135,14 +203,10 @@ npx @octocodeai/freellama route \
 
 Task kinds are `completion`, `coding`, `code-repair`, `tools`, `browser`, `vision`, `embedding`, and
 `long-context`. Objectives are `fastest`, `balanced`, and `quality`. `fastest` can use capability
-and local benchmark evidence alone; `balanced` and `quality` require a policy for that task.
-
-`recommend` is side-effect-free. If no installed model qualifies, it can return an installation
-plan from the reviewed recommendation catalog, but it never pulls a model.
-
-`natural-route` asks the configured local intent model to produce structured intent, validates that
-intent, and then invokes the same deterministic router as `route`. It does not let the intent model
-choose the final model directly.
+and local benchmark evidence alone. Default `balanced` prefers eligible task-policy candidates;
+without them it falls back to capability/context-compatible models and reports low confidence
+and missing quality evidence. `quality` requires a policy unless you supply an explicit model.
+An explicit minimum-confidence gate still refuses insufficient evidence in every objective.
 
 ## Execute tasks
 
@@ -157,19 +221,43 @@ Useful task options include:
 
 - `--model` for an exact installed model.
 - `--session` for affinity across related requests.
-- `--context-tokens` for a minimum context requirement.
+- `--scope-id` and `--scope-revision` together for bounded message history.
+- `--keep-alive` for an explicit residency duration.
+- `--context-tokens` for the complete input and output context window (`num_ctx`).
 - repeatable `--required-capability` constraints.
 - repeatable `--image` paths for vision tasks.
 - `--input-file` for batched embedding input, one item per line.
 - `--min-confidence low|medium` to refuse insufficiently evidenced routes before generation.
+- `--priority interactive|normal|background` for fair admission scheduling.
+- `--max-wait-seconds` for a shorter admission/resource wait budget.
+- `--timeout-seconds` for a total deadline including discovery, waiting, loading, and inference.
+- `--stop-on-repetition` to stream the task and stop once the output repeats itself, keeping all
+  generated text.
+- `--defer` to return a job ID immediately.
+
+Inspect deferred work with `jobs`, retrieve a result with `jobs --id <uuid>`, and cancel one task
+with `jobs --id <uuid> --cancel`. Remove one task with `jobs --id <uuid> --remove`: active work is
+cancelled first, then its retained record and result are deleted. Use the exact ID returned at
+submission; `--cancel` and `--remove` are mutually exclusive. The same operations are available
+through MCP `task_jobs`.
+Cancellation and removal wait for local execution permits to be released; they do not unload a shared model
+or confirm that the physical runner has stopped.
+
+Jobs stay in server memory: at most 64 receipts, 1 MiB per input, and 2 MiB per retained result or
+error. Finished receipts expire after 10 minutes and can be evicted earlier to make room for new
+work. A restart discards all jobs. Admission queue limits still apply, and deferred work can fail
+after acceptance. See [monitoring](MONITORING.md) for states and waiting reasons.
 
 Create a session with `session`, then pass its identifier to related `route` or `task` calls. A
 route preview honors an existing affinity but does not create or change one. Only a successfully
 admitted task execution binds the session to its selected model. Reuse never bypasses capability,
 policy, or memory checks.
 
-The CLI has no keep-alive flag. MCP `run_task` accepts `keepAlive`: `"0"` unloads after the request,
-`"-1"` pins the runner, and omission leaves Ollama's default in place.
+`task --keep-alive` and MCP `run_task.keepAlive` control residency: `"0"` requests immediate
+unload, `"-1"` requests indefinite retention, and omission selects finite adaptive retention.
+`session` retains affinity only; use `scope` for revision-protected message history and `warm`
+for an admitted runner load. See [Scope history and model warming](SCOPES_AND_WARMING.md) for
+input shapes, limits, and CLI examples.
 
 ## Earn medium routing confidence
 
@@ -178,7 +266,7 @@ benchmark record for the selected model.
 
 ```mermaid
 flowchart LR
-    Q["Quality evaluation aggregate"] --> P["policy-from-eval"]
+    Q["Quality evaluation aggregate"] --> P["freellama policy from-eval"]
     P --> PF["platform.toml"]
     T["Local throughput benchmark"] --> BR["benchmark-report.json"]
     PF --> S["freellama serve"]
@@ -186,34 +274,64 @@ flowchart LR
     S --> C["Medium confidence for configured, measured routes"]
 ```
 
-Generate the policy from correctness data and the benchmark report from local runtime data:
+Generate the policy from correctness data with `policy from-eval` and the benchmark report from
+local runtime data:
 
 ```bash
-npx @octocodeai/freellama policy-from-eval \
-  --aggregate benchmark/local/results/<model>/aggregate.json \
+npx @octocodeai/freellama policy from-eval \
+  --aggregate aggregate.json \
   --task coding \
   --min-pass 0.8 \
   --out platform.toml
 
 npx @octocodeai/freellama bench-all --output benchmark-report.json
-npx @octocodeai/freellama serve --recommendation-catalog recommendations.example.toml
+npx @octocodeai/freellama serve
 ```
 
-`serve` discovers `platform.toml` and `benchmark-report.json` in its working directory. Explicit
-`--policy-file` and `--benchmark-report` values take precedence.
+`serve` resolves each file in this order: the explicit flag, its environment variable, the working
+directory, then the per-user config directory (`$XDG_CONFIG_HOME/freellama/` or
+`~/.config/freellama/`; `%APPDATA%\FreeLlama\` on Windows).
 
-`policy-from-eval` reads `pass_at_1`, not the throughput produced by `bench-all`. It refuses expired
-aggregates and fewer than three trials unless `--allow-smoke` is explicit, and it skips models that
-are not installed. This prevents speed data from being mislabeled as quality evidence.
+| File | Flag | Environment variable | Discovered name |
+|---|---|---|---|
+| Task policy | `--policy-file` | `FREELLAMA_POLICY_FILE` | `platform.toml` |
+| Benchmark report | `--benchmark-report` | `FREELLAMA_BENCHMARK_REPORT` | `benchmark-report.json` |
 
-## Compare the CLI and MCP surfaces
+A task policy file has this shape:
 
-```bash
-npx @octocodeai/freellama tools
+```toml
+schema_version = 1
+
+[policies.code_repair]
+qualified_models = ["qwen3.8:27b-mlx"]   # best first; quality-qualified only
+
+# Optional request defaults for one exact tag on this task: think and num_predict (>= 1).
+[policies.code_repair.model_options."qwen3.8:27b-mlx"]
+think = false
+num_predict = 512
 ```
 
-The command prints the maintained parity map. MCP-only operations are `delegate_research` and the
-online `models { view: "library" }` view. CLI-only operations include `serve`, `proxy`, `session`,
-`recommend`, `natural-route`, `bench-all`, `policy-from-eval`, `run`, and `eval`.
+`serve` rejects unknown fields, including `num_ctx`: context size is routing-owned, so set
+`context_tokens` per request instead. Caller request options win over `model_options`, and
+`think = true` applies only to models with the thinking capability. See the annotated
+[platform.example.toml](https://github.com/bgauryy/FreeLlama/blob/main/platform.example.toml).
+
+The MCP server autostarts `serve` with its own environment and an arbitrary working directory, so
+put a machine-wide policy in the config directory or set the variables in the MCP client's `env`.
+`serve` prints each file it picked up.
+
+Replace `MODEL` with the directory containing your completed quality-evaluation aggregate.
+
+`policy from-eval` reads `pass_at_1`, not the throughput produced by `bench-all`. It refuses
+expired aggregates and fewer than three trials unless `--allow-smoke` is explicit, and it skips
+models that are not installed on `--ollama-endpoint` (default `FREELLAMA_OLLAMA_ENDPOINT`, then
+`http://127.0.0.1:11434`). This prevents speed data from being mislabeled as quality evidence.
+It accepts the task kinds `route` accepts, with `-` or `_` (`code-repair` or `code_repair`), writes
+to stdout unless `--out` is given, and reports a refusal as one `error: ...` line with exit status 1.
+
+## Compare the CLI and MCP surfaces
+
+MCP-only operations are `delegate_research` and the online `models { view: "library" }` view.
+CLI-only operations include `serve`, `proxy`, `bench-all`, `policy from-eval`, and `auth-token`.
 
-For the six MCP tool contracts, read the [MCP package reference](../packages/mcp/README.md).
+For the MCP tool contracts, read the [MCP package reference](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md).

package/docs/CPU_GPU_ROUTING.md

@@ -1,10 +1,15 @@
 # Run models on CPU and GPU
 
-Use two Ollama processes when a large model should remain on the GPU while smaller helper models run
-on the CPU. FreeLlama assigns exact model tags to the secondary process, pins those managed requests
-with `num_gpu: 0`, and reports the selected backend in catalog and task responses.
+To separate GPU work from CPU helpers, configure two Ollama processes and assign exact helper-model
+tags to the secondary process. FreeLlama routes managed tasks within those assignments, applies
+`num_gpu: 0` to CPU requests, and reports both the selected backend and observed processor placement.
 
-This configuration is useful for embeddings, intent interpretation, and other small helper models.
+The calling agent submits tasks and placement preferences. FreeLlama coordinates admission,
+memory checks, and model transitions for each backend; the operator configures the processes and
+eligible tags. A configured CPU backend is intent: inspect the placement observation before
+treating it as proof of CPU execution.
+
+This configuration is useful for embeddings, short classification, and other small helper models.
 Benchmark large CPU workloads before adopting them. Apple silicon shares memory bandwidth; systems
 with discrete GPUs have different contention and transfer costs, so neither result transfers
 without measurement.
@@ -23,7 +28,9 @@ machine-specific:
 
 `doctor` reports `machine.memory_bytes` on macOS, Linux, and Windows. It reports
 `machine.unified_memory_bytes` only when unified memory is known; that compatibility field is not a
-VRAM estimate on discrete-GPU hosts. Model-library fit is therefore a host-memory preflight, and
+VRAM estimate on discrete-GPU hosts. `machine.gpu` names the accelerator when the OS reports it
+(Apple model and core count, or NVIDIA name and memory on Linux), and `performance_cpus` /
+`efficiency_cpus` split hybrid CPUs on macOS. These are identity facts, not placement proof. Model-library fit is therefore a host-memory preflight, and
 actual accelerator placement must come from Ollama's resident-runner report.
 
 An agent can choose `auto`, `prefer_cpu`, or `prefer_gpu`, but it cannot invent topology. The
@@ -110,7 +117,10 @@ unsafe or ambiguous configurations:
 - A CPU model assignment without `--cpu-upstream`
 - Empty model names
 - The same socket expressed through aliases such as `localhost:11434` and `127.0.0.1:11434`
-- A non-loopback listener or upstream
+- A nonloopback upstream
+
+A nonloopback FreeLlama listener requires `--allow-remote` and bearer-token authentication.
+See the [production runbook](PRODUCTION.md) for remote ingress requirements.
 
 Set independent admission budgets when the defaults do not fit the workload:
 
@@ -120,13 +130,18 @@ Set independent admission budgets when the defaults do not fit the workload:
     --cpu-upstream http://127.0.0.1:11436 \
     --cpu-model nomic-embed-text:latest \
     --max-concurrent-tasks 2 \
-    --cpu-max-concurrent-tasks 1
+    --cpu-max-concurrent-tasks 1 \
+    --max-queued-tasks 16 \
+    --cpu-max-queued-tasks 8
 ```
 
 The defaults above admit one ordinary primary-backend chat (cost 2) and one CPU embedding (cost 1)
 at the same time. They are conservative workload units for the common `OLLAMA_NUM_PARALLEL=1`
 layout, not a profile of the development Mac. Increase them only after measuring queue wait,
 resident memory, and Ollama's own parallel setting on the target host.
+Queue cardinality and wait time are separate bounds: excess waiters are refused immediately, while
+an admitted waiter may remain until `--max-queue-wait-seconds`. Automatic backend selection checks
+that the actual task cost fits the current slot snapshot before following historical speed.
 
 ## Let an agent express placement intent
 
@@ -194,12 +209,14 @@ The `execution` object separates the configured `backend`, requested compatibili
 post-run `observation`. The source is Ollama `/api/ps`; direct inspection remains useful:
 
 ```bash
-curl --silent http://127.0.0.1:11434/api/ps | jq '.models[] | {name, size_vram}'
-curl --silent http://127.0.0.1:11436/api/ps | jq '.models[] | {name, size_vram}'
+curl --silent http://127.0.0.1:11434/api/ps | jq '.models[] | {name, size, size_vram}'
+curl --silent http://127.0.0.1:11436/api/ps | jq '.models[] | {name, size, size_vram}'
 ```
 
-A fully CPU-loaded model reports `size_vram:0`; a fully GPU-loaded model reports positive resident
-VRAM. `observation.status` is `verified`, `mismatch`, or unavailable. Unknown, mixed, and mismatched
+A fully CPU-loaded model reports `size_vram:0`; a fully GPU-loaded model reports positive VRAM
+covering its resident `size`. Compare both values from the same `/api/ps` entry. Installed `/api/tags`
+file bytes can differ from resident memory and cannot prove a mixed placement. Positive VRAM without
+total resident size stays unknown. `observation.status` is `verified`, `mismatch`, or unavailable. Unknown, mixed, and mismatched
 samples are reported but excluded from adaptive feedback.
 
 ## Understand concurrency
@@ -208,10 +225,16 @@ Each backend has its own weighted admission pool and its own resident/shared and
 transition/exclusive lock. CPU and GPU model transitions therefore do not block each other, and a
 GPU burst cannot spend the CPU helper's permit:
 
+Both pools also share local host-pressure sampling and forecast-memory reservations. Independent
+queues do not imply independent RAM on a unified-memory machine. A request can wait for available
+headroom even when its backend has a free weighted permit. Inspect `admission.resources` in health
+and `execution.resource_admission` in task receipts. Unknown thermal or GPU measurements are not
+reported as healthy readings. See [the execution architecture](ARCHITECTURE.md) for the complete gate.
+
 ```mermaid
 flowchart TD
     T["Managed task"] --> B{"Selected backend"}
-    B -->|"GPU"| GA["GPU admission pool<br/>default 2 units"]
+    B -->|"GPU"| GA["GPU admission pool<br/>default 2 units per Ollama slot"]
     B -->|"CPU"| CA["CPU admission pool<br/>default 1 unit"]
     GA --> GL{"Resident?"}
     CA --> CL{"Resident?"}
@@ -229,16 +252,28 @@ FreeLlama can overlap requests across the two servers even when each Ollama proc
 `OLLAMA_NUM_PARALLEL=1`. Raising `OLLAMA_NUM_PARALLEL` affects parallel requests within one server
 and multiplies K/V-cache memory; it is a separate tuning decision. `OLLAMA_MAX_QUEUE` likewise
 bounds each Ollama process after FreeLlama admission. It does not replace either backend's weighted
-FreeLlama budget or queue-wait deadline.
+FreeLlama budget, bounded waiter count, or queue-wait deadline. Raw passthrough uses a separate
+one-stream default cap in `serve`; its permit is held until the streamed response ends or is dropped.
+
+The runtime file's `[task_costs]` table can tune individual task-kind weights without increasing
+the entire pool's ceiling. Default vision weight four can serialize two vision requests under a
+four-unit budget even when Ollama has two slots. A lower weight requires a qualified workload;
+it does not add engine slots or relax memory checks. See
+[monitoring controls](MONITORING.md#adaptive-concurrency).
+Mutating raw requests also require exclusive access to the primary backend's managed transition
+lock and receive 503 while it is busy. Metadata GET/HEAD calls remain available. This prevents raw
+inference or model lifecycle calls from overlapping a managed generation on that backend.
 
 ## Understand automatic feedback
 
 With `executionPreference: "auto"`, unpinned `fastest` and `balanced` work can select a backend from
-observed warm task duration. The loop is deliberately bounded:
+comparable observed warm task duration. Learned hints require two eligible backends, explicit
+context, and a known execution payload-control projection. A decision-only preview cannot supply
+that payload projection and uses capacity and policy signals. The loop is bounded:
 
 ```mermaid
 flowchart LR
-    X["Successful resident task"] --> O["Record duration by<br/>task + backend"]
+    X["Comparable warm serial task"] --> O["Record duration by<br/>task + backend + profile"]
     O --> N{"At least 3 samples<br/>on both backends?"}
     N -->|"No"| D["Keep deterministic default"]
     N -->|"Yes"| C{"More than 10% faster<br/>per work unit?"}
@@ -248,13 +283,25 @@ flowchart LR
 ```
 
 Generation compares decode nanoseconds per output token; embeddings compare total nanoseconds per
-input token. Buckets are model-specific and reset when the selected model changes. Only physically
-verified placement contributes; cold transitions and assignment mismatches do not. A difference
+input token. Each task/backend has one current profile window, reset when identity changes.
+Identity includes installed/resident digest, rate metric kind, explicit observed context, effective controls,
+endpoint-attributed process settings, and serial admission class. Unknown or changed evidence,
+cold transitions, and overlapping managed work supply no speed sample. A difference
 of 10% or less is treated as noise. Feedback never overrides an explicit model, session affinity,
 capability or policy guards, or the `quality` objective. The CLI persists the bounded, versioned,
-prompt-free aggregate snapshot atomically by default; `--ephemeral-feedback` opts into reset-on-
-restart behavior. `GET /_freellama/v1/health` exposes persistence status, sample counts, readiness,
-and per-backend admission capacity so an agent can inspect the loop instead of guessing.
+prompt-free snapshot atomically by default; `--ephemeral-feedback` opts into reset-on-restart
+behavior. Legacy aggregate fields survive loading but do not qualify learned hints. Health's
+`decision_ready` describes the stored profile window; the current request must independently
+match it before routing can use its speed. `GET /_freellama/v1/health` exposes profile identity,
+profile sample counts, persistence status, and per-backend admission capacity. Physically verified
+warm completions still contribute legacy duration diagnostics even when their interval cannot
+qualify a speed-learning sample.
+
+Configured processor intent, verified placement, and speed-learning eligibility remain separate
+receipt fields. Missing endpoint-attributed process inspection disables learned hints and recovery,
+including remote backends; ordinary routing, admission, and pressure/error safeguards still work.
+Fresh process probes run for candidate serial learning or an eligible learned-route lookup, not
+for pinned, quality-only, preview-only, or single-backend route selection.
 
 ## Interpret the measured Mac result
 
@@ -307,7 +354,6 @@ and `execution.lifecycle`; a failed unload is reported without discarding the co
 Prefer the following assignments:
 
 - Small embedding models
-- Lightweight intent models
 - Short extraction or classification helpers with measured CPU behavior
 
 Benchmark these assignments before adopting them:
@@ -318,7 +364,7 @@ Benchmark these assignments before adopting them:
 
 The local measurement receipt is written to
 `.octocode/evals/cpu-gpu-concurrency-benchmark.md`. Git intentionally ignores that path, so the
-trial table in "Interpret the measured result" carries the durable result while the local artifact
+trial table in ["Interpret the measured Mac result"](#interpret-the-measured-mac-result) carries the durable result while the local artifact
 retains the full run detail.
 
 ## Troubleshoot the secondary backend
@@ -337,7 +383,7 @@ can also be unavailable until the secondary server returns. Raw passthrough to t
 continues to work because it does not depend on catalog discovery.
 
 For the surrounding runtime settings, see
-[Ollama and FreeLlama optimization](OLLAMA_SYSTEM_OPTIMIZATION.md). For all `serve` flags, see the
+[Ollama and FreeLlama optimization](dev/OLLAMA_SYSTEM_OPTIMIZATION.md). For all `serve` flags, see the
 [CLI reference](CLI.md).
 
 ## Upstream sources