@miller-tech/uap 1.137.1 → 1.137.3

package/docs/INDEX.md

@@ -1,6 +1,6 @@
 # UAP Documentation
 
-The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.124.1) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.
+The complete documentation for the **Universal Agent Protocol** (`@miller-tech/uap` v1.137.1) — the discipline layer that turns a talented-but-unreliable AI coding agent into a dependable member of your software delivery line.
 
 > **Reviewing the system?** The reverse-engineered, code-verified reference set lives in
 > [`documentation/`](../documentation/architecture.md): architecture, flows, permissions
@@ -20,11 +20,11 @@ UAP is organized like a delivery line. If you know which part of the pipeline yo
 | **Intake** — understand the work | Amnesiac sessions, invented scope | [Memory](guides/MEMORY.md) · [Reactor](design/UAP_REACTOR.md) |
 | **Prep / routing** — right job, right station | Wrong approach or wrong-sized model | [Multi-Model Routing](guides/MULTI_MODEL.md) · [Patterns](reference/PATTERNS.md) · [Droids & Skills](guides/DROIDS_AND_SKILLS.md) |
 | **Isolation** — a bench per job | Editing `main`, clobbering files | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) |
-| **Build** — make the thing | Plausible-but-wrong code, stubs, empty output | [`uap deliver`](guides/DELIVER.md) · [Local Models](guides/LOCAL_MODELS.md) |
+| **Build** — make the thing | Plausible-but-wrong code, stubs, empty output | [`uap deliver`](guides/DELIVER.md) · [Local Models](guides/LOCAL_MODELS.md) · [Inference Proxy](guides/PROXY.md) |
 | **QC / verify** — prove it runs | "Done" on code that never ran | [`uap deliver`](guides/DELIVER.md) · [Policies](guides/POLICIES.md) |
 | **Coordination** — many workers, one floor | Parallel agents colliding | [Coordination](guides/COORDINATION.md) · [Deploy Batching](guides/DEPLOY_BATCHING.md) |
 | **Shipping** — out the door safely | Regressions, red CI, skipped bumps | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) · [Policies](guides/POLICIES.md) |
-| **Feedback** — the floor learns | The same mistake every session | [Memory](guides/MEMORY.md) · [Self-Harness](design/SELF_HARNESS.md) |
+| **Feedback** — the floor learns | The same mistake every session | [Memory](guides/MEMORY.md) · [Self-Harness](design/SELF_HARNESS.md) · [Self-Tuning](guides/SELF_TUNING.md) |
 | *Cross-cutting* — the whole line | Ignored rules, bloated context | [Policies](guides/POLICIES.md) · [MCP Router](guides/MCP_ROUTER.md) |
 
 Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
@@ -54,12 +54,15 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [Sandbox](guides/SANDBOX.md) | Kernel-level (bubblewrap) write isolation — the boundary that survives `--dangerously-skip-permissions` |
 | [Policies](guides/POLICIES.md) | Executable policy gates that block non-compliant tool calls |
 | [**Policy Selection & Recommendations**](guides/POLICY_SELECTION.md) | Which policies to enable for your workflow — a recommended core + tailored sets by scenario; `uap policy recommend` ⭐ |
+| [Pay2U Policy Pack](guides/POLICY_PACK_PAY2U.md) | The pay2u-tailored policy bundle |
 | [Multi-Model Routing](guides/MULTI_MODEL.md) | Plan → route → execute across 7 model profiles |
-| [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 32 skills, the expert router |
+| [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 36 skills, the expert router |
 | [Deploy Batching](guides/DEPLOY_BATCHING.md) | Conflict-free batched git/deploy actions |
 | [Coordination](guides/COORDINATION.md) | Multi-agent overlap detection |
 | [Local Models](guides/LOCAL_MODELS.md) | Running agents against local llama.cpp / Qwen models |
+| [Inference Proxy](guides/PROXY.md) | The Anthropic↔local gateway: `uap proxy` lifecycle, reliability guardrails, security, serving recipes |
 | [Qwen3.6 on llama.cpp by VRAM](guides/QWEN36_LLAMACPP.md) | Tiered 8/12/16/24/32 GB setup; how `uap deliver` uplifts small local models |
+| [**LLM Self-Tuning**](guides/SELF_TUNING.md) | `uap tune` — raise a small model toward Opus by tuning UAP's flag surface with a benchmark-validated LLM/GP-BO loop; quality scoring, model profiles, auto-on real-time adaptation ⭐ |
 
 ## Architecture
 
@@ -68,7 +71,8 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [Overview](architecture/OVERVIEW.md) | System architecture as the delivery-line floor plan; subsystems, tool-call flow |
 | [Protocol](architecture/PROTOCOL.md) | The harness↔UAP contract, hook lifecycle, decision loop |
 | [Reactor (auto-apply)](design/UAP_REACTOR.md) | Dynamic experts/skills/patterns injected per prompt across harnesses; the assist vs enforce model, per-harness wiring |
-| [Self-Harness (proposal)](design/SELF_HARNESS.md) | Self-improving harness: autonomous mine→propose→validate loop over a bounded Mod DSL; cross-model transfer, online mining |
+| [Self-Harness](design/SELF_HARNESS.md) | Self-improving harness (shipped as `uap self-harness`): autonomous mine→propose→validate loop over a bounded Mod DSL; cross-model transfer, online mining |
+| [LLM Self-Tuning (analysis)](design/LLM_SELF_TUNING_ANALYSIS.md) | The design behind `uap tune`: quality signal, LLM-guided + Gaussian-process flag search, closed-loop validation, model profiles, real-time adaptation |
 
 ## Reference
 

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -88,6 +88,14 @@ Install UAP (`npm i -g universal-agent-protocol`) and every feature below activa
 
 **Why it matters:** No manual tuning. The right parameters are applied automatically for each model family.
 
+### Real-Time Adaptation (self-tuning) ✨
+
+**What it does:** During a session the reactor watches live signals — tool-failure rate, per-turn quality, context-window pressure, and RECON no-write streaks — and, when one breaches a threshold, emits a per-session adjustment the proxy honors mid-flight: escalate the turn to the judge model (fusion), converge sooner (lower the recon threshold), or force synthesis to break an exploration loop.
+
+**When it kicks in:** Auto-on. It is conservative — a signal is emitted only on a real threshold breach, so a nominal session is unchanged. Opt out with `uap config set realtimeAdapt.enabled false` (or `UAP_REALTIME_ADAPT=0`).
+
+**Why it matters:** The static per-model config (`uap tune`) can't foresee everything; this catches the failures that only show up live, escalating a small model exactly when it starts to struggle. See [LLM Self-Tuning](SELF_TUNING.md).
+
 ---
 
 ## Memory & Context

package/docs/guides/DELIVER.md

@@ -51,6 +51,22 @@ local or frontier — runs the build to 100% without stopping. See
 
 ---
 
+## Big builds: decompose → orchestrate → epics → contracts-first
+
+For a mission too large to hold in one context, `deliver` scales down the context each turn actually needs — this is what lets a small-context local model compose a system it could never see all at once.
+
+- **`--decompose`** splits the mission into sequential phases, each converged by its own loop (auto for long, complex instructions; `--no-decompose` forbids it).
+- **`--orchestrate`** runs those phases through the **blackboard orchestrator** with *minimal* per-task context — each task sees only its goal + its direct-dependency outputs. Implies `--decompose`.
+- **`--epics`** runs a massive mission as a sequence of **epics, each a fresh session** — only prior epics' summaries are injected, never their full code — looped until each is accepted (auto for very long missions; `--no-epics` disables).
+
+**Contracts-first** (on by default inside epic/decompose runs; `UAP_DELIVER_CONTRACTS=0` disables): the first epic plans the shared types, interfaces, and registry APIs the rest build against. Once accepted, its files are **locked read-only** so later epics build against frozen signatures and can't drift them. The public surface is *extracted and verified against emitted source* — only names proven present are recorded — which is what makes cross-module composition reliable without holding every module in context.
+
+**Scaffold-then-fill** (on by default in phased runs; `UAP_DELIVER_SCAFFOLD=0` disables): a large phase is split into a **scaffold** phase that emits the compiling skeleton (complete public signatures, wired imports/exports, stub bodies — build/typecheck must pass) and a **fill** phase that implements the logic *without changing any signature*. The skeleton keeps the build green while the details land.
+
+Interrupted a long run? **`--resume <id|latest>`** picks up a durable run from `.uap/deliver-runs` where it left off.
+
+---
+
 ## Auto-optimization
 
 By default every task is **classified by complexity** and the matching convergence aids turn on automatically (`auto-optimizer.ts`). You don't have to tune anything for the common case. To control it explicitly:
@@ -103,41 +119,106 @@ uap deliver "add the orders endpoint" --until-deployed
 
 ---
 
+## Beyond build & test: proving it runs
+
+Green gates prove code *compiles and tests pass* — not that the artifact actually **runs**. `deliver` adds gates for that:
+
+- **Execution gate** — auto-synthesized as a ladder rung whenever a runnable artifact is detected: it actually *runs* the thing (headless browser / vm-dom / child-process) and fails the turn on a runtime error, a blank canvas, or a static frame. Catches "declared done but never ran."
+- **Acceptance judge** (`--acceptance`) — after the objective gates pass, an LLM judges the spec's *behavioral completeness* from the code + runtime evidence and feeds any unmet requirements back so the loop finishes the spec. Pair it with **`--evaluator-model <preset>`** to have a *different* model judge than the one that implemented (separate generator from evaluator — the "barbell" strategy).
+- **Self-gate** — when a project has **no** detectable gates, `deliver` authors a task-specific acceptance gate as a fallback so there is always something to converge against (on by default; `--no-self-gate` disables, `--force-self-gate` authors one even when project gates exist).
+
+## Resilience: baseline-delta, migrations & repair escalation
+
+Long autonomous runs fail in predictable ways; `deliver` has a guard for each:
+
+- **Baseline-delta gating** — the full ladder is run **once at mission start**. Any required gate that is *already red at baseline* (a pre-existing failure the mission didn't cause) is demoted to non-blocking and annotated; only **new** regressions (green→red) block delivery. So a pre-existing broken lint or flaky test can't consume every attempt. On by default (`UAP_DELIVER_BASELINE_DELTA=0` or `.uap.json` `deliver.baselineDelta:false` to disable).
+- **Migration-validation gate** — when a `migrations/` dir with `.sql` files exists, a ladder rung runs the migrations against an **ephemeral throwaway Postgres container** before they can ship broken. Skips cleanly (never fails) when Docker/`sqlx-cli` isn't available.
+- **Repair escalation** — a circuit breaker for the compile-error death spiral: when the compile-error count *grows* across consecutive turns, the loop stops mission work and runs **one narrow "make it compile, change nothing else" pass** — in a fresh focused session, on the `--escalate-model` when configured — then resumes.
+
 ## Options
 
+**Loop & termination**
+
 | Flag | Purpose |
 |---|---|
 | `--max-turns <n>` | Maximum execute→verify iterations before until-delivered extension (default `5`) |
 | `--no-until-delivered` | Disable loop-until-delivered (ON by default: extends past `--max-turns` to the ceiling, stopping on stagnation) |
 | `--ceiling <n>` | Hard turn ceiling for until-delivered (1–50, default `30`) |
+| `--no-lazy` | Skip the lazy bare first attempt (by default one bare turn runs before the convergence aids engage) |
+| `--resume <id>` | Resume an interrupted durable run: a run id or `latest` (`.uap/deliver-runs`) |
+
+**Executor**
+
+| Flag | Purpose |
+|---|---|
+| `--executor <mode>` | Per-turn executor: `blind` (one completion), `agentic` (tool-using read/list/bash/write loop), or `auto` (agentic when there's repo context/gates to inspect) — default `auto` |
+| `--allow-bash` | Permit the agentic executor's `run_bash` tool when NOT under `uap sandbox` (off by default; auto-enabled under sandbox) |
+
+**Models & routing**
+
+| Flag | Purpose |
+|---|---|
 | `-m, --model <preset>` | Model preset (default `$UAP_DELIVER_MODEL` or `qwen35-a3b`) |
+| `--routing <preset>` | Pick the executor per task complexity from a routing preset (e.g. `cost-tiered`, `speed-tiered`); ignored when `--model` is set (`$UAP_DELIVER_ROUTING`) |
 | `--endpoint <url>` | Override the model endpoint (OpenAI-compatible `/v1`) |
-| `--escalate-model <preset>` | Stronger model for escalation (default `$UAP_ESCALATE_MODEL`) |
+| `--escalate-model <preset>` | Stronger model for the escalation/repair ladder (default `$UAP_ESCALATE_MODEL`) |
 | `--temperature <t>` | Sampling temperature (default: execution-profile value) |
+
+**Gates & acceptance**
+
+| Flag | Purpose |
+|---|---|
 | `--gates <ids>` | Gate subset: `build,typecheck,test,lint` |
-| `--tiers <list>` | Explicit local tiers to run, e.g. `fast,integration,deploy-dev` (overrides auto-detection) |
+| `--acceptance` | After objective gates pass, judge spec behavioral completeness (LLM) and feed unmet requirements back |
+| `--evaluator-model <preset>` / `--evaluator-endpoint <url>` | Judge the acceptance gate with a DIFFERENT model than the implementer (generator≠evaluator) |
+| `--no-self-gate` | Disable the self-authored acceptance-gate fallback (on by default when no project gates are detected) |
+| `--force-self-gate` | Author a task-specific acceptance gate even when project gates exist |
+| `--keep-best` | Never regress: snapshot first, roll back if the run ends with a worse required-gate score |
+
+**Tiers & CI/deploy feedback**
+
+| Flag | Purpose |
+|---|---|
+| `--tiers <list>` | Explicit local tiers, e.g. `fast,integration,deploy-dev` (overrides auto-detection) |
 | `--integration` / `--no-integration` | Run the integration tier (on by default when a suite is detected) |
 | `--deploy-dev` / `--no-deploy-dev` | Run a local dev deploy + smoke tier (compose up → smoke → teardown) |
-| `--watch-ci` | After local-green, commit + push the worktree branch and watch CI; re-converge on failure |
+| `--watch-ci` | After local-green, commit + push the worktree branch and watch CI; re-converge on failure (never pushes master/main) |
 | `--until-deployed` | Imply `--watch-ci` and require CI + staging/prod deploy jobs green before exiting 0 |
 | `--ci-passes <n>` | Max CI re-converge passes on failure (1–10, default `2`) |
 | `--ci-timeout <minutes>` | CI watch budget in minutes (1–120, default `20`) |
+
+**Big builds (decompose → orchestrate → epics)**
+
+| Flag | Purpose |
+|---|---|
+| `--decompose` / `--no-decompose` | Split the mission into sequential phases, each converged by its own loop (auto for long complex tasks) |
+| `--orchestrate` / `--no-orchestrate` | Run decomposed tasks through the blackboard orchestrator with MINIMAL per-task context (implies `--decompose`) |
+| `--epics` / `--no-epics` | Run a massive mission as a sequence of fresh-session epics until each is accepted (auto for very long missions) |
+
+**Exploration & quality aids**
+
+| Flag | Purpose |
+|---|---|
 | `--candidates <n>` | Best-of-N exploration: candidates per turn (2–8) |
-| `--critic` | Structured critique of failed turns |
+| `--critic` | Structured critique of failed turns (extra model call per failure) |
 | `--practices` / `--no-semantic` | Inject/record best-practice cards (keyword retrieval with `--no-semantic`) |
-| `--escalate` | Escalation ladder on stagnation |
+| `--escalate` | Escalation ladder on stagnation (widen exploration → critic → stronger model) |
 | `--ideate` / `--ideate-project <name>` | Divergent ideation strategy seeds |
-| `--halo` | Emit HALO spans (analyze with `uap harness analyze`) |
-| `--coordinate` | Register the run with the coordination layer |
-| `--deploy` | On success, queue a commit of applied files into the deploy batcher |
 | `--optimize` | Enable every convergence aid |
-| `--no-auto` | Disable dynamic optimization |
+| `--no-auto` | Disable dynamic optimization (aids are auto-selected by task complexity by default) |
+
+**Integration & run control**
+
+| Flag | Purpose |
+|---|---|
 | `--no-protect-tests` | Allow the model to modify pre-existing test files (protected by default) |
 | `--guidance-file <path>` | Poll a file each turn for live operator guidance |
+| `--halo` | Emit HALO spans (analyze with `uap harness analyze`) |
+| `--coordinate` | Register the run with the coordination layer (announce, heartbeat, overlap detection) |
+| `--deploy` | On success, queue a commit of applied files into the deploy batcher |
 | `--project-root <path>` | Project whose gates define delivery (default: cwd) |
 | `--dry-run` | Show detected gates and plan without calling the model |
 | `--json` | Emit a JSON result |
-| `--keep-best` | Never regress: snapshot the project first, roll back if the run ends with a worse required-gate score |
 
 ### `--keep-best` snapshots
 

package/docs/guides/DROIDS_AND_SKILLS.md

@@ -156,7 +156,7 @@ A skill is a reusable workflow. Skills live in directories under
 [`.factory/skills/`](../../.factory/skills/), each containing a `SKILL.md` file
 with frontmatter (`name`, `version`, `compatibility`) and the workflow body.
 
-UAP ships **32 skills** in `.factory/skills/`, including:
+UAP ships **36 skills** in `.factory/skills/`, including:
 
 - **Coordination & workflow** — `uap-coordination`, `uap-tasks`,
   `uap-worktree`, `worktree-workflow`, `parallel-expert-review`, `batch-review`

package/docs/guides/LOCAL_MODELS.md

@@ -162,6 +162,10 @@ The client then talks the Anthropic protocol to the proxy, which forwards
 OpenAI requests to llama.cpp. The proxy supports streaming and tool-call
 translation.
 
+For the full picture — the `uap proxy` lifecycle, the reliability guardrails
+that keep a small model from wedging, security, and serving recipes — see the
+**[Inference Proxy guide](PROXY.md)**.
+
 ## Related
 
 - [Deploy Batching](./DEPLOY_BATCHING.md) — what `uap deliver --deploy` queues.

package/docs/guides/PROXY.md

@@ -0,0 +1,202 @@
+# The Inference Proxy
+
+UAP ships a local **inference proxy** — an Anthropic-Messages-compatible gateway
+that sits in front of a local llama.cpp/Qwen backend, translates between the
+Anthropic wire format and llama's OpenAI-compatible API, and applies a layer of
+**reliability guardrails** on the way through. It's what lets a Claude-native
+harness (Claude Code, Factory, …) drive a local model, and it's where most of
+the "keep a small model from wedging" logic lives.
+
+> Code: [`tools/agents/scripts/anthropic_proxy.py`](../../tools/agents/scripts/anthropic_proxy.py)
+> (the server), `tools/agents/scripts/confidence_escalation.py` (serving
+> recipes), and `src/cli/proxy.ts` / `src/cli/proxy-lifecycle.ts` (lifecycle).
+> Related: [Local Models](LOCAL_MODELS.md) · [Configuration Reference](../reference/CONFIGURATION_REFERENCE.md).
+
+---
+
+## What it does
+
+- **Protocol translation** — accepts Anthropic `POST /v1/messages` and forwards
+  OpenAI-style requests to the local rail (`LLAMA_CPP_BASE`, e.g.
+  `http://localhost:8080/v1`), streaming and tool-calls included.
+- **Reliability guardrails** — detects and breaks the failure modes a small
+  local model falls into (act/review loops, "I'm stuck" spirals, endless
+  exploration with no deliverable) so a run terminates instead of burning turns.
+- **Context management** — scales token counts so the client compacts *before*
+  the local rail overflows, and prunes as a backstop.
+- **Graceful degradation under load** — pool saturation returns a proper
+  Anthropic `529 overloaded_error` with `retry-after` rather than failing hard.
+- **Serving recipes** — optional confidence/fusion escalation to a stronger
+  judge model, plus per-request routing from the reactor and the self-tuning
+  real-time adaptor.
+
+### Endpoints
+
+| Route | Purpose |
+|---|---|
+| `POST /v1/messages` (+ `/anthropic/v1/messages`) | Main Anthropic Messages endpoint (local model + guardrails) |
+| `POST /v1/messages/count_tokens` | Token counting, scaled so the client compacts before the local rail overflows |
+| `POST /v1/chat/completions` | OpenAI-compatible surface |
+| `GET /v1/models` | Model list (honors the `__local_only__` passthrough sentinel) |
+| `GET /health` | Liveness (probes the upstream; stays unauthenticated) |
+| `GET /v1/context` | Per-session token-usage / utilization / guardrail telemetry (dashboards & debug) |
+
+---
+
+## Lifecycle: `uap proxy`
+
+The proxy is **reference-counted and session-scoped**. Hooks call `ensure` when a
+session starts and `release` when it ends, so it starts on demand and stops when
+the last session leaves — but it **never** kills a proxy that systemd manages or
+that other sessions are still using.
+
+```
+uap proxy [ensure | release | status | start | stop | restart | enable | disable]
+```
+
+| Subcommand | What it does |
+|---|---|
+| `ensure` | Start the proxy if none is running, or **adopt** a running one; register this session as a client |
+| `release` | Deregister this session; stop the proxy **only if** we spawned it as a plain process and no other client remains |
+| `status` | Report whether it's running, how (systemd vs spawned), the port, and client count (`--json` for machine-readable) |
+| `start` / `stop` / `restart` | Explicit control (e.g. `restart` after changing `PROXY_*` in `.uap/proxy.env`) |
+| `enable` / `disable` | Toggle `.uap.json` `proxy.autostart` so hooks auto-start it (or not) |
+
+| Flag | Purpose |
+|---|---|
+| `--client <id>` | Client/session id (defaults to the session env or parent pid) |
+| `--client-pid <n>` | Long-lived agent pid for liveness (hooks pass `$PPID`) |
+| `--port <n>` | Proxy port (default `4000` / `$PROXY_PORT`) |
+| `--if-enabled` | No-op unless `.uap.json` `proxy.autostart` is `true` (hook-safe) |
+| `--quiet` / `--json` | Suppress output (hooks) / machine-readable status |
+
+**How it's managed.** When available, the proxy runs as the systemd unit
+`uap-anthropic-proxy.service`, reading its environment from
+`~/.config/uap/anthropic-proxy.env`; a plain spawned proxy seeds the same file
+for parity. The proxy also loads project-local `.uap/proxy.env` at startup
+(real environment always wins). PID reuse is defended with a `/proc/<pid>`
+start-time token so `release` never kills an unrelated process that inherited an
+old pid. Everything hook-driven **fails open** — if the proxy won't start, the
+agent just runs without it.
+
+```bash
+uap proxy status --json
+uap proxy restart          # pick up new PROXY_* values from .uap/proxy.env
+uap proxy enable           # let session hooks autostart it
+```
+
+---
+
+## Security
+
+- **Loopback by default.** The proxy binds `127.0.0.1` (`PROXY_HOST`). This is
+  deliberate: an unauthenticated `0.0.0.0` listener would let any host on your
+  LAN drive the local model — and reach any cloud passthrough — so local-only is
+  the safe default.
+- **Shared-secret auth for LAN exposure.** To run it as a shared service, set
+  `PROXY_HOST=0.0.0.0` **and** a `PROXY_AUTH_TOKEN`. With a token set, every model
+  route requires `Authorization: Bearer <token>` (or `X-Uap-Proxy-Token`), checked
+  in constant time; `/health` stays open. Never expose it beyond loopback without
+  a token.
+- **Passthrough credentials.** For requests routed to the cloud, the proxy
+  forwards the client's OAuth `Authorization: Bearer` verbatim and does not also
+  attach an `x-api-key` (Anthropic rejects both).
+
+---
+
+## Reliability guardrails
+
+These are the heart of the proxy — the logic that keeps a weaker model from
+wedging. Most are **on by default** and tuned via `PROXY_*` env vars (persisted
+in `.uap/proxy.env` or the systemd EnvironmentFile). The high-signal knobs are in
+the [Configuration Reference](../reference/CONFIGURATION_REFERENCE.md); the full
+set is below.
+
+### Termination breakers (on by default)
+
+| Guardrail | Env (default) | Behavior |
+|---|---|---|
+| **Loop-breaker** | `PROXY_LOOP_BREAKER` (on) | Detects act/review cycles + no-progress streaks and releases `tool_choice` to `auto` so the model can actually terminate |
+| **Stuck-break** | `PROXY_STUCK_BREAK` (on) | When the model self-reports "stuck in a loop" or hammers a rate-limited host, forces a terminal turn |
+| **Deferral-break** | `PROXY_DEFERRAL_BREAK` (on) | The inverse: a no-tool turn that *defers* work ("I need more exploration cycles") is forced to act on the next turn |
+| **Recon-convergence** | `PROXY_RECON_CONVERGENCE_THRESHOLD` (40) | After N tool-using turns with **no** write/deliverable, inject "stop exploring, produce the deliverable"; escalates to stripping tools if it persists (0 disables) |
+| **Hard-finalize** | `PROXY_HARD_FINALIZE_TURNS` (40) | Absolute turn cap before a forced finalize |
+| **MANDATE-DELIVER** | `PROXY_MANDATE_DELIVER` (on) | On the delivery-enforcer block marker, pin `tool_choice` to `deliver` so the next turn *must* route through the gated path — makes routing binding for weak models |
+
+### Context & compaction
+
+| Env (default) | Behavior |
+|---|---|
+| `PROXY_CONTEXT_WINDOW` (0 = auto) | Explicit local context window; 0 derives it from the live rail |
+| `PROXY_COUNT_TOKENS_SCALE` (auto) | Scales the reported token count so the client auto-compacts before the local rail overflows |
+| `PROXY_CONTEXT_PRUNE_THRESHOLD` (0.85) / `PROXY_CONTEXT_PRUNE_TARGET_FRACTION` (0.50) | Backstop pruning: prune at 85% of the window, land the session at ~50% |
+
+### Connection health & backpressure
+
+| Env (default) | Behavior |
+|---|---|
+| `PROXY_MAX_CONNECTIONS` (20) | httpx pool size; a large pool + 529 backoff absorbs connection churn gracefully |
+| **529 backpressure** (no toggle) | A pool timeout returns HTTP **529 `overloaded_error`** with `retry-after` — pure graceful degradation, not a hard failure |
+| `PROXY_CLOSEWAIT_REAP_INTERVAL` (0 = **off**) | Opt-in CLOSE-WAIT reaper (pool self-heal); off by default because pool-swap churn can harm a saturated upstream |
+| `PROXY_TOOL_NARROWING` (**off**) | Opt-in: drop cycling/banned tools from the set on loops — always keeps the Bash/WebFetch/Agent escape hatch + write tools (a floor invariant that never strands the agent) |
+
+> **Off-by-default knobs to know:** `PROXY_TOOL_NARROWING`, the CLOSE-WAIT reaper
+> (`PROXY_CLOSEWAIT_REAP_INTERVAL=0`), `PROXY_POOL_SWAP_ON_SATURATION`, and the
+> serving recipes (`PROXY_CONFIDENCE_ESCALATE`). Everything else above is on.
+
+---
+
+## Serving recipes & escalation
+
+The proxy can run a bounded **micro-agent recipe** in front of the local model —
+escalating low-confidence or hard turns to a stronger **judge** model — behind
+the same single model API. It is **off by default and fails open**.
+
+| Env (default) | Meaning |
+|---|---|
+| `PROXY_CONFIDENCE_ESCALATE` (off) | Master switch for serving recipes |
+| `PROXY_RECIPE` (auto) | `single \| confidence \| fusion` (+ `ratings \| remom`); `auto` routes by signal |
+| `PROXY_CONFIDENCE_THRESHOLD` (0.5) | Below this confidence, escalate the turn to the judge |
+| `PROXY_FUSION_N` (3) | Candidates the fusion recipe samples before the judge picks/merges (2–6) |
+| `PROXY_ESCALATE_MODEL` / `PROXY_ESCALATE_ENDPOINT` / `PROXY_ESCALATE_API_KEY` | The stronger judge backend |
+
+A judge-dependent recipe requires a judge **distinct from** the primary model —
+a same-model "qwen judging qwen" setup downgrades to `single` unless
+`PROXY_ALLOW_SELF_JUDGE=1`. The judge model id is configured on the harness side
+via `recipes.judge.model` (see the [recipes settings](../reference/CONFIGURATION_REFERENCE.md));
+`uap setup` / `uap config` seed the `PROXY_ESCALATE_*` triple into the proxy env.
+
+### Cross-process signals
+
+Because the proxy freezes its `PROXY_*` env at startup and has no reload
+endpoint, two features steer it **per request** via small signal files (each a
+best-effort read, TTL ~180s, never fatal):
+
+- **Recipe signal** — the harness [Reactor](../design/UAP_REACTOR.md) writes its
+  per-prompt routing decision to `~/.cache/uap/recipe-signals/`; the proxy prefers
+  that fresh signal over re-deriving complexity itself.
+- **Adaptation signal** — the [LLM self-tuning](SELF_TUNING.md) real-time adaptor
+  writes per-session adjustments (escalate / recipe / recon threshold / force
+  synthesis) to `~/.cache/uap/adaptation-signals/`. Consumed when
+  `PROXY_REALTIME_ADAPT` is on (**auto-on**; opt out with `0`).
+
+---
+
+## Configuration
+
+Proxy settings are `PROXY_*` environment variables. Persist them with
+`uap config set` (which writes `.uap/proxy.env`) and `uap proxy restart` to apply:
+
+```bash
+uap config set PROXY_RECON_CONVERGENCE_THRESHOLD 30
+uap config set PROXY_AUTH_TOKEN "$(openssl rand -hex 16)"
+uap proxy restart
+```
+
+The curated high-impact subset is documented in the
+[Configuration Reference](../reference/CONFIGURATION_REFERENCE.md#proxy);
+the exhaustive list lives as module-level constants in `anthropic_proxy.py`.
+
+> **Note:** the upstream backend default in the checked-in scripts
+> (`LLAMA_CPP_BASE`) points at a specific host/port — always set it (or your
+> model's `endpoint`) to your own llama.cpp/Qwen server.

package/docs/reference/CLI.md

@@ -29,7 +29,7 @@ runs, keeping `--help` fast.
 | Command | Purpose |
 |---------|---------|
 | [`init`](#init) | Initialize agent context in the current project |
-| [`setup`](#setup) | One-command setup: init + Qdrant + Python deps + index patterns |
+| [`setup`](#setup) | Guided setup wizard (arrow-key), or `--profile maximum\|minimal\|custom`; backs up instruction files, extracts custom content |
 | [`analyze`](#analyze) | Analyze project structure and emit metadata |
 | [`generate`](#generate) | Generate or update CLAUDE.md and related files |
 | [`update`](#update) | Update CLAUDE.md, memory system, and related components |
@@ -41,6 +41,19 @@ runs, keeping `--help` fast.
 | [`expert-route`](#expert-route) | Recommend an expert droid chain for a task |
 | [`deliver`](#deliver) | Convergence loop: iterate a model against gates until delivery |
 | [`harness`](#harness) | HALO harness optimization over execution traces |
+| [`bench`](#bench) | Controlled paired (UAP-on vs UAP-off) benchmark with CIs |
+| [`self-harness`](#self-harness) | Self-improving harness: mine failures → propose → validate → commit |
+| [`tune`](#tune) | LLM self-tuning: raise a small model toward Opus by tuning UAP flags |
+| [`verify`](#verify) | Runtime verification gate: prove changed code actually runs |
+| [`config`](#config) | Inspect and change every UAP setting (`.uap.json` / `.uap/proxy.env`) |
+| [`design`](#design) | DESIGN.md interrogation, lint, and the off-token UI gate |
+| [`proxy`](#proxy) | Reference-counted, session-scoped local inference proxy lifecycle |
+| [`orchestrator`](#orchestrator) | Toggle the long multi-turn deliver orchestrator |
+| [`handsfree`](#handsfree) (`hf`) | Hands-free persistence: loop any model to a 100% ledger |
+| [`challenge`](#challenge) | Open multi-agent challenge with a significance-gated leaderboard |
+| [`sandbox`](#sandbox) | Run a command with a kernel-enforced writable-dir boundary |
+| [`react`](#react) | Resolve dynamic experts/skills/patterns for a lifecycle event (JSON) |
+| [`status`](#status) | Show HALO trace collection state |
 | [`ideate`](#ideate) | Divergent ideation (open-collider) for hard problems |
 | [`coord`](#coord) | Agent coordination and status |
 | [`agent`](#agent) | Agent lifecycle, work coordination, and communication |
@@ -379,6 +392,254 @@ The trace file defaults to `$UAP_HALO_TRACE_PATH` or `.uap/halo/traces.jsonl`.
 
 ---
 
+## `bench`
+
+Controlled paired benchmark — hold the base model + agent constant and toggle
+UAP on/off over the same real-gate suite and seeds, then report paired deltas
+with confidence intervals, a McNemar gate-value 2×2, and a cost–accuracy Pareto.
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `paired` | `--suite`, `--adapter <mock\|opencode\|claude\|mini\|raw\|deliver>`, `--model`, `--epochs`, `--concurrency`, `--ablation`, `--lazy`, `--seed`, `--iterations`, `--rope-margin`, `--out`, `--json` | Run the UAP-on vs UAP-off A/B; writes `records.jsonl` + Markdown/JSON reports |
+
+```bash
+uap bench paired --adapter opencode --model qwen36-a3b --epochs 5
+uap bench paired --ablation            # leave-one-out per UAP component
+```
+
+See [Paired Harness](../benchmarks/PAIRED_HARNESS.md) for the methodology.
+
+---
+
+## `self-harness`
+
+Self-improving harness: mine model-specific failures from traces, propose a
+bounded, reversible modification (the "Mod" DSL), validate it with a real paired
+bench, and — with `--apply` — commit it and snapshot a versioned profile.
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `analyze` | `--records`, `--env`, `--transfer`, `--json` | Mine weaknesses + propose candidate Mods (read-only) |
+| `run` | `--records`, `--suite`, `--heldout`, `--adapter`, `--model`, `--epochs`, `--max-candidates`, `--apply`, `--json` | The full loop; `--apply` commits + snapshots |
+| `transfer` | `--transfer`, `--json` | List the cross-model transfer store |
+| `mine-prod` | `--traces`, `--unit`, `--since`, `--pending`, `--json` | Mine production traces → enqueue proposals (never applies) |
+| `pending` / `prune` | `--pending`, `--transfer`, `--json` | Inspect / ablation-prune the queue + store |
+| `tune` | (alias of `uap tune`) | The LLM/GP flag self-tuning loop |
+
+```bash
+uap self-harness run --suite benchmarks/suites/real-gate --adapter opencode
+```
+
+See [Self-Harness (design)](../design/SELF_HARNESS.md).
+
+---
+
+## `tune`
+
+LLM self-tuning — raise a small model (e.g. qwen3.6) toward Opus-level output by
+tuning UAP's own flag surface (recipes, hands-free, memory, concurrency, proxy
+guardrails) with a benchmark-validated closed loop. An LLM proposes small flag
+changes when a judge model is configured; otherwise a Gaussian-process Bayesian
+optimizer picks the next config. `uap self-harness tune` is an alias.
+
+| Flag | Purpose |
+|------|---------|
+| `--model <id>` | Executor model family to tune (default `qwen36-a3b`) |
+| `--adapter <name>` | `mock \| opencode \| claude \| mini \| raw \| deliver` |
+| `--judge <id>` | Judge/tuner model; else `recipes.judge.model`, else GP-only |
+| `--phase <name>` | Force one search phase: `coarse \| medium \| fine \| combinatorial` |
+| `--max-iterations <n>` | Tuning-loop budget (default 6) |
+| `--epochs`, `--concurrency`, `--iterations`, `--seed` | Paired-bench + stats controls |
+| `--apply` | Commit accepted configs + save the profile (default: dry-run) |
+| `--json` | Machine-readable result |
+
+```bash
+uap tune --model qwen36-a3b --adapter opencode --judge opus-4.8 --apply
+uap tune --adapter mock --max-iterations 3 --json     # offline smoke test
+```
+
+See [LLM Self-Tuning](../guides/SELF_TUNING.md).
+
+---
+
+## `verify`
+
+Run the project's completion gates — including the **runtime execution gate**
+that actually runs the changed code — against the current files and report
+pass/fail. This is what the Stop hook calls to block "done" on code that never
+ran.
+
+| Flag | Purpose |
+|------|---------|
+| `-d, --dir <path>` | Project directory (default: cwd) |
+| `--strict` | Treat "no verifiable gates" as a failure (fail-closed) |
+| `--runtime-only` | Run only the cheap runtime execution gate |
+| `--full` | Also run the expensive integration / deploy-dev tiers |
+| `--gates <ids>` | Comma-separated rung subset (e.g. `build,test,execution`) |
+| `--acceptance <specfile>` | LLM acceptance gate: judge behavioral completeness vs a spec |
+| `--no-visual` | Skip the headless visual gate |
+| `-m, --model`, `--endpoint` | Model + endpoint for the acceptance gate |
+| `--timeout <ms>`, `--json` | Per-rung timeout; JSON output |
+
+```bash
+uap verify --runtime-only          # prove the artifact runs
+uap verify --acceptance spec.md --strict
+```
+
+---
+
+## `config`
+
+Inspect and change every UAP setting from one place — the single source of truth
+is `src/config/settings-registry.ts`, which also generates the
+[Configuration Reference](CONFIGURATION_REFERENCE.md).
+
+| Subcommand | Purpose |
+|------------|---------|
+| `list` | All settings + current values |
+| `get <key>` / `explain <key>` | Read / learn one setting |
+| `set <key> <value>` | Change it (writes `.uap.json`, `.uap/proxy.env`, or prints a shell export) |
+| `doctor` | Flag risky / sub-optimal settings |
+| `wizard` | Interactive expert configurator (also `uap setup --profile custom`) |
+| `docs` | Regenerate `docs/reference/CONFIGURATION_REFERENCE.md` from the registry |
+
+```bash
+uap config set recipes.enabled true
+uap config set realtimeAdapt.enabled false   # opt out of real-time adaptation
+uap config doctor
+```
+
+---
+
+## `design`
+
+DESIGN.md integration: interrogate an existing UI into a design brief, lint UI
+work against it, and gate off-token colors / off-scale spacing.
+
+| Flag | Purpose |
+|------|---------|
+| `-d, --project-dir <path>` | Project directory (default: cwd) |
+| `-o, --out <path>` | Output path for `interrogate` (default `DESIGN.md`) |
+| `--force` | Overwrite an existing DESIGN.md |
+| `-f, --file <path>` | Target file (lint/check) or `"old,new"` (diff) |
+| `--json` | Machine-readable output |
+
+---
+
+## `proxy`
+
+Reference-counted, session-scoped lifecycle for the local inference proxy (the
+Anthropic-compatible gateway in front of a local llama.cpp/Qwen). Hooks
+`ensure`/`release` it per session so it starts on demand and stops when the last
+session leaves — but it never kills a proxy that systemd manages or that other
+sessions still use.
+
+`uap proxy [ensure | release | status | start | stop | restart | enable | disable]`
+
+| Flag | Purpose |
+|------|---------|
+| `--client <id>` | Client/session id (defaults to the session env or parent pid) |
+| `--client-pid <n>` | Long-lived agent pid for liveness (hooks pass `$PPID`) |
+| `--port <n>` | Proxy port (default 4000 / `$PROXY_PORT`) |
+| `--if-enabled` | No-op unless `.uap.json` `proxy.autostart` is true (hook-safe) |
+| `--quiet` / `--json` | Suppress output (hooks) / machine-readable status |
+
+```bash
+uap proxy status --json
+uap proxy restart          # e.g. after changing PROXY_* in .uap/proxy.env
+```
+
+The proxy binds `127.0.0.1` by default; see the proxy `PROXY_*` settings in the
+[Configuration Reference](CONFIGURATION_REFERENCE.md) and [Local Models](../guides/LOCAL_MODELS.md).
+
+---
+
+## `orchestrator`
+
+Toggle the long multi-turn deliver orchestrator (blackboard decomposition +
+epic controller for big autonomous builds). Persists to `.uap.json`
+(`deliver.orchestrate`).
+
+`uap orchestrator [on | off | auto | status]` — `auto` (default) engages it only
+for large multi-epic work. See [Orchestrator & Hands-Free](../guides/ORCHESTRATOR.md).
+
+---
+
+## `handsfree`
+
+Hands-free persistence (alias `hf`): drive any model to keep working until the
+multi-epic build **completion ledger** is 100% done instead of stopping early.
+Auto-on.
+
+`uap handsfree [status | on | off | init | complete <id> | fail <id> | remaining | stop-check]`
+
+| Flag | Purpose |
+|------|---------|
+| `--mission <text>` | Mission text for `init` |
+| `--items <json>` | JSON array of ledger items for `init` |
+
+See [Orchestrator & Hands-Free](../guides/ORCHESTRATOR.md).
+
+---
+
+## `challenge`
+
+Open multi-agent challenge: a shared goal, verified submissions, and a
+significance-gated leaderboard (scores within a ROPE margin of the leader are
+ties, not wins).
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `open` | `--metric <name>`, `--rope-margin <x>`, `--lower-is-better` | Open a challenge with a shared goal + scoring metric |
+| `submit` / `leaderboard` / `status` | — | Submit a verified result / view the ranked board / show state |
+
+```bash
+uap challenge open --metric tps --rope-margin 4
+```
+
+---
+
+## `sandbox`
+
+Run a command with a kernel-enforced workdir boundary (bubblewrap): only the
+current dir + scratch are writable, so writes outside fail at the kernel — the
+boundary `--dangerously-skip-permissions` cannot bypass.
+
+```bash
+uap sandbox -- <command> [args...]
+```
+
+See [Sandbox](../guides/SANDBOX.md).
+
+---
+
+## `react`
+
+Resolve the dynamic UAP capabilities (experts / skills / patterns) for a
+lifecycle event and emit JSON — the engine behind the per-prompt Reactor. Hook
+adapters pipe a JSON `ReactorContext` on stdin; the flags below are for manual
+invocation.
+
+| Flag | Purpose |
+|------|---------|
+| `--event <event>` | `user-prompt \| session-start \| pre-tool \| post-tool \| stop \| session-end` |
+| `--prompt <text>` | Prompt text (when not piping a JSON payload) |
+| `-f, --files <files...>` | Changed files (routing signal) |
+| `--inject-threshold <n>` | Min confidence to inject (default 0.30) |
+| `--auto-spawn-threshold <n>` | Min confidence to auto-spawn an expert (default 0.80) |
+| `--max-inject-chars <n>` | Inject character budget (default 1200) |
+
+See [Reactor (auto-apply)](../design/UAP_REACTOR.md).
+
+---
+
+## `status`
+
+Show HALO trace collection state (enabled, path, span count). `--json` for
+machine-readable output. (Equivalent to `uap harness status`.)
+
+---
+
 ## `ideate`
 
 Divergent ideation (open-collider): generate non-trivial ideas for hard

package/docs/reference/CONFIGURATION_REFERENCE.md

@@ -598,6 +598,30 @@ The serving recipe the proxy applies (mirror of `recipes.recipe`, consumed by th
 
 **Recommendation:** Keep in sync with `recipes.recipe`; `uap setup`/`uap config` write both.
 
+### `realtimeAdapt.enabled`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Real-time flag adaptation (LLM Self-Tuning P4): the reactor emits per-session adjustments from live signals (tool-failure/quality/context/RECON) so the proxy can escalate or converge mid-session. This is the effective master switch — off means no signal is emitted.
+
+**Recommendation:** Leave on. It is conservative (emits only when a live signal breaches a threshold) and is the effective master switch — disabling it turns the whole feature off regardless of the proxy side.
+
+### `PROXY_REALTIME_ADAPT`
+
+| | |
+|---|---|
+| **Where** | `.uap/proxy.env` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Proxy side of real-time adaptation: whether the serving proxy honors a fresh adaptation signal per request. Auto-on; harmless when no emitter is running (no signal to honor).
+
+**Recommendation:** Leave on. Set `false` only to make the proxy ignore adaptation signals even when the reactor emits them.
+
 ## Dashboard
 
 <a id="dashboard"></a>The live analytics server and its mutation token.

package/docs/reference/FEATURES.md

@@ -231,7 +231,19 @@ Hierarchical MCP router that collapses 150+ MCP tools to 2
 | Subsystem | Description |
 |-----------|-------------|
 | Observability (`observability/halo-exporter.ts`) | Emits agent/LLM/tool spans as OTLP/OpenInference JSONL for the HALO engine. Opt-in via `UAP_HALO_TRACE`; zero-overhead when off. |
-| Telemetry (`telemetry/session-telemetry.ts`) | Session-level telemetry capture. |
+| Telemetry (`telemetry/session-telemetry.ts`) | Session-level telemetry capture, incl. per-turn quality estimates for real-time tuning. |
+
+## Self-Improvement (`src/self-harness/`, `src/self-tuning/`) — Feedback
+
+> **Stage: Feedback.** The floor doesn't just log its mistakes — it rewrites its
+> own harness to stop making them. Two closed loops, both validated by the same
+> paired benchmark so a "fix" is never accepted on faith.
+
+| Subsystem | Description |
+|-----------|-------------|
+| Self-Harness (`self-harness/`) | Autonomous mine → propose → validate → decide loop over a bounded, reversible **Mod DSL** (proxy/llama env knobs, scaffold text, middleware, and settings-registry `ConfigMod`s). Cross-model transfer store; online production-trace mining. Fixes **correctness** bugs. `uap self-harness`. |
+| Self-Tuning (`self-tuning/`) | `uap tune` — raises a small model toward Opus by tuning UAP's flag surface against a multi-dimensional **quality** score. LLM-guided proposals with a real Gaussian-process Bayesian-optimizer fallback; atomic rollback-safe flag writes; per-model tuning profiles (bundled qwen3.6 / Opus). |
+| Real-time adaptation (`self-tuning/realtime-adaptor.ts`) | Per-session flag adjustments from live signals (tool-failure / quality / context pressure / RECON loop) over the adaptation-signal channel the proxy honors mid-session. **Auto-on**; opt out with `realtimeAdapt.enabled:false`. |
 
 ## Browser & Benchmarks — QC / Verify
 
@@ -267,7 +279,10 @@ similarity, and system resource detection.
 
 The `uap` CLI is the single door into the whole factory (top-level commands):
 `init`, `setup`, `analyze`, `generate`, `memory`, `patterns`, `worktree`,
-`sync`, `droids`, `expert-route`, `deliver`, `harness` (HALO), `ideate`,
-`coord`, `agent`, `deploy`, `task`, `compliance`, `coordination`, `skill`,
-`update`, `dashboard` (alias `dash`), `model`, `mcp-router`, `hooks`,
-`tool-calls`, `rtk`, `mcp-setup`, `schema-diff`, `policy`, `uap-omp`.
+`sync`, `droids`, `expert-route`, `deliver`, `verify`, `harness` (HALO),
+`bench`, `self-harness`, `tune`, `config`, `design`, `proxy`, `orchestrator`,
+`handsfree` (`hf`), `challenge`, `sandbox`, `react`, `ideate`, `coord`, `agent`,
+`deploy`, `task`, `compliance`, `coordination`, `skill`, `update`,
+`dashboard` (alias `dash`), `model`, `mcp-router`, `hooks`, `tool-calls`,
+`rtk`, `mcp-setup`, `schema-diff`, `policy`, `uap-omp`. See
+[CLI reference](CLI.md) for every command and flag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.137.1",
+  "version": "1.137.3",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",