@miller-tech/uap 2.21.3 → 2.36.1

package/docs/reference/CLI.md

@@ -1,7 +1,7 @@
 # UAP CLI Reference
 
 > Complete command reference for the Universal Agent Protocol command-line interface (`uap`).
-> Version v1.224.0.
+> Version v2.31.0.
 
 > **🏭 Where this fits:** Every station — this is the control panel for the whole
 > line. **What it delivers:** one binary that drives each stage of your
@@ -43,6 +43,8 @@ runs, keeping `--help` fast.
 | [`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 |
+| [`eta`](#eta) | Measured pace: the EWMA ETA from this project's own recorded attempts |
+| [`diff`](#diff) | Local diff view: uncommitted + untracked + unpushed at a glance |
 | [`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 |
@@ -72,7 +74,9 @@ runs, keeping `--help` fast.
 | [`schema-diff`](#schema-diff) | Detect breaking schema changes between branches |
 | [`policy`](#policy) | UAP policy management |
 | [`quality`](#quality) | Quality-metrics gate: complexity, coverage, CRAP, mutation, duplication, any-types |
-| `plan` | Validate + record plan validation (validate-plan-on-change gate): `uap plan validate [file]` reviews the plan, then stamps |
+| `plan` | Validate + record plan validation (validate-plan-on-change gate): `uap plan validate [file]` runs the deterministic readability scan + model review, then stamps |
+| `self` | Self-knowledge card: build the version-pinned digest of UAP's own command/feature surface (`uap self card`), and answer "how do I X" offline (`uap self query "<question>"`) |
+| `attention` | Operator attention queue: decisions waiting on you (`list`), answer them (`decide`), and the AFK auto-decider that adopts recorded safe defaults (`sweep`) |
 | `principles` | Engineering principles: show them, and answer the backward-compatibility stance (`status \| ask \| compat \| maturity \| show`) |
 | `fidelity` | Inspect or set the maximum-fidelity verification mode (raised gates + always-on visual/vision review) |
 | `interaction` | Interaction gate: derive probes from the requirements and play the artifact through them |
@@ -82,6 +86,7 @@ runs, keeping `--help` fast.
 | `self-harness mine-prod` | Mine weaknesses from production traces (HALO + proxy log) and enqueue proposals for gated validation (never applies) |
 | `self-harness pending` | List queued proposals awaiting validation + gate (from mine-prod) |
 | `bench paired` | Run the paired A/B over a real-gate suite; reports accuracy + efficiency deltas with CIs |
+| `bench report` | Read the newest paired run (deltas with CI/verdict/discrimination); `--compare` for run-to-run drift |
 | `self-harness prune` | Ablation-prune: drop stale / no-longer-paying-off transfer + pending entries |
 | `self-harness run` | Autonomous loop: mine → propose → validate (real paired bench per Mod) → decide → (with `--apply`) commit + versioned snapshot |
 | `self-harness transfer` | List the cross-model transfer store (accepted/rejected Mods keyed by failure signature) |
@@ -489,16 +494,72 @@ with confidence intervals, a McNemar gate-value 2×2, and a cost–accuracy Pare
 | 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 |
+| `report` | `--dir`, `--compare`, `--full`, `--json` | Read the newest paired report (or `--dir`); `--compare` shows run-to-run delta drift. Deltas always carry their CI, verdict, and discrimination status |
 
 ```bash
 uap bench paired --adapter opencode --model qwen36-a3b --epochs 5
 uap bench paired --ablation            # leave-one-out per UAP component
+uap bench report                       # what did the latest run measure
+uap bench report --compare              # did the delta hold since the last run
 ```
 
 See [Paired Harness](../benchmarks/PAIRED_HARNESS.md) for the methodology.
 
 ---
 
+## `eta`
+
+Measured pace: the EWMA ETA for a (model, taskType,
+complexity) key, built **only** from this project's own recorded attempts
+(the ETA sample stream in the model-analytics store). Recent attempts weigh
+more (half-life in samples, default 10); the sample count, the spread, and
+the failure rate always travel with the number — a pace without provenance
+is exactly the confident guess this replaces. Fewer than 3 successful
+attempts is **not an estimate**: the command says so instead of guessing.
+3–5 samples is `thin` (shown with the caveat); 6+ is `solid`. `--all` lists
+every key with history and **names the keys that are still too thin**
+instead of silently omitting them.
+
+| Flag | Purpose |
+|------|---------|
+| `--model <id>` | Model id (default: the active/executor model) |
+| `--taskType <t>` / `--complexity <c>` | Sample key (default `orchestrated`/`medium`) |
+| `--all` | Every key with history: estimates + too-thin keys by name (capped at the 50 most-active keys, truncation named); `--json` with `--all` emits `{keys, estimates, truncated}` |
+| `--limit <n>` / `--half-life <n>` | Sample window (default 50) / EWMA half-life in samples (default 10) — garbage input is refused loudly, never folded |
+| `--db <path>` | Pin the analytics DB path (odd layouts; the default is the project store) |
+| `--json` | Machine-readable: `{key, estimate}` for one key, `{keys, estimates, truncated}` for `--all` |
+
+```bash
+uap eta                                # the active model's pace for orchestrated/medium
+uap eta --all                          # every key; too-thin keys named, not hidden
+```
+
+---
+
+## `diff`
+
+Local diff view: what the agent changed around here, in one
+honest render — uncommitted rows (staged + unstaged vs HEAD) with per-file
++N/-N and git status glyphs, untracked paths, honest totals, and unpushed
+commits vs the base with ahead/behind and aggregate deltas. Binary files
+render `±` (unknown), never `0`. Safe-git only: execFileSync argument
+arrays, a 5s timeout, and the stateful caches (fsmonitor, untrackedCache)
+defeated. Outside a repository it prints an explicit `git:` error line —
+never a stack trace, never silence.
+
+| Flag | Purpose |
+|------|---------|
+| `--base <ref>` | Base ref for the unpushed view (default `master`) |
+| `--max <n>` | Per-section file cap (default 40) |
+| `--json` | The raw facts as JSON |
+
+```bash
+uap diff                               # the working-tree + unpushed picture
+uap diff --base origin/master          # against a different base
+```
+
+---
+
 ## `self-harness`
 
 Self-improving harness: mine model-specific failures from traces, propose a
@@ -640,6 +701,9 @@ Ports/hosts: `UAP_DASH_PORT` (3847), `UAP_DASH_HOST` (localhost),
 | `--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`) |
+| `--socket <path>` | `connect`: proxy AF_UNIX socket (default `$UAP_PROXY_SOCKET`) |
+| `--ready-file <path>` | `connect`: touch this file (with the bound port) once listening |
+| `--allow-anyone` | `connect`: REQUIRED consent — see the warning below |
 | `--if-enabled` | No-op unless `.uap.json` `proxy.autostart` is true (hook-safe) |
 | `--no-dashboard` | Don't start the ride-along dashboard on this `ensure`/`start` |
 | `--quiet` / `--json` | Suppress output (hooks) / machine-readable status |
@@ -648,8 +712,23 @@ Ports/hosts: `UAP_DASH_PORT` (3847), `UAP_DASH_HOST` (localhost),
 uap proxy status --json    # includes a `dashboard` block (port, url, healthy, owner)
 uap proxy restart          # e.g. after changing PROXY_* in .uap/proxy.env
 uap proxy dashboard off    # opt out of the ride-along dashboard
+uap proxy connect --socket ~/.uap/proxy.sock --port 4000 --allow-anyone
 ```
 
+`connect` is the companion to the proxy's optional AF_UNIX surface
+(`PROXY_SOCKET`, served 0600): a small relay that accepts on a local TCP port
+and pipes every byte to the socket, for clients that cannot speak AF_UNIX. It
+is fail-closed (an upstream failure destroys the client connection instead of
+hanging it) and touches a `--ready-file` once listening, so wrappers can wait
+out the boot race.
+
+**Why `--allow-anyone` is required:** the 0600 socket exists so only the
+owning USER can reach the model path; the relay re-serves it on loopback
+TCP, and while it runs EVERY local user can reach the model path through
+it — the gate, inverted. The command refuses to start without the explicit
+flag, says so on stderr while it runs, and should be stopped when the work
+is done.
+
 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).
 
@@ -707,10 +786,37 @@ current dir + scratch are writable, so writes outside fail at the kernel — the
 boundary `--dangerously-skip-permissions` cannot bypass.
 
 ```bash
-uap sandbox -- <command> [args...]
+uap sandbox [--session <id>] [--net shared|off] -- <command> [args...]
+```
+
+The `--` separator before the command is REQUIRED: without it, the sandbox's
+own flags (`--session`, `--net`, `--ttl`, `--reason`, `--json`) are parsed as
+sandbox options rather than passed through to the session command. The grant
+verbs are only intercepted when there is no `--` — `uap sandbox -- revoke …`
+runs a binary named `revoke`, not the ledger verb.
+
+Bridge P4 authorities on top of the floor:
+
+- `--net off` — 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; a harness that needs the model fails loudly by design.
+- per-session writable holes from the consent ledger (reason REQUIRED, TTL
+  default 8h / cap 7d, audit-logged):
+
+```bash
+uap sandbox grant <path...> --session <id> --reason "..." [--ttl <secs>]
+uap sandbox grants [--session <id>] [--json]
+uap sandbox revoke <grantId>
 ```
 
-See [Sandbox](../guides/SANDBOX.md).
+  The grants listing states the ledger's tamper-evidence verdict (ADR 0011):
+  a ledger that fails its out-of-checkout anchor check is stamped INTEGRITY
+  MISMATCH — rows are still listed but marked unverified, new grants are
+  refused, and a sandbox session opens ZERO grant-derived holes. With
+  `--json` the alarm rides stderr so the data stays pure.
+
+See [Sandbox](../guides/SANDBOX.md) and
+[ADR 0011](../architecture/adr/0011-sandbox-grants-and-network-egress-boundary.md).
 
 ---
 
@@ -1115,6 +1221,62 @@ a deliberate act — do it only with reviewer sign-off.
 
 ---
 
+## `self`
+
+The self-knowledge card (S2): a small, version-pinned digest of UAP's own
+command surface and feature catalog, generated offline from the docs that ship
+inside the installed package (`docs/reference/CLI.md` +
+`docs/reference/FEATURES.md`). An agent that must search online to learn its
+own features wastes turns and self-describes from stale sources; the card is
+the fix. Cached in the project's `.uap/self-card.md` and regenerated
+automatically when the installed version or the source docs change
+(fingerprint-pinned). The session-start hook keeps it fresh and surfaces a
+pointer block.
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `card` | `--refresh`, `--json` | Ensure/build the card; `--refresh` forces a rebuild even when the pin matches |
+| `query <question>` | `--limit <n>`, `--json` | Ranked offline search over the card (commands + features, alias-aware) |
+
+```bash
+uap self card                       # ensure the card is fresh and print the pointer block
+uap self card --refresh --json      # force a rebuild, machine-readable stats
+uap self query "how do I run a controlled benchmark"
+```
+
+---
+
+## `attention`
+
+The operator attention queue: the ask-instead-of-stop rail. When a
+decision is genuinely yours — a placement parked and waiting for a swap
+approval, a grant request, a blocking question — the agent records it here
+with its context and a SAFE DEFAULT, and keeps working. The session-start hook
+shows what is waiting (plus what was auto-decided while you were away); `sweep`
+is the AFK auto-decider: anything whose grace window elapsed without an answer
+adopts its recorded safe default (logged, never silent), and anything without
+one ESCALATES instead of silently expiring. The decider only records its own
+adoption — the underlying system keeps its own lifecycle. One queue per
+checkout: the MAIN checkout's `.uap/attention.json` (the dashboard, the CLI,
+and session hooks in any worktree share it; `UAP_ATTENTION_QUEUE` pins it
+elsewhere). Fail-open, atomic, re-sanitized on load; `UAP_ATTENTION_OFF=1`
+silences the rail end-to-end.
+
+| Subcommand | Key flags | Purpose |
+|------------|-----------|---------|
+| `list` | `--status <s>`, `--json` | What is waiting — OPEN items by default (pending + acknowledged + escalated); `--status` filters to one status (pending, acknowledged, decided, auto-decided, escalated; unknown values error) |
+| `ack <id>` | | Mark seen — the grace clock keeps running (seen ≠ answered) |
+| `decide <id> <decision>` | | Answer the ask (yours beats the decider) |
+| `sweep` | `--json` | Adopt recorded safe defaults for grace-elapsed items; escalate the rest |
+
+```bash
+uap attention list                        # what is waiting on you
+uap attention decide att-9f2a1b "apply option 2"
+uap attention sweep                        # AFK decider: adopt safe defaults, escalate the rest
+```
+
+---
+
 ## `uap-omp`
 
 UAP integration commands for oh-my-pi (omp) users. Thin wrappers over the
@@ -1140,3 +1302,6 @@ installed omp scripts and SQLite memory store.
 | `UAP_ESCALATE_MODEL` | `deliver` | Stronger model preset for escalation |
 | `UAP_HALO_TRACE_PATH` | `harness` | Default HALO trace JSONL path |
 | `UAP_EMBEDDING_ENDPOINT` | memory/embeddings | Embedding service endpoint |
+| `UAP_PLAN_READABILITY` | `plan` | `0` disables the deterministic readability scan in `uap plan validate` |
+| `UAP_PLAN_READABILITY_STRICT` | `plan` | `1` makes error-severity readability findings block the validation stamp |
+| `UAP_ETA_OFF` | `deliver` | `1` disables per-attempt wall-clock telemetry to the model-analytics store |

package/docs/reference/COMPARISON.md

@@ -1,6 +1,6 @@
 # UAP vs Other Agent Harnesses and Tooling
 
-> Applies to UAP v1.224.0. Competitor profiles reflect public sources as of
+> Applies to UAP v2.29.0. Competitor profiles reflect public sources as of
 > September 2026; vendor-reported numbers are flagged as such, and claims we
 > could not verify are marked or omitted. UAP's own claims in this document
 > were verified against the code.

package/docs/reference/CONFIGURATION.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-> Universal Agent Protocol (UAP) v1.224.0
+> Universal Agent Protocol (UAP) v2.30.0
 
 > **🏭 Where this fits:** Cross-cutting — the settings that tune every station.
 > **What it delivers:** the dials that decide how your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)
@@ -28,7 +28,7 @@ source. Only options that exist in code are documented here.
 ### `.uap.json` schema (`src/types/config.ts`)
 
 Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
-`timeOptimization`, plus droids/commands/template sections.
+`timeOptimization`, `attention`, plus droids/commands/template sections.
 
 ```jsonc
 {
@@ -104,7 +104,7 @@ Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
 |---|---|---|
 | `deliver.orchestrate` | Blackboard orchestration for decomposed missions (`"on"`/`"off"`) | `"on"` (preflight seeds it) |
 | `deliver.epics` | Epic controller outer loop (`"on"`/`"off"`) | `"on"` (preflight seeds it) |
-| `deliver.parallelTasks` | Worktree-isolated parallel dispatch: independent READY orchestrator tasks run concurrently, each convergence loop + its gates in a detached git worktree seeded with the mission's current state; deltas merge back serially, and a merge conflict fails the task into the minimal-repair retry. Clamped to 1–8. **Parallel is the default** — an unset key resolves to 4, capped per wave at the number of independent READY tasks. Parallelism is conditional on worktree isolation: outside a git repo (or with an unborn HEAD) the run stays sequential and logs why. Set `1` (or `UAP_DELIVER_PARALLEL_TASKS=1`) to force sequential execution. | `4` (parallel, worktree-isolated) |
+| `deliver.parallelTasks` | Worktree-isolated parallel dispatch: independent READY orchestrator tasks run concurrently, each convergence loop + its gates in a detached git worktree seeded with the mission's current state; deltas merge back serially, and a merge conflict fails the task into the minimal-repair retry. Completion-triggered scheduling: a finished task's slot refills the moment it settles (no wave barrier — a fast sibling never idles behind a slow one), and a task whose dependencies all succeeded starts as soon as its slowest sibling-dependency settles. Settlement stays strictly sequential (one task at a time); which task settles next is timing-dependent. Clamped to 1–8. **Parallel is the default** — an unset key resolves to 4. Parallelism is conditional on worktree isolation: outside a git repo (or with an unborn HEAD) the run stays sequential and logs why. Set `1` (or `UAP_DELIVER_PARALLEL_TASKS=1`) to force sequential execution. | `4` (parallel, worktree-isolated) |
 | `deliver.adversarialGate` | Adversarial red-team gate before a converged run is accepted (`false`/`0`/`"off"` disables; a positive integer retunes the round budget, cap 4). Overridden by `UAP_DELIVER_ADVERSARIAL_GATE`. | on (≤2 rounds) |
 | `deliver.criteriaLint` | Plan-time lint of planner/split-emitted acceptance criteria; behavioral criteria gain an executable-evidence clause. Overridden by `UAP_DELIVER_CRITERIA_LINT`. | on |
 | `deliver.evidenceGate` | Anti-vacuous delivery gate + over-claim metric stream (`.uap/delivery-evidence.jsonl`). Overridden by `UAP_DELIVER_EVIDENCE_GATE`. | on |
@@ -114,6 +114,9 @@ Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
 | `UAP_SNAPSHOT_DIR` | Base dir for `--keep-best` snapshots (absolute path) | `~/.cache/uap/snapshots` |
 | `UAP_SNAPSHOT_MAX_MB` | Skip the `--keep-best` snapshot (rollback disabled) when the tree exceeds this size | `4096` |
 | `UAP_DASH_REFRESH_MS` | Dashboard live snapshot push/poll interval in ms (`--refresh` flag wins; min 250) | `2000` |
+| `UAP_ATTENTION_GRACE_SECS` | Runtime override for `attention.graceSecs` (the AFK decider's grace window). Positive integer seconds, cap 86400; set-but-invalid (including a cleared/empty value) fails safe to the config value. | unset (config wins) |
+| `UAP_ATTENTION_OFF` | `1` is the kill switch for the attention rail: nothing new is enqueued from surfaces (e.g. a parked placement), nothing is auto-decided, `uap attention list` shows nothing, and the session-start hint prints nothing. The queue file itself is left alone. | unset |
+| `UAP_ATTENTION_QUEUE` | Pins the attention queue to an explicit FILE (default: the MAIN checkout's `.uap/attention.json`, so the dashboard, the CLI, and session hooks in any worktree share ONE queue). Tests and odd layouts only. | unset |
 | `HERMES_HOME` | Hermes home dir | `~/.hermes` |
 | `FACTORY_PROJECT_DIR` | Project dir in Factory hook commands | — |
 | `FORGE_UAP_PROJECT` | Project dir in ForgeCode hook scripts | `.` |
@@ -122,6 +125,12 @@ Top level: `version`, `project`, `memory`, `worktree`, `costOptimization`,
 | `HOME` | `~/.uap/omp`, droids dir resolution | — |
 | `APPDATA` / `USERPROFILE` | Windows MCP config path expansion | — |
 
+### `.uap.json` `attention` section (top level)
+
+| Key | What it does | Default |
+|---|---|---|
+| `attention.graceSecs` | Operator attention queue: how long a pending ask waits for your answer before the AFK auto-decider may act (`uap attention sweep`, also swept at session start and on a 60s timer by the dashboard server). A grace-elapsed item with a recorded safe default ADOPTS it (logged, never silent); an item without one ESCALATES instead of silently expiring. The decider records its adoption only — the underlying system keeps its own lifecycle. Positive integer seconds, cap 86400 (24h); `0` adopts immediately. NOTE: an asking surface may pin an item's deadline to the ask's own expiry (a placement park's deadline is the pending entry's TTL) — the grace window is the fallback for asks without one. Overridden by `UAP_ATTENTION_GRACE_SECS`. The queue file is the MAIN checkout's `.uap/attention.json` (not per-worktree), overridable via `UAP_ATTENTION_QUEUE`. | `300` (5 min) |
+
 Per-model API key env var names are configurable via the model config field
 `apiKeyEnvVar` (`src/types/config.ts`), resolved indirectly in
 `src/models/openai-compat-client.ts`.

package/docs/reference/CONFIGURATION_REFERENCE.md

@@ -29,6 +29,7 @@ uap config wizard               # interactive expert configurator (also: uap set
 - [Engineering principles](#principles) — How code should be written, and the backward-compatibility stance.
 - [Worktree workflow](#worktree) — Branch-per-feature isolation and auto-cleanup.
 - [Inference proxy tuning](#proxy) — Guardrails and context limits for a local model behind the proxy.
+- [Sandbox & session authority](#sandbox) — Kernel-enforced agent boundaries: the bubblewrap floor, per-session grants, and the network egress boundary.
 - [Dashboard](#dashboard) — The live analytics server and its mutation token.
 - [Token & time optimization](#optimization) — Context budgets, caching, batching, and parallelism.
 - [General](#general) — Project metadata and CLI behavior.
@@ -133,6 +134,18 @@ When set to 1 for a single command, exempts that one sanctioned manual edit from
 
 **Recommendation:** Use inline (`UAP_DELIVER_BYPASS=1 <cmd>`) for a one-off edit; never export it.
 
+### `delivery.protectIac`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `false` |
+
+Refuse model writes to deploy/IaC files (Dockerfile, docker-compose, *.tf, *.tfvars, pulumi, serverless) during `uap deliver`. Permissive by default (false) so the model can edit IaC freely; set true to block IaC writes and snapshot/restore them against run_bash tampering. The `--protect-iac` CLI flag overrides this per-run.
+
+**Recommendation:** Leave false (permissive) for most projects — IaC edits are legitimate deliverable work. Set true only when the deploy topology is a fixed trust anchor the mission must not alter.
+
 ## Verification gates
 
 <a id="verification"></a>Proving generated code actually builds and runs before "done".
@@ -257,6 +270,102 @@ Model id sent to the vision endpoint for aesthetic review (e.g. qwen3.8-27b).
 
 **Recommendation:** Set by `uap setup` to your local vision model. Required for blocking vision review under `max` fidelity.
 
+### `plan.readability.enabled`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `true` |
+
+The plan-comprehension scan in `uap plan validate` (B1): deterministic readability rules over the plan artifact — executive summary first, detail progressing downward, section word budgets, jargon density, diagram required at a task-count threshold. Findings are advisory hints the judge-model review adjudicates.
+
+**Recommendation:** Leave on: the scan is local, instant, and advisory by default.
+
+### `plan.readability.strict`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | boolean |
+| **Default** | `false` |
+
+Give the readability scan deterministic teeth: error-severity findings (no opening summary, detail before the high level, missing diagram) fail `uap plan validate` outright instead of being adjudicated hints. `--force` / `UAP_PLAN_REVIEW_FORCE=1` remains the escape hatch.
+
+**Recommendation:** Enable once your plan templates reliably pass — it enforces plans a human can skim. Keep off while calibrating.
+
+### `plan.readability.minSummaryWords`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `20` |
+
+Minimum prose words between the plan title and the first section — the executive-summary gate.
+
+**Recommendation:** 20 words is a two-sentence what-and-why. Lower for terse internal plans; 0 effectively disables the rule.
+
+### `plan.readability.maxWordsPerSection`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `300` |
+
+Soft word budget per section before a readability warning fires.
+
+**Recommendation:** 300 keeps a section to one point. 0 disables the budget check.
+
+### `plan.readability.jargonDensityThreshold`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `0.35` |
+
+Jargon tokens per prose word above which the plan earns a readability warning (camelCase/snake_case/acronyms in prose).
+
+**Recommendation:** 0.35 tolerates normal technical writing while catching identifier soup. Raise for deeply technical audiences.
+
+### `plan.readability.requireDiagramAtTasks`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `5` |
+
+Task items (checklist + ordered steps) at which a data-flow diagram (mermaid or image) is required in the plan.
+
+**Recommendation:** 5 keeps small plans diagram-free while forcing one once the moving parts multiply. 0 disables the rule.
+
+### `UAP_PLAN_READABILITY`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `true` |
+
+Runtime kill switch for the plan readability scan: `0` skips it entirely in `uap plan validate`.
+
+**Recommendation:** Leave unset. Use inline `UAP_PLAN_READABILITY=0 uap plan validate` only when diagnosing a scan misfire.
+
+### `UAP_PLAN_READABILITY_STRICT`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `false` |
+
+Runtime strict override for the plan readability scan: `1` makes error-severity findings block the validation stamp (same as `plan.readability.strict`).
+
+**Recommendation:** Use inline for CI enforcement without changing the project config; never export globally — a hard gate in every shell surprises interactive agents.
+
 ## Model routing
 
 <a id="routing"></a>Which model handles planning, execution, and review.
@@ -571,6 +680,54 @@ Batches git/deploy actions across agents to avoid conflicting concurrent pushes.
 
 <a id="orchestration"></a>Long-task autonomy: decompose, resume, and loop-to-100%.
 
+### `attention.graceSecs`
+
+| | |
+|---|---|
+| **Where** | `.uap.json` |
+| **Type** | number |
+| **Default** | `300` |
+
+Grace window before the AFK auto-decider may adopt an attention item's recorded safe default (`uap attention sweep`, also swept at session start). Items without a safe default escalate instead.
+
+**Recommendation:** 300s (five minutes) is long enough for a present operator to intercede and short enough that an unattended run never stalls on an ask. Raise for high-stakes decisions, 0 adopts immediately.
+
+### `UAP_ATTENTION_GRACE_SECS`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | number |
+| **Default** | `300` |
+
+Runtime override for the attention grace window; caps at 86,400 (24h).
+
+**Recommendation:** Use inline for a one-off long mission; set the project config key instead for a standing value.
+
+### `UAP_ATTENTION_OFF`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `false` |
+
+Kill switch for the attention rail: `1` disables enqueue, sweep, AND list end-to-end (the queue file stays; nothing new is asked, nothing is auto-decided, no hint prints).
+
+**Recommendation:** Leave unset. Use inline when the queue is misbehaving; the rail is fail-open everywhere so a broken store never blocks work.
+
+### `UAP_ATTENTION_QUEUE`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Pins the attention queue to an explicit FILE. Default: the MAIN checkout's `.uap/attention.json`, so the dashboard, the CLI, and session hooks in any worktree share ONE queue.
+
+**Recommendation:** Tests and non-standard layouts only; unset means the default shared-per-checkout root.
+
 ### `handsfree.enabled`
 
 | | |
@@ -795,20 +952,6 @@ When the model self-reports "stuck" but keeps repeating the same failing tool, r
 
 **Recommendation:** Keep on for local models; harmless for cloud models (rarely triggers).
 
-### `PROXY_LOCKSTEP_BREAK`
-
-| | |
-|---|---|
-| **Where** | `.uap/proxy.env` |
-| **Type** | boolean (+ `PROXY_LOCKSTEP_PIVOT_AT` / `PROXY_LOCKSTEP_HARD_AT` numbers) |
-| **Default** | `true` (pivot at streak 2, hard stop at streak 4) |
-
-When the *identical* tool call fails with the *identical* error, escalates decisively: pivot directive → final warning → hard-fail the session with a 400, recording each tier to the loop-incident ledger (`UAP_LOOP_INCIDENTS`, default `~/.config/uap/loop-incidents.jsonl`). Both directives are always given before the stop, so the stop lands at `max(HARD_AT, PIVOT_AT + 2)` — never earlier. `uap loops` lists the ledger and prints a ready `uap ideate`/`uap deliver` handoff for the broken loop. A fresh human user turn re-arms the guard.
-
-**Dependency:** the streaks lockstep reads are fed by the ERROR-LOOP and DOUBLING-DOWN trackers — `PROXY_ERROR_LOOP=off` or `PROXY_DOUBLING_BREAK=off` silently disarms lockstep too. `PIVOT_AT=0` disables the guard; `HARD_AT=0` disables only the hard stop.
-
-**Recommendation:** Keep on — this is the guard that ends deterministic-failure loops in minutes instead of tens of wasted full-context turns.
-
 ### `PROXY_RECON_CONVERGENCE_THRESHOLD`
 
 | | |
@@ -857,6 +1000,118 @@ Proxy side of real-time adaptation: whether the serving proxy honors a fresh ada
 
 **Recommendation:** Leave on. Set `false` only to make the proxy ignore adaptation signals even when the reactor emits them.
 
+## Sandbox & session authority
+
+<a id="sandbox"></a>Kernel-enforced agent boundaries: the bubblewrap floor, per-session grants, and the network egress boundary.
+
+### `PROXY_SOCKET`
+
+| | |
+|---|---|
+| **Where** | `.uap/proxy.env` |
+| **Type** | string |
+| **Default** | `` |
+
+AF_UNIX socket the inference proxy serves IN ADDITION to its TCP port — a permission-gated (0600) model-path choke point for sandboxed and multi-user setups (unset = off).
+
+**Recommendation:** Set in .uap/proxy.env to the checkout's `.uap/proxy.sock` on shared boxes; leave unset for single-user loopback setups.
+
+### `UAP_PROXY_SOCKET`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Where `uap proxy connect` looks for the proxy socket when re-serving it on local TCP (default: the checkout's `.uap/proxy.sock`).
+
+**Recommendation:** Leave unset (the default covers the standard layout); set only when the proxy socket lives elsewhere.
+
+### `UAP_SANDBOX_NET`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | enum (shared \| off) |
+| **Default** | `shared` |
+
+Default network mode for `uap sandbox`: shared (normal network) or off (own network namespace with nothing up — the kernel egress boundary; model access impossible by design). Strictly `shared` or `off`: any other value fails loud (exit 2), never a silent downgrade to shared.
+
+**Recommendation:** Leave shared; use `--net off` per-run for untrusted code, evals, and data-only work.
+
+### `UAP_SANDBOX_GRANTS`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Pins the per-session sandbox grant ledger to an explicit FILE. Default: the MAIN checkout's `.uap/sandbox-grants.json`, so every surface shares ONE consent ledger.
+
+**Recommendation:** Tests and non-standard layouts only; unset means the default shared-per-checkout ledger.
+
+### `UAP_SANDBOX_GRANTS_OFF`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | boolean |
+| **Default** | `false` |
+
+Kill switch for the grant ledger: `1` resolves zero grants (no extra writable holes). The sandbox itself and its kernel boundary are unaffected.
+
+**Recommendation:** Leave unset. Inline use only, when the ledger is misbehaving — the safe direction is always least authority.
+
+### `UAP_SANDBOX_WORKDIR`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Workdir `uap sandbox` makes writable (default: cwd). Refused when over-broad ($HOME, /, /home).
+
+**Recommendation:** Leave unset in hooks (cwd is right); set when the sandboxed command must run from elsewhere.
+
+### `UAP_SANDBOX_ALLOW`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Extra writable paths, colon-separated — UNRECORDED authority, honored for compatibility. Every use is named in the audit trail and the launch banner, and entries get the same plan-time realpath re-check recorded grants get: an entry resolving to `/`, `/home`, or `$HOME` is refused loudly, and a symlink entry binds its resolved target, not the link.
+
+**Recommendation:** Prefer `uap sandbox grant <path> --session <id> --reason "..."` (recorded, TTL-bounded, revocable); use this only in throwaway scripts.
+
+### `UAP_SANDBOX_AUDIT`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Pins the sandbox audit trail (JSONL, one line per grant/revoke/sandbox-run) to an explicit FILE. Default: `.uap/sandbox-audit.jsonl` at the main checkout root.
+
+**Recommendation:** Leave unset; ship the default trail to your audit tooling.
+
+### `UAP_SANDBOX_ANCHOR_DIR`
+
+| | |
+|---|---|
+| **Where** | shell env |
+| **Type** | string |
+| **Default** | `` |
+
+Pins the DIRECTORY holding the consent-ledger trust anchors (one 0600 JSON per checkout, the tamper-evidence hash of the sanitized ledger). Default: `$XDG_STATE_HOME/uap/sandbox-anchors` (or `~/.local/state/uap/sandbox-anchors`) — OUTSIDE the checkout's write reach by design.
+
+**Recommendation:** Tests and non-standard layouts only; leave unset so the anchor stays outside the tree it vouches for.
+
 ## Dashboard
 
 <a id="dashboard"></a>The live analytics server and its mutation token.

package/docs/reference/DATABASE_SCHEMA.md

@@ -1,6 +1,6 @@
 # Database Schema Reference
 
-> Universal Agent Protocol (UAP) v1.224.0
+> Universal Agent Protocol (UAP) v2.30.0
 
 > **🏭 Where this fits:** Cross-cutting — the shop's records and shift log.
 > **What it delivers:** the durable memory of your [delivery pipeline](../guides/DELIVERY_PIPELINE.md)