@miller-tech/uap 2.21.3 → 2.36.1

package/docs/reference/FEATURES.md

@@ -1,6 +1,6 @@
 # Feature Catalog
 
-> Universal Agent Protocol (UAP) v1.224.0
+> Universal Agent Protocol (UAP)
 
 > **🏭 Where this fits:** Every station on the line — this catalog is the parts list for the whole factory. **What it delivers:** each feature below is mapped to the stage of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md) it protects, so you can see exactly where your agent's work stops being plausible-looking and starts being genuinely shippable.
 
@@ -99,8 +99,9 @@ Multi-model, two-tier (planner/executor) architecture.
 | Planner (`planner.ts`) | Decomposes tasks into subtasks (`TaskPlanner`). |
 | Executor (`executor.ts`) | Runs subtasks with retry/fallback (`TaskExecutor`, `MockModelClient`). |
 | Plan validator (`plan-validator.ts`) | Validates plans before build. |
+| Plan comprehension gate (`plan-readability.ts`) | Deterministic readability rules for plan artifacts — summary-first, abstraction progression, section budgets, jargon density, diagram-required — feeding `uap plan validate`; advisory by default, blocking under `plan.readability.strict`. |
 | Execution profiles (`execution-profiles.ts`, `profile-loader.ts`) | Named model profiles (`UAP_MODEL_PROFILE`). |
-| Analytics (`analytics.ts`) | Per-task token/cost/outcome metrics (`model_analytics.db`). |
+| Analytics (`analytics.ts`) | Per-task token/cost/outcome metrics (`model_analytics.db`), incl. `recentDurations` for the ETA estimator. |
 | OpenAI-compat client (`openai-compat-client.ts`) | OpenAI `/v1`-compatible client (default endpoint `http://localhost:4000/v1`). |
 
 ## Coordination (`src/coordination/`) — Line coordination & Prep
@@ -178,6 +179,14 @@ you'd run by hand.
 | Auto-optimizer (`auto-optimizer.ts`) | Dynamically enables aids. |
 | Ideation / practice / spec-imports | Divergent strategy seeds, best-practice cards, curated project seeds. |
 | HALO trace (`halo-trace.ts`) | Emits HALO spans. |
+| ETA instrumentation (`eta.ts`) | Fail-soft per-attempt wall-clock telemetry to the model-analytics store, keyed (model, task type, complexity) — the sample stream behind task ETAs. |
+| EWMA estimator + pace surfaces (`eta-estimate.ts`, `eta.ts` CLI, `eta-inject.ts`) | The reader for the ETA sample stream: an exponentially-weighted fold of successful-attempt durations (half-life in samples, recency weighs most) with honesty rules enforced — fewer than 3 successes is NOT an estimate (3–5 = thin, caveat shown; ≥6 = solid), the min/max spread always travels with the number, and wall-time projections scale by the key's attempts-per-success so failures are never laundered into pace. Surfaces: `uap eta` (one key or `--all`, naming too-thin keys), the handsfree status wall-clock line, the dashboard's Measured Pace section, and the `eta:pace` reactor block (solid estimates only — a thin-data guess would inject exactly the confident noise it replaces). |
+| Local diff view (`diff.ts`) | `uap diff` — one honest render of what the agent changed around here: uncommitted rows with per-file +N/-N and git status glyphs, untracked paths, totals, and unpushed commits vs the base with ahead/behind and aggregate deltas. Safe-git (execFileSync arg arrays, 5s timeout, fsmonitor/untrackedCache/ext-diff defeated); degrades to an explicit `git:` error line outside a repo, never a crash — and a FAILED or timed-out read renders `working tree: UNKNOWN`, never a false "clean"; binary files render `±` (unknown), not `0`. |
+| Paired bench report reader (`bench-report.ts`) | `uap bench report` — the surface for runs `uap bench paired` already wrote: the newest run's deltas with CI, verdict, and McNemar discordant count always attached; `--compare` shows run-to-run drift (held/flipped verdicts, delta drift); `--full` reprints the stored report.md (degrading to the summary with a reason when it is missing, never a stack trace). A delta is never cited without its discrimination status — an unusable run is NO MEASUREMENT. |
+| Dependency-triggered dispatch (`task-orchestrator.ts`) | Completion-triggered task scheduling: a finished task's slot refills the moment it settles, and a dependent starts as soon as its last dependency succeeds — no wave barrier idles fast siblings behind slow ones. Settlement stays strictly sequential (one task at a time); which task settles next is timing-dependent. |
+| Per-leaf model dials (`decompose.ts`, `orchestrated-mission.ts`, `deliver.ts`) | Phases may carry an optional `model` key (planner-relayed from the mission's own list, or hand-authored); the dial binds that one task's convergence loop to the named preset — fail-closed to the mission model on unknown keys, non-isolated tasks, and the blind-executor path, with a plan-time lint warning at mission start. |
+| Attention queue (`attention.ts`) | The ask-instead-of-stop rail: decisions that are genuinely the operator's (a parked placement awaiting swap approval, grant requests) are recorded with context and a SAFE DEFAULT into the main checkout's `.uap/attention.json`, and the agent keeps working. `uap attention list/ack/decide`; the AFK auto-decider (`sweep` — at session start, on a 60s dashboard timer) adopts recorded safe defaults once the grace window elapses (logged, never silent; a site can pin the deadline to the ask's own expiry) and escalates items without one. Fail-open storage, sanitized at ingest AND on load, `UAP_ATTENTION_OFF` kill switch. |
+| Sandbox grants + egress boundary (`sandbox-grants.ts`, `sandbox.ts`) | Recorded authority for the bubblewrap sandbox: extra writable holes are per-session GRANTS (`uap sandbox grant <path> --session <id> --reason "..."`, TTL 8h default / 7d cap, revocable) from a consent ledger at the main checkout root, audit-logged per run — the legacy `UAP_SANDBOX_ALLOW` env still works but is named UNRECORDED in the audit. The out-of-checkout trust anchor (`sandbox-anchor.ts`) records the sanitized-ledger hash after every recorded mutation; a ledger changed outside a consent operation is detected on load — new grants refused, the session resolves ZERO grant-derived holes (fail-closed), and the grants listing stamps every row unverified. The audit JSONL is seq-stamped and bounded (past 12,000 lines it compacts to the 10,000 newest event lines plus the triggering event and one recorded `audit-compaction` marker — 10,002 total). `uap dashboard` (session view) surfaces the active grants per session with the anchor verdict and a revoke command per grant. `--net off` is the kernel egress boundary: own network namespace with nothing up (no TCP, no DNS, not even loopback) for untrusted code, evals, and data-only work. The proxy's optional `PROXY_SOCKET` (0600 AF_UNIX) is the permission-gated model choke point; `uap proxy connect` re-serves it on local TCP for AF_UNIX-less clients. |
 | Integrity (`integrity.ts`) | Test-protection / integrity guard — stops the model from gutting the tests to "pass." |
 
 ## MCP Router (`src/mcp-router/`) — Cross-cutting (lean context)
@@ -222,6 +231,7 @@ Hierarchical MCP router that collapses 150+ MCP tools to 2
 |-----------|-------------|
 | Analyzers (`analyzers/`) | `analyzeProject(cwd)` builds a `ProjectAnalysis` (languages, frameworks, dirs) from `.uap.json`, git, package files. |
 | Generators (`generators/claude-md.ts`) | Handlebars-based CLAUDE.md / web AGENT.md generation from analysis + discovered skills. |
+| Self-knowledge card (`generators/self-card.ts`, `cli/self.ts`) | Version-pinned digest of UAP's own command/feature surface, built offline from the shipped docs, cached in `.uap/self-card.md`, searchable with `uap self query` — the agent expert on itself. |
 
 ## Observability & Telemetry — Feedback
 
@@ -280,9 +290,11 @@ 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`, `verify`, `harness` (HALO),
-`bench`, `self-harness`, `tune`, `config`, `design`, `proxy`, `orchestrator`,
+`bench` (incl. `bench report` — the paired-run delta reader), `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`,
+`eta` (measured pace), `diff` (local diff view),
 `mcp-setup`, `schema-diff`, `policy`, `uap-omp`. See
 [CLI reference](CLI.md) for every command and flag.

package/docs/reference/PATTERNS.md

@@ -1,6 +1,6 @@
 # Pattern Library Reference
 
-> Universal Agent Protocol (UAP) v1.224.0
+> Universal Agent Protocol (UAP) v2.29.0
 
 > **🏭 Where this fits:** Prep / Routing — before your agent starts cutting, it
 > should pick the right technique for the job. **What it delivers:** the right

package/docs/reference/PLATFORMS.md

@@ -1,6 +1,6 @@
 # Platform & Harness Reference
 
-> Universal Agent Protocol (UAP) v1.224.0
+> Universal Agent Protocol (UAP) v2.29.0
 
 > **🏭 Where this fits:** Cross-cutting — the same line, whichever floor you work
 > on. **What it delivers:** every station of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
@@ -54,6 +54,19 @@ DB-driven policy gate, and (where supported) the hierarchical MCP router.
 > blocks are enforced; Hermes prompts once to approve each hook command
 > (`~/.hermes/shell-hooks-allowlist.json`) unless `hooks_auto_accept: true`.
 
+> **OpenCode seam notes.** OpenCode never runs the shared `.sh` lifecycle
+> scripts — the plugin (`uap-session-hooks.ts`) IS the seam, so two steering
+> surfaces live there: the `session.created` handler injects the
+> `uap loops --steer` digest (recurring loop classes across sessions) beside
+> the memory context, and `session.idle` runs the runtime gate then applies a
+> **bounded auto-continue** when the gate fails — opencode cannot hard-block a
+> stop, so a premature stop with a failing gate is resumed through
+> `client.session.prompt` instead of left wedged. Bounds: never after a proxy
+> hard stop (ERROR-LOOP / LOOP-ESCALATE deliberately ended the session), never
+> past `UAP_AUTO_CONTINUE_MAX` (default 2), never twice for the identical
+> failure. `UAP_AUTO_CONTINUE=0` disables; a stop with green gates is left
+> alone (usually a human interrupt).
+
 ## Lifecycle hooks installed
 
 The shared hook scripts (copied from `templates/hooks/`) are wired into each