@octocodeai/freellama-mcp-server 0.1.0 → 0.5.0

package/docs/ARCHITECTURE.md

@@ -1,8 +1,13 @@
 # FreeLlama architecture
 
-FreeLlama is a localhost control plane in front of Ollama. Ollama owns model storage, model loading,
-scheduling, inference engines, and token generation. FreeLlama owns model-aware policy around those
-operations.
+FreeLlama is the management layer between an AI agent and local Ollama models. Agents offload
+bounded tasks through MCP, the CLI, or the control API. FreeLlama selects eligible models,
+coordinates resources, and returns results with execution evidence.
+
+The calling agent owns task decomposition, prompts, and answer verification. FreeLlama owns managed
+admission, memory checks, residency coordination, and routing within operator-configured CPU/GPU
+backends. Ollama owns model storage, runner loading, inference engines, and token generation;
+the operating system and drivers schedule physical work.
 
 ## Responsibility boundary
 
@@ -13,8 +18,9 @@ The following table defines the ownership boundary:
 | Model files, runners, Metal, MLX, llama.cpp, and token generation | Ollama |
 | Native `/api/*` and OpenAI-compatible `/v1/*` semantics | Ollama |
 | Installed-model discovery and capability normalization | FreeLlama |
-| Task routing, advertised-context compatibility, K/V lower-bound preflight, evidence policy, and model rejection reasons | FreeLlama |
-| Managed admission, session affinity, and model-transition coordination | FreeLlama |
+| Task routing, advertised-context compatibility, advisory K/V estimates, evidence policy, and model rejection reasons | FreeLlama |
+| Managed admission, session affinity, bounded scope history, and model-transition coordination | FreeLlama |
+| Forecast memory reservations, host-pressure holds, and requests to unload idle unpinned models | FreeLlama managed execution |
 | Explicit per-model CPU/GPU backend assignment | FreeLlama and separate Ollama processes |
 | Grounded research adapters, citations, and verification verdicts | FreeLlama MCP server |
 
@@ -77,6 +83,8 @@ flowchart TD
     C -->|"natural-routes"| INTENT["Run intent model, then route"]
     C -->|"tasks"| RUN["Route, admit, and execute"]
     C -->|"sessions"| SESSION["Create in-memory affinity id"]
+    C -->|"scopes"| SCOPES["Retain revision-protected messages"]
+    C -->|"warm"| RUN
 ```
 
 The control API exposes these endpoints:
@@ -91,7 +99,16 @@ The control API exposes these endpoints:
 | `POST /_freellama/v1/natural-routes` | Schema-bound intent interpretation followed by deterministic routing | Intent model only |
 | `POST /_freellama/v1/sessions` | New model-affinity session | No |
 | `DELETE /_freellama/v1/sessions/:session_id` | Release model-affinity session | No |
+| `POST /_freellama/v1/scopes` | Create bounded message history | No |
+| `GET /_freellama/v1/scopes/:id` | Scope metadata; optional explicit history inclusion | No |
+| `POST /_freellama/v1/scopes/:id/fork` | Fork history at an expected revision | No |
+| `DELETE /_freellama/v1/scopes/:id` | Delete retained history | No |
+| `POST /_freellama/v1/warm` | Admitted load of an exact installed runner profile | Load only |
 | `POST /_freellama/v1/tasks` | Managed chat, vision, tools, or embedding task | Yes |
+| `GET /_freellama/v1/jobs` | Deferred job metadata without prompts or results | No |
+| `GET /_freellama/v1/jobs/:id` | One deferred receipt and retained result | No |
+| `POST /_freellama/v1/jobs/:id/cancel` | Cancel one deferred task and release its local permits | No new inference |
+| `DELETE /_freellama/v1/jobs/:id` | Cancel active work, release local permits, and remove its retained record | No new inference |
 
 The machine profile is host-derived rather than model-name-derived. It reports total physical
 memory on macOS (`sysctl`), Linux (`/proc`), and Windows (system APIs), along with CPU, OS,
@@ -125,9 +142,19 @@ A failed `/api/show` response skips that model instead of failing the entire cat
 configured backend fails catalog discovery closed because FreeLlama cannot prove the assigned model's
 state.
 
+### Public model metadata
+
+Public model enrichment belongs to the MCP layer's `model-knowledge.ts` and `model-search.ts`.
+Installed/detail requests can opt into GET-only Ollama family and full tag-page lookups. The layer
+matches exact tags and digest prefixes, preserves local supported features, and attaches family-scoped
+source excerpts and usage notes. Its bounded in-memory cache expires successes after one hour and
+failures after one minute. Failed or unmatched lookups leave local inventory and evidence intact.
+Public claims do not enter the Rust catalog, task policy, quality confidence, or routing decisions.
+See [Ollama model metadata](MODEL_METADATA.md) for the public contract and request bounds.
+
 ## Deterministic routing
 
-Routing starts with an explicit task contract. Supported task kinds are `completion`, `coding`,
+Routing defaults to ordinary `completion`; explicit profiles refine selection. Supported task kinds are `completion`, `coding`,
 `code_repair`, `tools`, `browser`, `vision`, `embedding`, and `long_context`.
 
 ```mermaid
@@ -138,7 +165,7 @@ flowchart TD
     X -->|"Yes"| E["Use exact model or refuse"]
     X -->|"No"| O{"Objective"}
     O -->|"fastest"| S["Rank local performance,<br/>residency, and deterministic ties"]
-    O -->|"balanced"| B["Require policy-qualified candidates,<br/>then balance score and residency"]
+    O -->|"balanced"| B["Prefer policy-qualified candidates;<br/>otherwise use eligible models with low confidence"]
     O -->|"quality"| Q["Require policy-qualified candidates,<br/>then prefer policy order"]
     E --> H["Grade advertised-context compatibility and evidence"]
     S --> H
@@ -154,7 +181,7 @@ reason so callers can distinguish capability, context, policy, and installation
 
 `context_window_fit` means only that requested `num_ctx` fits the model's advertised context
 window. It is not a live-memory, free-VRAM, K/V-cache, thermal, or runner-admission verdict.
-Execution separately reports a conservative model-metadata K/V lower-bound preflight and post-run
+Execution separately reports an advisory model-metadata K/V estimate and post-run
 placement evidence; Ollama remains authoritative for actual runner allocation and admission.
 
 ### Confidence evidence
@@ -198,12 +225,23 @@ The natural route endpoint does not run the selected task. Submit a managed task
 
 ## Managed task execution
 
-Managed tasks combine routing with admission and backend-aware transition coordination:
+The implementation separates [admission scheduling](../packages/rust-core/src/platform/admission.rs),
+[execution coordination](../packages/rust-core/src/platform/execution.rs),
+[read-only readiness](../packages/rust-core/src/platform/readiness.rs), and
+[typed errors](../packages/rust-core/src/platform/error.rs). The platform module wires HTTP endpoints,
+configuration, discovery, and shared state; extracting these owners preserves the public routing API.
+
+Managed tasks combine routing with admission and backend-aware transition coordination. With
+`defer:true`, the server returns HTTP `202` and a process-local job handle, then runs the same task
+path. The bounded registry owns receipts and cancellation, while the existing governor owns
+admission. Batch items cannot defer. Per-task `timeout_seconds` bounds discovery, waiting, loading,
+and inference together, capped by the server task timeout. See [CLI controls](CLI.md#execute-tasks)
+for retention limits and [monitoring](MONITORING.md) for the observable lifecycle.
 
 ```mermaid
 flowchart TD
     T["POST /tasks or /task-batches"] --> R["Select eligible model + backend"]
-    R --> K["Calculate metadata-backed K/V lower bound<br/>(or report unknown)"]
+    R --> K["Estimate metadata-backed F16 K/V<br/>(or report unknown)"]
     K --> A{"Acquire selected backend's<br/>3:2:1 fair weighted budget"}
     A -->|"No"| E503["503 server busy"]
     A -->|"Yes"| B{"Execution backend"}
@@ -219,7 +257,7 @@ flowchart TD
     CR --> OQ
     CX --> OQ
     OQ --> SEND["Ollama schedules bounded request"]
-    SEND --> RETRY{"500, 502, 504,<br/>or connection failure?"}
+    SEND --> RETRY{"500, 502,<br/>or connection-establishment failure?"}
     RETRY -->|"Retryable"| OQ
     RETRY -->|"Success"| OBS["Query selected Ollama /api/ps"]
     OBS --> OUT["Route, assignment, physical observation,<br/>admission, metrics, and response"]
@@ -228,40 +266,120 @@ flowchart TD
 
 Admission is independent per backend and uses weighted fair round robin: interactive gets three
 turns, normal two, and background one, preserving FIFO inside each class and preventing starvation.
-The primary/GPU pool defaults to two weighted units and the
-optional CPU pool defaults to one. A saturated GPU burst therefore cannot consume the permit held
-for a small CPU helper. Those values represent one ordinary chat and one embedding, not detected
-hardware capacity; operators can tune both budgets from queue-wait and resident-memory evidence.
+The primary/GPU pool defaults to two weighted units per observed `OLLAMA_NUM_PARALLEL` slot,
+falling back to two. The optional CPU pool defaults to one. A saturated GPU burst therefore cannot
+consume the permit held for a small CPU helper. With one parallel slot, those values represent one
+ordinary chat and one embedding. Operators can tune both budgets from queue-wait and resident-memory evidence.
 After FreeLlama admission, each Ollama process applies its own `OLLAMA_MAX_QUEUE`, scheduler,
-`OLLAMA_NUM_PARALLEL`, and loaded-model limit. Raw proxy requests bypass FreeLlama admission and
-enter the primary Ollama queue directly.
+`OLLAMA_NUM_PARALLEL`, and loaded-model limit. Raw proxy requests bypass weighted admission but
+still pass the raw concurrency cap, backend exclusion, and host-pressure gate.
 
-| Task | Cost |
+| Task | Default cost |
 |---|---:|
 | Embedding | `ceil(input_items / 4)` |
 | Chat, coding, tools, browser, or long context | 2 |
 | Vision | 4 |
 
+The runtime file's `[task_costs]` table overrides task-kind base costs. Embeddings multiply their
+base by `ceil(input_items / 4)`; the acquired charge is capped to the backend's current capacity.
+See [monitoring controls](MONITORING.md#adaptive-concurrency) for validation and reload behavior.
+
+After six capacity bypasses, the scheduler reserves released capacity for the oldest blocked waiter,
+so a stream of small requests cannot indefinitely starve a larger request. Cancellation releases
+that reservation. Admission, resource waiting, and transition locking share one queue deadline.
+
+A task waiting for host resources returns its execution slot after two seconds and continues
+waiting within the same deadline. It remains counted against the backend's bounded queue, so
+memory pressure cannot create an invisible backlog. Health reports slot and resource waiters
+separately. Returning to slot admission transfers the existing queue registration atomically;
+new arrivals and a smaller reloaded queue limit cannot displace accepted work. Expired deadlines
+prevent admission even when an execution slot is free. Cancellation removes either waiter, and releasing a memory reservation wakes resource
+waiters immediately; host telemetry still obeys the sampling and recovery policy below.
+
 FreeLlama acquires the admission slot before a transition lock to avoid deadlock. A model marked
 resident during discovery is checked again while the shared transition lock is held; stale or
 unavailable residency falls back to the exclusive transition path. Session affinity is bound only
 after successful upstream execution, so refused and failed tasks cannot change later routing.
+An explicit `done:false` chat response or a reported upstream error is a failure, even with HTTP 200.
+It cannot train runtime feedback or bind affinity. Completed failed exchanges retain the raw response
+and honor a requested immediate unload. Transport failures also attempt that unload and return its
+lifecycle receipt, but a disconnected inference response alone does not prove upstream cancellation.
+Resource failures return a readable `error`, a stable `code`, and structured `resource_admission`
+data, including per-item batch failures.
 
 `POST /_freellama/v1/task-batches` is for caller-declared independent work only: every item has a
 stable ID and `independent:true`; dependent workflow execution is rejected before any upstream call.
 It bounds local dispatch and returns ordered per-item success/error receipts. Every child still
 passes the same global admission and transition path above.
 
-The K/V preflight derives F16 K+V bytes-per-token only when `/api/show` exposes the required model
-shape. It blocks only a known weights-plus-cache lower bound above 80% of total CPU/unified memory.
-It deliberately reports unknown rather than guessing for other architectures or discrete GPU free
-VRAM; Ollama remains the live loader and final memory authority.
+The K/V preflight derives single-sequence F16 K+V bytes-per-token only for supported model
+architectures with sufficient metadata. Explicit key/value dimensions take precedence; sliding-window,
+shared-KV, recurrent, and unknown layouts report unknown. F16 is advisory because quantized KV can
+use less memory. The coarse model-file budget refuses files over 80% of local CPU/unified RAM only
+for loopback backends. Forecasts use each backend's independently attributed parallelism and KV
+cache settings where process inspection is available, with explicit fallback sources otherwise.
+Process observations refresh on requests after five seconds; measurements made under different
+settings cannot supply an exact-fit estimate. Ollama remains the live loader and final memory
+authority. Configured settings alone do not prove physical processor placement.
+
+The shared [resource governor](../packages/rust-core/src/platform/resources.rs) samples local
+available-memory estimates, load per logical CPU, OS memory pressure, active swap-out growth, and
+thermal throttling when reported. It holds new local work below the larger of 15% available RAM or
+1 GiB, and requires two healthy samples above the larger of 20% or 2 GiB to resume. Historical swap
+occupancy alone is not pressure. Samples are cached for two seconds; unavailable signals stay unknown.
+Remote backends bypass this host gate.
+
+Each pressure signal recovers independently after two fresh samples that meet its recovery
+threshold. A recovered CPU-load signal therefore clears even while RAM remains low. That keeps
+unchanged resident runners eligible under a memory-only hold while cold loads continue waiting.
+
+The default `require_memory` telemetry policy holds local inference when available RAM is missing,
+even when a raw request has no model-footprint estimate. `best_effort` is an explicit opt-in;
+`require_all` additionally requires the collector's applicable load, OS-pressure, and thermal signals.
+Unsupported Linux collector signals remain explicitly unavailable rather than being fabricated.
+The pure `ResourceSnapshot::assess_capacity` calculation is shared by admission and previews.
+Previews use the same footprint lookup, subtract existing reservations, and expose both queue and
+resource readiness. An available weighted slot cannot by itself produce `runnable_now` when model
+headroom is insufficient. Preview capacity is advisory and conservative, never a reservation.
+
+Managed CPU/unified-memory tasks reserve estimated additional model-file and known F16 KV bytes
+across both backends. Verified runner footprints replace that estimate only for the same backend,
+immutable model digest, and equal-or-larger observed context. Exact resident digest/context matches
+avoid double-counting existing allocations. The reservation is rechecked after transition locking;
+an increased requirement that no longer fits refuses with 503, without waiting while holding the
+backend lock. Permits release on completion or cancellation. On discrete-GPU hosts, observed free
+VRAM discounts the estimated host-memory requirement by the bytes the GPU can hold. Missing VRAM
+telemetry reserves the full estimated footprint in host RAM. The governor cannot constrain external
+allocations or preempt an already-running model.
+
+Managed text tasks without explicit `context_tokens` select the smallest 2K/4K/8K/16K/32K bucket
+that covers the UTF-8 prompt/schema estimate, output reserve, and 512-token template margin, bounded
+by the selected model's advertised limit. Larger requests require explicit context or compaction.
+Multimodal and embedding requests retain their profiles. The execution receipt exposes
+`context_sizing`; previews contain routing fields only and therefore retain task defaults.
+Managed chat sends `truncate:false` and `shift:false` so supporting Ollama backends refuse overflow
+instead of silently losing earlier instructions. Managed embeddings send `truncate:false` too.
+Only the dedicated CPU backend supplies a thread default: half the logical CPU count on other
+platforms, while macOS leaves Ollama to select its performance cores. `FREELLAMA_CPU_NUM_THREAD`
+overrides that default; explicit request options take precedence. The primary backend leaves thread
+selection to Ollama to avoid changing the options of a shared runner. `runtime_options` reports
+forwarded values; runner support is not assumed.
 
 Resident tasks share a backend lock. Nonresident tasks take that backend's exclusive lock so a cold
 load cannot race another managed task on the same server. CPU and GPU backends have separate locks
 and admission pools, so they can progress independently.
 
-HTTP `500`, `502`, and `504` status codes and connection failures use bounded retry with backoff.
+In `serve`, mutating raw proxy requests also take the primary backend's exclusive transition lock,
+returning 503 when busy. The response body holds this guard through EOF or disconnect. Metadata
+GET/HEAD and `/api/show` requests remain available. Raw inference waits at most 500 ms for host
+pressure to clear, then returns 503 with `Retry-After`; empty `keep_alive:0` unload requests bypass
+pressure. Raw request-body collection has the configured request deadline too; an incomplete upload
+returns HTTP 408 and releases its guards without contacting Ollama. Admission receipts report
+`queue_wait_ms`, `resource_wait_ms`, `transition_wait_ms`, and
+their sum as `total_wait_ms`. Health and route receipts expose sampled pressure and reservations.
+
+HTTP `500` and `502` status codes and connection-establishment failures use bounded retry with backoff.
+HTTP `504`, transport timeouts and post-send disconnects are not replayed.
 FreeLlama does not retry `503 Service Unavailable` because retrying while holding admission can
 amplify overload. It does not retry a generation timeout because the first request might still run.
 
@@ -317,6 +435,7 @@ flowchart TD
     TOOL -->|"doctor"| NAPI["Native core diagnostics"]
     TOOL -->|"models"| MIX["Control API or direct Ollama/library HTTP"]
     TOOL -->|"run_task"| TASK["Control API route or task"]
+    TOOL -->|"task_jobs"| JOB["Deferred receipts and per-task cancellation"]
     TOOL -->|"ollama_manage"| LIFE["Direct Ollama pull or unload"]
     TOOL -->|"ollama_delete"| DELETE["Explicit destructive Ollama delete"]
     TOOL -->|"delegate_research"| AD["Confined adapter subprocess"]
@@ -355,14 +474,33 @@ shape.
 
 The adapter loop preserves its control contract through four mechanisms:
 
-- Pagination keeps complete output on disk while showing bounded pages to the model.
+- Pagination keeps complete output in adapter memory and writes it into the final result file,
+  while showing bounded pages. Oversized lines split losslessly; the final page ends pagination.
 - Context fitting byte-preserves the system prompt and question by default, compacts older
   observations, and fails before Ollama if pinned content cannot fit. The first estimate is
   configurable; real `prompt_eval_count` values calibrate subsequent fits conservatively.
 - JSON repair retains gathered evidence across a bounded format correction.
 - Repeat suppression serves an identical earlier result without rerunning the subprocess command.
 
-For the benchmark implementation of this loop, see [`AGENTS.md`](../AGENTS.md).
+Overflow compaction targets 90% of the input budget using older observations, preserving head/tail
+evidence and exact stored-page recovery actions. Already-fitting prefixes and existing breadcrumbs
+remain unchanged. Compact observation ledgers preserve action, status, source, step, page recovery,
+and untrusted-output provenance. Full observations and page offsets are stored in temporary files;
+only the requested page enters the conversation. Final audit JSON streams the full results from disk
+and is atomically replaced. Temporary files are cleaned on normal and exceptional exits.
+Calibration keys include the endpoint, exact model tag and verified manifest digest, system-prompt
+hash, estimator version, and settings. Unknown model identity disables persisted calibration while
+retaining process-local calibration. Adapter retries cover explicit
+503 overload and connection refusal, never uncertain timeouts or post-send disconnects.
+
+Ollama's optional `prompt_eval_cached_count` is a subset of total `prompt_eval_count`. Prefill rate
+uses uncached tokens only; unavailable cache counts produce null instead of invented zero hits.
+Adapter cache totals remain null if any turn is unreported, with partial-report coverage in metadata.
+See [Ollama usage](https://docs.ollama.com/api/usage) and
+[the pinned prefix-cache implementation](https://github.com/ggml-org/llama.cpp/blob/74a7c897f049c17e7080423aa2111776eff6ebbf/tools/server/server-context.cpp#L3201).
+
+For adapter implementation, defaults, and measured caveats, see the
+[local adapter reference](../benchmark/local/docs/07-adapter-contracts.md).
 
 ## Context and token boundary
 
@@ -390,6 +528,7 @@ FreeLlama keeps these values in memory:
 - Catalog metadata cache
 - Current residency snapshots
 - Session-to-model affinity
+- Revision-protected scope message history and bounded adaptive residency measurements
 - Independent GPU and CPU priority-fair weighted admission pools
 - Per-task normalized warm latency and queue feedback for each backend, restored from an optional
   versioned atomic snapshot
@@ -398,7 +537,11 @@ FreeLlama keeps these values in memory:
 Sessions are bounded (default 1024) and expire after idle time (default one hour); they store only
 model affinity, never prompts or Ollama KV. Restarting `freellama serve` clears sessions and the catalog cache. Persisted placement feedback is
 reloaded; `--ephemeral-feedback` intentionally resets it. Ollama owns model residency, so loaded
-models survive a FreeLlama restart.
+models survive a FreeLlama restart. Scope histories and their revisions do not survive restart.
+They store messages independently from affinity and append only a successful generation at the
+expected revision. Warming uses ordinary admission and fit checks; omitted residency controls use
+a finite measured policy. See [Scope history and model warming](SCOPES_AND_WARMING.md) for the
+public contract and configured limits.
 
 The design fails closed when it cannot establish a required contract. Examples include an
 unreachable configured backend, an unknown confidence grade, a policy without qualified models, an

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 quick start](../README.md#quick-start) for first
+use and this reference to look up commands and controls.
 
 ## Choose a command
 
@@ -22,16 +23,22 @@ flowchart TD
 
 | 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 |
@@ -91,18 +98,70 @@ 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,
+environment variable, 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.
+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 defaults to holding below 15% available RAM and resuming 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.
+
+The reserve applies to every new managed load, not only to the pressure gate: a task is admitted
+when effective available RAM covers already-reserved bytes, the task's estimated bytes, and the
+reserve (the hold reserve normally; the larger resume reserve while capacity is recovering).
+Effective available RAM is free memory plus a bounded reclaimable estimate, so it can be far lower
+than the OS "free" percentage. A refusal reports `assessment.status: "held_insufficient_capacity"`
+with `required_with_reserve_bytes` and `effective_available_bytes`; free memory, choose a smaller
+model, or lower the percentages deliberately.
+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`, `recommend`, and `task` accept
 `--execution-preference auto|prefer-cpu|prefer-gpu`. This is a fallback-capable hint over models
@@ -115,6 +174,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,7 +198,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.
+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.
 
 `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.
@@ -157,19 +223,41 @@ 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.
+- `--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
 
@@ -190,7 +278,7 @@ Generate the policy from correctness data and the benchmark report from local ru
 
 ```bash
 npx @octocodeai/freellama policy-from-eval \
-  --aggregate benchmark/local/results/<model>/aggregate.json \
+  --aggregate benchmark/local/results/MODEL/aggregate.json \
   --task coding \
   --min-pass 0.8 \
   --out platform.toml
@@ -202,6 +290,8 @@ npx @octocodeai/freellama serve --recommendation-catalog recommendations.example
 `serve` discovers `platform.toml` and `benchmark-report.json` in its working directory. Explicit
 `--policy-file` and `--benchmark-report` values take precedence.
 
+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. This prevents speed data from being mislabeled as quality evidence.
@@ -213,7 +303,7 @@ npx @octocodeai/freellama tools
 ```
 
 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`,
+online `models { view: "library" }` view. CLI-only operations include `serve`, `proxy`,
 `recommend`, `natural-route`, `bench-all`, `policy-from-eval`, `run`, and `eval`.
 
-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](../packages/mcp/README.md).