@miller-tech/uap 2.21.2 → 2.36.1

package/docs/architecture/adr/0012-operator-legibility-surfaces.md

@@ -0,0 +1,175 @@
+# ADR 0012: Operator legibility surfaces — measured pace, local diff view, bench report reader
+
+- Status: Accepted
+- Date: 2026-10-11
+- Spec: the operator's own legibility (S3 local diff view, S1b ETA
+  surfaces + paired bench delta report).
+- Supersedes: none — these are read-only surfaces over telemetry that
+  already existed (the ETA sample stream, git, the paired-bench
+  reports); no schema or authority changes.
+
+## Context
+
+The agent-facing surfaces made the *agent* legible — to
+itself (the self-knowledge card), to the plan, to the operator's consent
+(grants, attention). What never got a surface was the operator's own three
+questions, asked every day on a busy checkout:
+
+1. **"What did the agent actually change around here?"** The answer lives
+   in git, but the honest answer spans three views at once — uncommitted
+   rows with per-file deltas, untracked files, and unpushed commits against
+   a base — and assembling it by hand is exactly the kind of repetitive
+   synthesis operators skip, then regret.
+2. **"How long does this model actually take on this project?"** The ETA
+   sample stream (`delivery/eta.ts` → `model_analytics.db`, keyed
+   model × taskType × complexity) was recorded but nothing *read* it — so the
+   operator (and the agent) kept guessing pace from vibes, which is the
+   failure mode the whole program exists to end.
+3. **"Did the measured delta hold?"** `uap bench paired` writes a full
+   AnalysisReport under `benchmark-results/paired-*/` and nobody ever looks
+   at it again; run-to-run drift (a delta that narrowed, a verdict that
+   flipped) was invisible unless someone diffed JSON by hand.
+
+The bar (unchanged from the reliability ladder): **a number without its
+provenance is noise.** Every surface below is built so it *cannot* print a
+confident guess — thin data says so, unusable runs say so, unknown deltas
+render as `±`, never as `0`.
+
+## Decision
+
+### S1b — the EWMA estimator (`src/delivery/eta-estimate.ts`) and its four surfaces
+
+`ewmaEstimate(samples)` is pure math over a plain array — no store, no
+fs, no clock — so the estimator is unit-testable and deterministic. It
+folds the sample stream **oldest→newest** with a half-life **in samples**
+(default 10, from `1 − 2^(−1/h)`), because the model, the harness, and the
+task mix all drift; recency is the point. The honesty rules are load-bearing
+and pinned by tests:
+
+- **Thin data is not an estimate.** Fewer than 3 successful attempts in the
+  window yields `null` — surfaces show nothing rather than a number
+  invented from noise. 3–5 is `thin` (shown *with a caveat*, never
+  silently); ≥6 is `solid`.
+- **The spread is part of the number.** min/max of the folded successes
+  travel with the estimate; a surface printing "~2 min" without the spread
+  is lying by omission.
+- **Failures are visible.** The fold is over SUCCESS durations (that is
+  what "how long does a completing attempt take" means), but the estimate
+  also carries `attemptsPerSuccess` — and every wall-clock projection
+  (`remainingWallMs`, the handsfree line) scales by it, so a 50%-failure
+  key never presents its successes as its pace.
+
+`estimatePace` is the fail-soft store wrapper (a broken store costs one
+try/catch, never a crash in a surface — same contract as the S1a
+recorder). The four surfaces:
+
+- **`uap eta [--model|--taskType|--complexity|--all|--limit|--half-life|--json]`**
+  (`src/cli/eta.ts`) — one key, or `--all` for every key with history.
+  `--all` *names the too-thin keys* instead of silently omitting them, so
+  the operator knows why a key they expect is missing and what would fill
+  it.
+- **handsfree status** — a remaining-work wall clock for the open ledger
+  items (`pending + failed`), scaled by attempts-per-success, shown only
+  when an estimate exists.
+- **Dashboard models view** — a "Measured Pace" section (top 8 keys by
+  attempts): per-task EWMA, spread, n, success rate.
+- **Reactor injection** (`src/coordination/eta-inject.ts`, keyed
+  `eta:pace`) — the agent's OWN pace as calibrated planning context: fires
+  only on solid estimates, because a thin-data guess would inject exactly
+  the confident noise the block exists to replace.
+
+### S3 — the local diff view (`src/cli/diff.ts`, `uap diff`)
+
+`gatherDiffFacts` is the only impure part: safe-git with `execFileSync`
+**argument arrays** (no shell, no injection surface), a 5s timeout,
+`core.fsmonitor=false -c core.untrackedCache=false` (defeat the stateful
+caches that make status flaky on big repos), and **degrade-never-throw** —
+a non-repo or an unusable git yields `gitError: "git unavailable or not a
+repository"` and the renderer says exactly that, not a stack trace. One
+numstat pass vs HEAD covers staged + unstaged; `git status --porcelain`
+folds status codes onto the rows (worktree code preferred over index code
+— the file's state on disk is what the operator sees) and collects
+untracked paths; renames are normalized before matching because porcelain
+prints `old -> new` while numstat prints `{old => new}`. `renderDiffView`
+is pure and pinned by tests: rows sorted by additions, per-section caps
+with honest "… and N more" counts, honest totals, binary files render `±`
+(unknown — never `0`), ahead/behind against the merge-base, and an
+`inspect:` footer with the follow-up commands.
+
+### The bench report reader (`uap bench report`)
+
+Reports accumulate under `benchmark-results/paired-*/`; the reader answers
+"what did the latest run measure" (`uap bench report`, newest by
+`report.json` mtime with a dirname tiebreak for bulk-copied trees) and
+"did the delta hold" (`--compare`, the two newest runs). It unwraps the
+harness's `{ ablation, report }` on-disk shape. Two rules carried over
+from the reliability ladder, now enforced at the surface:
+
+- **A delta is never printed without its CI, verdict, and McNemar
+  discordant count.**
+- **An unusable run is NO MEASUREMENT.** `discrimination.usable === false`
+  prints the reason and the explicit warning line; the drift view warns
+  when *either* compared run could not measure. `--full` reprints the
+  stored report.md; `--json` emits the raw report.
+
+## Consequences
+
+- The operator's three daily questions each got a one-command answer whose
+  numbers all carry provenance — the same standard the ladder demands of
+  the agent.
+- The S1a sample stream finally has a consumer, which retroactively
+  justifies its deliberate inclusion of synthetic zero-token rows in
+  `recentDurations` (duration/success data is real even when the
+  convergence-loop token totals are not visible at that seam).
+- The estimator is pure and the renderers are pure, so the honesty rules
+  are pinned by fast unit tests rather than by CLI scraping.
+- Test seams are documented as such: `--db` (`uap eta`), the `root`/`cwd`
+  options (`bench report` / `uap diff`) — they exist because vitest
+  workers cannot `process.chdir`, the lesson P4's sandbox-cli tests paid
+  for. No new env vars, no settings-registry entries, no schema changes.
+- Known open surface (named, not hidden): the dashboard's Measured Pace
+  section is exercised through the estimator's tests rather than a
+  dashboard-level test — the dashboard command is environment-heavy and
+  the section is a thin formatting shell over the pinned estimator.
+
+## Review round (all three reviewers' findings fixed in-branch)
+
+The 3-parallel-reviewer pass (code-quality, security, architecture)
+surfaced one design rule and several contract completions, all fixed
+before merge:
+
+- **Absence of data is not a claim of cleanliness.** `uap diff` records
+  which git reads succeeded (`numstatOk`/`statusOk` travel in the facts
+  and the JSON); a failed or timed-out read renders
+  `working tree: UNKNOWN`, never `clean`. Same rule in `bench report`:
+  one dangling symlink in `benchmark-results/` skips that entry, not the
+  whole listing. An unborn repo (fresh `git init`, no commits) is a repo —
+  probed with `--is-inside-work-tree`, not with a HEAD rev-parse, and its
+  branch reads via `symbolic-ref` (which works before the first commit).
+- **`--full` degrades, never throws**: a run dir with `report.json` but
+  no `report.md` (interrupted write) prints the reason, falls back to the
+  delta summary, exits non-zero.
+- **The read surfaces do not materialize what they read.** `estimatePace`
+  gained `requireExisting` — the reactor injection (per-prompt) and the
+  handsfree status line will not create an empty analytics store on a
+  checkout that has no history. The explicit `uap eta` command keeps the
+  store's established open semantics.
+- **One open, not N**: key enumeration moved into the estimator layer as
+  fail-soft `listPaceKeys` (the `--all` path and the enumeration share a
+  single store open; the 50-key cap is named, not silent). The bench
+  reader split into `bench-report.ts` (one command per file, per the
+  repo's own pattern).
+- **Terminal/prompt hygiene at one choke point** (`utils/terminal-safe.ts`):
+  every rendered foreign string (report fields, commit subjects, model
+  ids) is stripped of C0/C1/DEL control bytes; strings that become prompt
+  text are additionally flattened to one line and bounded — a hostile
+  model id cannot carry line-break structure into a block that presents
+  itself as measured data. The raw id still keys the store query.
+- **Loud flags**: garbage `--limit`/`--half-life`/`--max` is refused with a
+  clean error (NaN never reaches the render math), and a `--base` that
+  would reach git as an *option* (refnames cannot start with `-`) is
+  refused rather than passed to argv. `--no-ext-diff` keeps repo-configured
+  diff drivers out of the reads.
+- The prepass's four `execSync` template-literal findings in
+  `src/bin/cli.ts` are pre-existing debt outside this diff, verified
+  untouched by all three reviewers — they belong in a separate cleanup PR.

package/docs/getting-started/INSTALLATION.md

@@ -9,7 +9,7 @@ edits your main branch, writes plausible-but-wrong code, and cheerfully declares
 "done" on something that never actually ran. UAP puts a station at each of those
 break points so the work that comes off the line is trustworthy.
 
-It ships as a single npm package (`@miller-tech/uap`, v1.224.0) that installs the
+It ships as a single npm package (`@miller-tech/uap`, v2.29.0) that installs the
 `uap` CLI. This page gets it onto your machine and wired into your project.
 
 ## Prerequisites

package/docs/guides/AUTOMATIC_FEATURES.md

@@ -132,6 +132,13 @@ Install UAP (`npm i -g universal-agent-protocol`) and every feature below activa
 
 **Why it matters:** Fewer deploys, faster delivery, atomic rollouts.
 
+### Operator Attention Queue (v2.29)
+**What it does:** When a decision is genuinely the operator's (a placement parked with no auto path), the agent records an ASK — context plus the SAFE DEFAULT the asking surface vouches for — and keeps working. The AFK auto-decider adopts recorded safe defaults once the grace window lapses (logged, never silent) and escalates asks that have no safe default.
+
+**When it kicks in:** At session start (the hook sweeps and shows what is waiting, plus what was auto-decided while you were away), on a 60s timer inside the dashboard, and whenever a gated surface parks on a decision.
+
+**Why it matters:** The agent stops on any excuse — or worse, silently decides for you. Now an unattended run keeps moving on decisions that are safe to default, and every adoption is on the record (`uap attention list/decide`; `UAP_ATTENTION_OFF=1` silences the rail).
+
 ---
 
 ## Long-Task Autonomy (Hands-Free) ✨
@@ -270,6 +277,7 @@ long-running build is progressing — no guesswork.
 | Pattern RAG | ✅ | Every prompt | Battle-tested implementations |
 | Coordination | ✅ | Complex tasks | Parallel subagent execution |
 | Deploy batching | ✅ | Multiple changes | Atomic, efficient deploys |
+| Attention queue + AFK decider | ✅ | Operator decisions / session start / 60s dashboard timer | Asks instead of stalls; unattended adoptions logged |
 | HALO | ✅ | Substantial prompts | Automatic task decomposition |
 | Model presets | ✅ | Model selection | Optimal params per model |
 

package/docs/guides/LOCAL_MODELS.md

@@ -1,6 +1,6 @@
 # Running UAP Against Local Models
 
-> UAP v1.224.0
+> UAP v2.29.0
 
 > **🏭 Where this fits:** BUILD — this is the station where a cheap local model
 > flails: plausible-but-wrong code, empty output, or a loop that never lands a

package/docs/guides/PROXY.md

@@ -225,11 +225,12 @@ set is below.
 |---|---|---|
 | **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 |
+| **Error-loop** | `PROXY_ERROR_LOOP` (on), `PROXY_ERROR_LOOP_THRESHOLD` (3), `PROXY_ERROR_LOOP_HARD_LIMIT` (3) | The SAME tool-result error recurring despite varied edits: inject a STOP directive naming the failure — a KNOWN FIX when the class has one (the shared class table: hallucinated skill names, edit-anchor mismatches, identical old/new strings, truncated whole-file writes, policy blocks (where the remedy names the policy layer and never endorses error-named commands), HTTP 404s, missing DB credentials, missing pgcrypto), else the class-matched diagnose remedy. Directives ride the transcript tail as a user-role turn, carry an untrusted-tool-output caveat, and yield to recon-convergence — the 2026-09-24 opencode+qwen log shows 20 hard stops where three system-top re-read directives were ignored en route to each. After HARD_LIMIT ignored directives the session hard-fails (400); a fresh human user turn re-arms. Yields to lockstep when lockstep owns the shape |
 | **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 |
-| **Lockstep escalation** | `PROXY_LOCKSTEP_BREAK` (on), `PROXY_LOCKSTEP_PIVOT_AT` (2), `PROXY_LOCKSTEP_HARD_AT` (4) | The identical tool call failing with the identical error: inject a pivot directive at streak 2, a final warning one fire later, then hard-fail the session (400) at streak 4 instead of drifting (both directives always precede the stop, so it lands at `max(HARD_AT, PIVOT_AT+2)`). Each tier appends to the loop-incident ledger (`UAP_LOOP_INCIDENTS`, default `~/.config/uap/loop-incidents.jsonl`, ~3 records per episode, no rotation) for `uap loops` to inspect and hand to `uap ideate`/`uap deliver`. A fresh human user turn re-arms the guard. Disarmed if `PROXY_ERROR_LOOP=off` or `PROXY_DOUBLING_BREAK=off` (their trackers feed it) |
+| **Lockstep escalation** | `PROXY_LOCKSTEP_BREAK` (on), `PROXY_LOCKSTEP_PIVOT_AT` (2), `PROXY_LOCKSTEP_HARD_AT` (4) | The identical tool call failing with the identical error: inject a pivot directive at streak 2, a final warning one fire later, then hard-fail the session (400) at streak 4 instead of drifting (both directives always precede the stop, so it lands at `max(HARD_AT, PIVOT_AT+2)`). Directives ride the transcript tail as a user-role turn (the salient position; the 2026-10-07 ledger showed system-top directives ignored twice) and carry a KNOWN FIX line for recurring error classes (hallucinated skill names, invalid todo statuses, interrupted calls, edit-anchor mismatches, truncated writes, policy blocks, HTTP 404s, missing DB credentials, missing pgcrypto). Each tier appends to the loop-incident ledger (`UAP_LOOP_INCIDENTS`, default `~/.config/uap/loop-incidents.jsonl`, ~3 records per episode, no rotation) for `uap loops` to inspect and hand to `uap ideate`/`uap deliver`; `uap loops --steer` distills the recurring classes into session-start context — shell harnesses read it from `session-start.sh`, opencode from the plugin's `session.created` handler — so a fresh session never re-enters a logged loop. A fresh human user turn re-arms the guard. Signatures anchor on the decisive traceback line — never the content-free header or exit-code wrapper that unrelated failures share — error tokens glued into larger names (openobserve-error-scan) never count, and a Read payload with no `is_error` flag is content, not failure; the DOUBLING-DOWN pivot rides the same tail placement. Disarmed if `PROXY_ERROR_LOOP=off` or `PROXY_DOUBLING_BREAK=off` (their trackers feed it) |
 
 ### Context & compaction
 

package/docs/guides/SANDBOX.md

@@ -67,13 +67,98 @@ tool whose name starts with a prefix in `PROXY_SANDBOX_UNREACHABLE_PREFIXES` (de
 back to `WebFetch` / local reads instead. (This is the "strip unreachable browser MCP tools
 from sandboxed sessions" behavior.)
 
+## Per-session grants (P4: recorded authority)
+
+`UAP_SANDBOX_ALLOW` widens the boundary but nobody consented on the record. Bridge Phase 4
+adds a **consent ledger**: every extra writable hole is a *grant* — scoped to a session,
+bounded by a TTL, stated with a reason, recorded with who consented, and audit-logged on
+use.
+
+```bash
+# consent to one more hole for this session (reason is REQUIRED)
+uap sandbox grant /var/cache/ccache --session my-session --reason "shared compiler cache" --ttl 3600
+uap sandbox grants [--session <id>] [--json]      # inspect
+uap sandbox revoke sbg-557c11d5                  # take it back
+# then run with the session that owns the grants
+uap sandbox --session my-session -- claude --dangerously-skip-permissions
+```
+
+Rules worth knowing:
+
+- The `--` separator before the command is REQUIRED: without it the sandbox's own flags
+  (`--session`, `--net`, `--ttl`, `--reason`, `--json`) are parsed as sandbox options, not
+  passed through. The grant verbs are intercepted only when there is no `--` —
+  `uap sandbox -- revoke …` runs a binary named `revoke`, not the ledger verb.
+- **Consent comes from the operator, never from inside a sandbox.** `grant`/`revoke` are
+  refused when `UAP_SANDBOX_ACTIVE=1` (that flag is set by the sandbox on the untrusted
+  side); listing stays available. And the ledger + audit files are mounted READ-ONLY into
+  every sandbox namespace — a bind-mounted file cannot be unlinked, replaced, or written
+  inside it — so a sandboxed agent can neither plant grant rows nor forge audit lines.
+- A grant is refused without `--session`, `--reason`, or a grantable target (an existing
+  absolute path; `/`, `/home`, and `$HOME` itself are refused — an over-broad grant IS a
+  sandbox escape, checked after symlink resolution, and re-resolved at plan time to close
+  the swap race).
+- `--ttl` fails CLOSED on garbage: a non-numeric or negative value is refused (not
+  silently upgraded to the 8h default); `--ttl 0` means "expires immediately" (floored to
+  1s). Grants default to **8h** and hard-cap at **7d**; an identical open grant is renewed,
+  not duplicated; expired grants are invisible to the sandbox. Every persist is
+  re-verified against a concurrent writer before success is reported.
+- The ledger lives at the MAIN checkout's `.uap/sandbox-grants.json` (one ledger per
+  checkout, shared by every surface — the ADR 0010 anchor). Every sandbox run appends to
+  `.uap/sandbox-audit.jsonl`: which grants were used, which network mode engaged, and any
+  legacy `UAP_SANDBOX_ALLOW` entries labeled `unrecordedAllow` — still honored, now named.
+  Audit lines carry a monotonic `seq` and the file is BOUNDED: past 12,000 lines it
+  compacts to the 10,000 newest event lines — plus the triggering event and one
+  `audit-compaction` marker recording the drop, so the file lands at 10,002.
+- **Tamper evidence (the ADR 0011 trust anchor).** Every recorded grant/renew/revoke also
+  writes a 0600 anchor OUTSIDE the checkout
+  (`$XDG_STATE_HOME/uap/sandbox-anchors/<hash-of-root>.json`) recording the hash of the
+  sanitized ledger. On load, the ledger is re-hashed and compared: if something with the
+  checkout's write reach changed it outside a recorded consent operation, `uap sandbox
+  grants` stamps the listing INTEGRITY MISMATCH (rows shown but unverified), new grants
+  are REFUSED, and a sandbox session opens ZERO grant-derived holes — the kernel boundary
+  itself is unaffected. Revoking still works (removing authority is the safe direction)
+  and re-anchors the remaining rows as the new baseline, naming the prior mismatch
+  loudly. `UAP_SANDBOX_ANCHOR_DIR` pins the anchor dir (tests, odd layouts).
+- `UAP_SANDBOX_GRANTS_OFF=1` resolves zero grants; `UAP_SANDBOX_GRANTS` pins the ledger
+  file (tests, odd layouts).
+
+See [ADR 0011](../architecture/adr/0011-sandbox-grants-and-network-egress-boundary.md) for
+the design and its trust model (the ledger is shared-write state, so it is sanitized at
+ingest AND on load — a planted row must not become a kernel-writable hole).
+
+## Network egress boundary (P4: `--net off`)
+
+The P0 sandbox shares the host network (the agent must reach the proxy). For runs that
+should have **no network at all** — untrusted code, evals, data-only work — `--net off`
+adds `--unshare-net` with nothing brought up: no TCP, no DNS, not even loopback, at the
+kernel. Any `connect()` fails; a harness that needs the model fails loudly with connection
+refused, which is the boundary working.
+
+```bash
+uap sandbox --net off -- npm test          # kernel-enforced zero egress
+UAP_SANDBOX_NET=off uap sandbox -- ...     # default the mode for every run
+```
+
+Every run's actual mode (`shared` / `off`) is audit-logged. There is deliberately **no
+`--net proxy`** (netns cut with a single hole to the proxy): rootless Linux cannot express
+it — AF_UNIX sockets are network-namespace-scoped, bwrap closes every inherited fd, and
+the userspace network stacks have no outbound allowlist. A boundary that only works with
+the right helper installed would be a suggestion, not enforcement. The full analysis and
+the rejected alternatives live in
+[ADR 0011](../architecture/adr/0011-sandbox-grants-and-network-egress-boundary.md); the
+model-path choke point that DOES hold is the proxy's `PROXY_SOCKET` (0600 AF_UNIX socket,
+plus `uap proxy connect` to re-serve it on local TCP for clients that cannot speak
+AF_UNIX).
+
 ## Escape hatches (operator-only)
 
 | Variable | Effect |
 |---|---|
 | `UAP_SANDBOX_OFF=1` | Run the command as-is, no sandbox (for debugging). |
-| `UAP_SANDBOX_ALLOW=/path:/other` | Extra writable prefixes. |
+| `UAP_SANDBOX_ALLOW=/path:/other` | Extra writable prefixes — UNRECORDED (audited as `unrecordedAllow`; prefer `uap sandbox grant`). |
 | `UAP_SANDBOX_WORKDIR=/path` | Override the resolved workdir. |
+| `UAP_SANDBOX_NET=off` | Default the network mode for every run. Strictly `shared` or `off` — any other value fails LOUD (exit 2), never a silent downgrade to shared. |
 | `PROXY_SANDBOX_UNREACHABLE_PREFIXES` | Change which tool prefixes are stripped (proxy side). |
 
 Treat all of these as trusted-launch-environment settings — they widen the boundary, and
@@ -81,9 +166,11 @@ the model should never be able to set them for itself.
 
 ## Limits (be honest about them)
 
-- **Network is not restricted.** A sandboxed agent can still make outbound network calls;
-  the sandbox is a *filesystem* boundary. Egress control is the proxy's job
-  (`ANTHROPIC_PASSTHROUGH_MODELS=__local_only__` for the cloud path).
+- **Network is restricted only in `--net off` mode.** In the default `shared` mode a
+  sandboxed agent can still make outbound network calls; the sandbox's default is a
+  *filesystem* boundary. Model-path gating is the proxy's job
+  (`ANTHROPIC_PASSTHROUGH_MODELS=__local_only__` for the cloud path, and the
+  `PROXY_SOCKET` unix surface for per-user permission gating).
 - **The writable holes are real writable areas.** Anything under the workdir, `/tmp`, or
   `~/.cache`/`~/.claude`/`~/.npm` can be modified — including caches that persist across
   runs.

package/docs/integrations/MCP_ROUTER.md

@@ -1,6 +1,6 @@
 # MCP Router
 
-`v1.224.0` · `src/mcp-router/`
+`v2.29.0` · `src/mcp-router/`
 
 > **🏭 Where this fits:** Cross-cutting (keeps the belt from jamming) — every
 > station downstream stalls when your agent's context window is choked with

package/docs/plans/model-performance-proof-options.md

@@ -0,0 +1,176 @@
+# Model-performance proof options — how to demonstrate UAP's benefits with honest numbers
+
+**Status:** Proposed (a menu of options, ordered by cost; each names what it
+would prove, what it would NOT prove, and its price — no option starts
+without an explicit go)
+**Date:** 2026-10-12
+**Builds on:** [PAIRED_FINDINGS](../benchmarks/PAIRED_FINDINGS.md) (the honest
+baseline: what has and has not replicated), the
+[reliability ladder](../performance/reliability-ladder.md) (the underpowered-status
+rule), [harness-engineering uplift](harness-engineering-uplift-2026-07-31.md)
+(the mechanism priors), and [K3 uplift validation](k3-uap-uplift-validation.md)
+(the frontier run).
+
+## The claim we are actually proving
+
+The measured history constrains what any honest plan can promise. The paired
+harness established:
+
+- UAP's gate loop delivers a large accuracy lift **only against base agents
+  that do not self-verify** (+20pp vs a single-shot model); against a strong
+  self-verifying harness the pooled accuracy effect is a wash
+  (**Δ 0.0pp [−5.5, +6.9]** — the CI excludes +20pp) at a token cost.
+- UAP never significantly *hurt* accuracy on any surface measured.
+- The one tier where payoff dwarfed cost in the ladder is the hardest one
+  (brutal tier 26.1% → 56.8%, ⚠ underpowered).
+
+So "prove benefits and improvements to model performance" decomposes into
+**four distinct, separately-provable claims** — and each option below is
+mapped to the claim(s) it can actually carry:
+
+| # | Claim | Where it is strongest |
+|---|---|---|
+| C1 | The gate loop lifts weak/non-self-verifying models and hardest-tier tasks | Local paired A/B |
+| C2 | Memory + compounding surfaces lift long-horizon, multi-session work | Unmeasured gap — no existing number |
+| C3 | Operator surfaces (attention, pace) improve throughput/stopping, not accuracy | Unmeasured gap |
+| C4 | Frontier-model uplift under a canonical harness | The K3 plan |
+
+**House rule (applies to every option):** every reported delta carries its
+discrimination status (powered / underpowered / descriptive) and a paired
+design — same model, same tasks, same seeds, only the UAP layer toggled.
+An underpowered delta is labeled "directional, underpowered" and never quoted
+as a finding. Analysis follows the established format: per-task paired rates,
+bootstrap 95% CI, McNemar on discordant pairs.
+
+## The options, ordered by cost
+
+### O1 — Aggregate the delivery-gate telemetry we already record (free)
+
+**Claims:** C1 (descriptive support) · **Cost:** hours of analysis, no runs ·
+**Prereqs:** none — the data exists.
+
+Every `deliver` outcome already records best-%-of-gates per attempt per model
+per technique (the `[deliver]` lessons). Option: aggregate this corpus into a
+measured table — model × technique × tier → gate-pass rate and token cost —
+and publish it as the first *descriptive* performance dataset.
+
+- **Would prove:** where in the model/technique matrix the protocol's gates
+  bind (and where they are overhead) — at population scale, no new runs.
+- **Would NOT prove:** causality (no controlled arm); it is descriptive
+  evidence that directs where to spend O2's controlled runs.
+- **Discrimination status:** descriptive by construction; label it that way.
+
+### O2 — Targeted local paired replication where the payoff was (free, GPU-local)
+
+**Claims:** C1 · **Cost:** GPU-hours only ·
+**Prereqs:** the local stack (`uap bench paired`, the swe-bench-pro-gen suite).
+
+Re-run the paired harness on the current local model stack, UAP on/off, but
+**stratified to the cells the ladder says matter**: the hardest tier (the
+only tier with a measured 2.2× payoff, still underpowered) and a weak
+single-shot arm (the +20pp regime, to check it still holds on today's models).
+
+- **Would prove:** whether C1 survives replication on the current stack with
+  enough attempts to graduate from "underpowered, directional" to a powered
+  finding — the single most valuable upgrade to the ladder.
+- **Would NOT prove:** anything about memory, attention, or frontier models.
+- **Discrimination status:** starts underpowered by design; the run count is
+  chosen from a power calculation on the pilot variance (the existing paired
+  format's bootstrap CI sizes the needed attempts).
+
+### O3 — The multi-session memory experiment (free; the real gap)
+
+**Claims:** C2 · **Cost:** GPU-hours + a task-suite design ·
+**Prereqs:** a k-session task sequence where session k depends on k−1.
+
+The strongest *unmeasured* claim. The harness-engineering ablation gives the
+prior (long-term memory alone: +5.6pp on their harness) and the paired
+findings could not test it (their tasks are single-session). Design: N task
+*sequences* of k sessions each, same model, two arms — UAP memory on vs
+wiped-between-sessions — measuring per-session success, tokens, and the
+session-over-session trend. The paired Δ *and the slope difference* are the
+two numbers.
+
+- **Would prove:** whether UAP's memory system (recall-first, compounding,
+  one store across agents) delivers the multi-session lift C2 claims — this
+  is the repo's most defensible original contribution, so it deserves the
+  repo's most careful experiment.
+- **Would NOT prove:** single-session accuracy (O2's territory).
+- **Discrimination status:** no prior number exists; pilot first, then power
+  up. Sequence design is the hard part and is the first deliverable.
+
+### O4 — Pace-injection stopping behavior (free, unit-level)
+
+**Claims:** C3 · **Cost:** hours · **Prereqs:** the `eta:pace` reactor block
+and `model_analytics.db`.
+
+The measured-pace surfaces inject the agent's own EWMA estimate. Test whether
+the injection changes *stopping* behavior: iterations past green, wall-clock
+to stop, over-iteration rate — paired on/off on the same task set. This is a
+behavior metric (throughput and token waste), deliberately not an accuracy
+claim.
+
+- **Would prove:** whether the pace surface earns its place (faster correct
+  stops = tokens saved with no accuracy loss).
+- **Would NOT prove:** accuracy improvement; a null result here is also
+  publishable (it would justify demoting the surface).
+- **Discrimination status:** underpowered at pilot scale; directional unless
+  powered up.
+
+### O5 — Attention/AFK unattended-throughput (free)
+
+**Claims:** C3 · **Cost:** hours · **Prereqs:** the attention queue + a
+task set with operator-blocking asks.
+
+Measure blocked-on-operator time per session with the queue on vs off (the
+ask-instead-of-stop rail plus the AFK auto-decider): wall-clock to
+completion, number of hard stops, safe-default adoption correctness (each
+adoption is logged, so correctness is auditable).
+
+- **Would prove:** the throughput claim — less idle time, more unattended
+  completions — and that auto-adopted defaults were correct (the safety
+  claim).
+- **Would NOT prove:** accuracy improvement; the correctness audit bounds the
+  risk the throughput number would otherwise hide.
+- **Discrimination status:** descriptive unless task count is powered.
+
+### O6 — Frontier replication under a canonical harness (paid)
+
+**Claims:** C4 · **Cost:** ~$5 smoke → ~$40–90 pilot → ~$900–4,300 full ·
+**Prereqs:** the [K3 plan](k3-uap-uplift-validation.md), verbatim.
+
+The frontier option is already written, phased, and gated on an explicit go:
+Terminal-Bench 2.1, Factory Droid as harness, Kimi K3 via BYOK, paired
+arms (baseline / AGENTS.md protocol / full proxy enforcement). Nothing here
+supersedes it; it is the only option with an external, publicly-anchored
+comparator (K3's published 88.3, harness caveat attached).
+
+- **Would prove:** whether the protocol treatment lifts a frontier model
+  under a harness Factory itself has published methodology for.
+- **Would NOT prove:** attribution to any single UAP surface (it is the
+  whole-protocol treatment); the paired Δ is the claim, the absolute score
+  is the caveated secondary.
+- **Discrimination status:** 89 tasks × 5 attempts is powered for the
+  published convention's effect sizes; report Δ with bootstrap CI + McNemar.
+
+## Suggested order
+
+1. **O1** (free, hours of analysis, no risk) → publishes the descriptive dataset and
+   targets O2's strata.
+2. **O2 hardest-tier replication** (free, targeted) → upgrades the ladder's
+   strongest row from underpowered to powered, or retires it honestly.
+3. **O4 + O5** (free, small) → the C3 throughput numbers, including the
+   demote-if-null honesty.
+4. **O3** (the gap) → design review first (the sequence design is its own
+   deliverable), then pilot, then power up.
+5. **O6** (paid) → only after O1–O3 sharpen what the frontier arms should
+   emphasize, and only on the explicit go the K3 plan already requires.
+
+## What no option here claims
+
+None of these options will show UAP lifting a strong self-verifying agent's
+single-session accuracy — the pooled 0.0pp replication already bounds that
+claim, and the honest headline is the *conditional*: the protocol pays where
+verification, memory, and operator attention are otherwise missing. A plan
+that promised more would be exactly the unpowered-delta marketing the paired
+findings exist to prevent.

package/docs/reference/API.md

@@ -1,6 +1,6 @@
 # UAP Programmatic API Reference
 
-> Public API of the `@miller-tech/uap` package. Version v1.224.0.
+> Public API of the `@miller-tech/uap` package. Version v2.29.0.
 
 > **🏭 Where this fits:** Cross-cutting — the machine parts behind the line.
 > **What it delivers:** when the `uap` CLI isn't the right shape for your job,