@miller-tech/uap 2.21.3 → 2.36.1

package/docs/architecture/adr/0008-fleet-clients-link-out.md

@@ -0,0 +1,92 @@
+# ADR 0008: Dashboard fleet "Clients" tab ships as link-out, not multi-root
+
+- **Status**: Accepted
+- **Date**: 2026-10-10 (branch `feature/348-dashboard-fleet-clients`)
+
+## Context
+
+The dashboard server (`uap dashboard serve`) is single-project: every route
+reads `process.cwd()` captured at start. The operator runs many UAP-managed
+client folders as siblings on disk and wants one surface that shows each
+client's job queue (tasks) and delivery processes, with the ability to
+switch to any of them.
+
+Two shapes solve this:
+
+- **Option A — multi-root host**: the host server accepts a root parameter
+  on every API call and re-scopes all panels in place. Largest payoff, but
+  it turns the host into a cross-project write surface: every existing
+  mutation route (`/api/deliver/launch`, task mutations, policy toggles)
+  would need a second authority dimension, and the mutation token would
+  suddenly grant control of every sibling project at once.
+
+- **Option B — fleet overview + link-out**: the host stays single-project
+  and gains a read-only `GET /api/clients` that summarizes the fleet
+  (deliver-run states, queue depth, git, activity, health probe). Opening a
+  client spawns that client's OWN `uap dashboard serve` on a loopback port
+  (registry-only paths) and links out to it. Full control exists per
+  client, but only through each client's token-gated instance.
+
+## Decision
+
+Ship Option B. The host server gains no cross-project write authority; the
+only wire-reachable cross-client action is `POST /api/clients/serve`
+(token-gated, resolved strictly against the client registry — never a
+raw path from the wire). Discovery is auto-scan of the scan root (default:
+the host's parent directory, ignore-list filtered) merged with manual
+entries in `~/.uap/clients.json` (`uap clients add/remove/list/scan`).
+
+Consequences and guards:
+
+- **Sticky ports**: spawned dashboards record their port in the registry
+  (`ports` map), and computed ports skip claimed ones — a fleet change
+  (new folder, rename) can never silently move a live dashboard's port,
+  which would orphan the old process and wedge the new assignment.
+- **Root-matched probes**: liveness is true only when the answering
+  dashboard reports the expected project root, so a foreign listener on a
+  candidate port can never be link-mistaken for the client.
+- **Spawn is registry-only and argv-fixed** (`dashboard serve --port N
+  --host 127.0.0.1`): no shell, no path from the wire.
+- **Host never writes into client projects** — the earlier `.uap/dash.pid`
+  write was dropped; nothing reads it and it breached the invariant.
+- **Disclosure scope** (recorded for the security review): `GET
+  /api/clients` is unauthenticated and CORS-open exactly like
+  `/api/dashboard`, but it widens exposure from one project to every
+  sibling (absolute paths, branches, activity). On `--host 0.0.0.0` binds
+  this is LAN-visible; operators choosing that bind accept the wider
+  read. If the CORS-open-read posture is ever tightened, this route
+  belongs in that sweep. No secrets, tokens, or pids are in the payload.
+- **Environment**: spawned children inherit the operator's environment
+  (including `UAP_DASHBOARD_TOKEN`, deliberately kept so scripted fleet
+  control works) except the host's `UAP_CLIENTS_*` test overrides, which
+  are scrubbed so the child scans its own siblings.
+
+## Alternatives rejected
+
+- **Multi-root host (Option A)**: rejected for the write-surface blast
+  radius above. Note this change prepares rather than blocks it — the
+  per-project read surface (`getTaskData(cwd)`, `listRuns(root)`) was
+  already root-parameterized, and the registry's `ClientEntry` model is
+  reusable if in-place switching is ever wanted.
+- **Federated static links (no spawn)**: rejected because the operator
+  wants one click from the fleet view to a live dashboard; requiring a
+  manual `uap dashboard serve` per client defeats the point.
+
+## Follow-ups
+
+Completed on this branch:
+
+- **`uap clients stop` + tab Stop action** (spawned-instance teardown):
+  spawn-on-demand records the child pid in the registry (`pids` map —
+  host-owned bookkeeping in `~/.uap/clients.json`, never a write into the
+  client project). Stop requires BOTH a root-matched live probe and pid
+  ownership verification (`/proc/<pid>/cwd` must be the client root) before
+  SIGTERM — a recycled pid is never killed; on mismatch or missing evidence
+  it refuses and names the port for a manual stop. Stale pid records are
+  cleared opportunistically whenever a probe shows the dashboard gone.
+- **`resolveUapBin` extracted** to `src/utils/resolve-uap-bin.ts`
+  (`controls.ts` and `client-registry.ts` share it; the util lives one level
+  under `dist/` so the same-install `<root>/dist/bin/cli.js` resolution is
+  unchanged).
+
+None outstanding.

package/docs/architecture/adr/0009-completion-triggered-dispatch-and-per-leaf-model-dials.md

@@ -0,0 +1,71 @@
+# ADR 0009: Completion-triggered dispatch and per-leaf model dials
+
+- Status: Accepted
+- Date: 2026-10-11
+- Spec: completion-triggered scheduling (C1) and routing dials (C2), responding to the
+  "serial execution / no delegation" and "wrong worker on the wrong job"
+  gaps in mtlynch.io's *Why Are Coding Agents So Dumb?*
+- Supersedes: none — replaces the wave-barrier scheduling note documented in
+  `deliver.parallelTasks` (CONFIGURATION.md) and the `OrchestratorConfig`
+  doc block; extends the `DeliveryPhase` plan schema additively.
+
+## Context
+
+Two independent costs lived in the task orchestrator:
+
+1. **Wave-barrier idling.** The main loop dispatched a "wave" of up to
+   `concurrency` READY tasks and waited for ALL of them (`Promise.all`)
+   before recomputing the ready set. A 2-minute task in a wave with a
+   30-minute sibling left its slot idle for 28 minutes, and a dependent
+   whose only blocker finished early still waited for the whole wave.
+2. **Mission-wide model binding.** One model per mission meant paying the
+   strong model's rate for mechanical fill/test leaves, or starving the
+   hard design leaf by running everything cheap. Phase plans are the natural
+   place to say which leaf needs which worker, but `DeliveryPhase` had no
+   dial and deliver bound the executor model once, at mission start.
+
+## Decision
+
+1. **C1 — completion-triggered dispatch.** The orchestrator keeps an
+   in-flight array, fills free slots from the READY set (graph order), races
+   on completion, and settles the winner sequentially before refilling.
+   Invariants:
+   - settlement is strictly one-at-a-time; graph mutations (blackboard,
+     skip cascade, repair chains, P5 re-planning) never interleave;
+   - WHICH flight settles first is timing-dependent: `outcomes` interleaving
+     varies run-to-run and the per-id contract is last-entry-wins. This is
+     a deliberate trade of run-to-run reproducibility for utilization;
+   - a throwing settle drains in-flight flights (`allSettled` in a
+     `finally`) so a seam-callback throw cannot abandon tasks mid-mutation
+     (reachable only under completion-triggered dispatch — the wave barrier
+     guaranteed an empty in-flight set on any throw).
+2. **C2 — per-leaf model dials.** `DeliveryPhase.model?: string` is an
+   optional dial, planner-relayed (copy a key the MISSION text names
+   verbatim, never invent one) or hand-authored. Semantics:
+   - normalized once at parse (`normalizeModelDial`: lowercased to match
+     the preset table, control-character-stripped against log injection,
+     64-char cap); the run-state resume sanitizer applies the SAME rules;
+   - bound only where a per-task executor exists (isolated + agentic
+     tasks); the shared non-isolated executor stays mission-bound at start
+     because its write-allowlist refs are shared mutable state;
+   - fail-closed: unknown keys, non-isolated tasks, and the blind-executor
+     path all degrade to the mission model with a warning naming the actual
+     reason, plus a plan-time lint at mission start (not hours later at
+     bind time). The preset lookup uses `Object.hasOwn` — prototype-chain
+     keys (`constructor`, `__proto__`) are planner-reachable untrusted
+     text and must not bind an unpinned model.
+3. **Known debt, out of scope here:** the production projection drops
+   `criteria` (pre-existing; the dial threading fixed `model` in the same
+   map). Filed for a separate change.
+
+## Consequences
+
+- Utilization: a slot refills the moment a task settles; dependents start
+  when their last dependency succeeds, not when the wave drains.
+- The first C1 tests would literally deadlock under wave scheduling — they
+  pin the behavior by construction (a regression manifests as a timeout).
+- Resume round-trips keep dials; the persisted `model` key is additive and
+  old readers strip it harmlessly (their allowlist predates the field).
+- Blast radius: `task-orchestrator.ts` (loop), `decompose.ts` (schema +
+  prompt), `orchestrated-mission.ts` (threading + P5 feed), `deliver.ts`
+  (projection + binding), `run-state.ts` (round-trip), two reference docs.

package/docs/architecture/adr/0010-attention-queue-and-afk-auto-decider.md

@@ -0,0 +1,159 @@
+# ADR 0010: Attention queue and the AFK auto-decider
+
+- Status: Accepted
+- Date: 2026-10-11
+- Spec: unattended autonomy (A1) and the operator attention queue (A2), responding to
+  the "blocks on the operator / no safe way to proceed unattended" gap in
+  mtlynch.io's *Why Are Coding Agents So Dumb?*
+- Supersedes: none — extends the placement park path (ADR 0006's pending
+  approvals) and the session-start surface; adds a new module, no schema it
+  depends on changes.
+
+## Context
+
+When a decision is genuinely the operator's — a placement parked until a
+swap is approved, a grant that exceeds standing consent — the system had
+two bad options: stall the run waiting for a human, or silently drop the
+ask and pick a default nobody signed off on. mtlynch's complaint applies
+verbatim: the agent is either dumb-but-safe (idle) or autonomous-but-
+unaccountable (silent).
+
+The missing piece is not more automation; it is a **visible decision
+queue with recorded consequences**:
+
+- every ask carries its own context (what was requested, why it parked)
+  so the operator can answer it cold, minutes or hours later;
+- every ask carries a **safe default** the asking surface itself vouches
+  for — an action that is correct *without further consent* (for a parked
+  placement: let the pending request expire on its own TTL — nothing is
+  loaded, nothing is evicted);
+- an absent operator is expected, not exceptional: long unattended runs
+  are a first-class mode.
+
+## Decision
+
+1. **A2 — the attention queue** (`src/delivery/attention.ts`):
+   `.uap/attention.json` holds bounded, pending-or-resolved items
+   (`kind`, `title`, `detail`, `source`, optional `safeDefault{decision,
+   rationale}`, `graceDeadline`, `status`). Surfaces:
+   - **one queue per CHECKOUT, not per cwd**: the file lives in the MAIN
+     checkout's `.uap/` (resolved via `mainCheckoutRoot`, the same anchor
+     the policy-liveness fix established on 2026-07-13), because three
+     surfaces with three different cwds (dashboard server process, CLI,
+     session-start hook inside a worktree) would otherwise write and read
+     three different files and the rail would silently no-op — flagged
+     BLOCKER by the architecture review. `UAP_ATTENTION_QUEUE` pins an
+     explicit file for tests and odd layouts.
+   - **enqueue sites** vouch for their own safe default and may PIN the
+     item's deadline to the ask's own expiry (`expiresAt`): the placement
+     site pins to the pending entry's TTL, so the decider adopts at the
+     moment the pending actually expires — never advertising an actionable
+     swap for a dead pending, never recording an adoption before the
+     expiry it describes. Generic sites use the grace window. Only one
+     enqueue site ships with this ADR: the placement admit path (a park
+     that found no auto plan) enqueues a review-request sourced
+     `placement:<id>` whose safe default is the TTL expiry — the recorded
+     rationale says plainly that nothing is loaded or evicted by waiting.
+     A resolved ask (forward / auto-load) never enters the queue, and the
+     only park reason with options to apply (`not_resident`) gets the
+     "apply" instruction; the no-option reasons say so plainly instead of
+     inviting a decision that cannot be made.
+   - **the asking surface also CLOSES its asks**: applying or dismissing a
+     pending placement resolves the matching attention item by origin
+     (`resolveAttentionBySource`), so the queue learns of decisions made
+     through the placement surface itself — otherwise a later sweep would
+     record a false AFK adoption over an operator decision that was
+     actually made.
+   - **read surfaces**: `uap attention list/ack/decide` (CLI, new) and the
+     session-start hook, which sweeps, summarizes what was auto-decided
+     while away, and shows the top OPEN items so every session opens with
+     what is waiting on the operator. The default view is the open set
+     (pending + acknowledged + escalated) — an escalated ask is the
+     loudly-unresolved class and must not drop out of the casual view.
+   - **enqueue dedupes on open asks**: by `source` (the ledger's rule) AND
+     by (kind, title) — an expired-pending client retrying every TTL mints
+     a new placement id per retry, and without content dedupe an
+     unattended weekend would mint one never-pruned ask per retry. Each
+     item still self-resolves at its own pinned deadline.
+   - **sanitized twice**: at ingest AND on load. The file lives in
+     shared-write `.uap/` (writable by every agent on the project, and a
+     cloned third-party repo need not gitignore it), so the load path
+     re-applies the control-char/length sanitizer and validates
+     `kind`/`status` against their enums — a planted row with ANSI escapes
+     or a planted `safeDefault` must not reach operator terminals or ride
+     a sweep wearing its `[auto]` label (security review, F1).
+   - **fail-open everywhere**: the queue is an observability rail — a
+     corrupt or unwritable store logs a warning and never blocks the
+     asking surface (all enqueue call sites are best-effort; a failed
+     persist returns null instead of a phantom item). `source` is
+     server-generated, never client text, and the placement admit path
+     rejects model ids outside `[A-Za-z0-9._-]` before any queue write —
+     client text never becomes a durable prompt-injection channel. The
+     hook renders item text with an untrusted-data disclaimer.
+2. **A1 — the AFK auto-decider** (`sweepExpired`, same module; invoked by
+   `uap attention sweep`, at session start, and on a 60s timer inside the
+   dashboard server — gated by the same fleet-ownership env as the idle
+   sweeper, because during a long unattended run, the exact case this rail
+   exists for, session starts are rare and nothing else would fire):
+   - an item whose grace window elapsed WITH a recorded safe default has
+     the decider's resolution recorded **on the item only** — `status:
+     "auto-decided"`, the adopted decision and rationale logged. The
+     decider never mutates the underlying system: it adopts what the
+     surface already promised would happen unattended (for placement,
+     the expiry is the system's own TTL doing the work; the sweep just
+     makes the record honest instead of leaving a stale pending row).
+   - an item with NO safe default escalates (`status: "escalated"`) — the
+     opposite failure mode of mtlynch's complaint is the one we refuse:
+     never silently expire an ask that mattered.
+   - **operator beats the decider**: any operator resolution (ack keeps
+     the item alive but the grace clock keeps running — seen ≠ answered;
+     decide closes it) wins over the sweep; sweeps are idempotent against
+     already-resolved items; and a decision made through the asking
+     surface itself (apply/dismiss) resolves the queue item by origin.
+   - **standing consent stays the boundary**: a safe default is only as
+     trustworthy as the surface that recorded it (cf. ADR 0007's
+     allowlist discipline). The decider adds no authority of its own — it
+     is a bookkeeper for promises surfaces already had the right to make.
+3. **Grace window:** env `UAP_ATTENTION_GRACE_SECS` > config
+   `attention.graceSecs` > 300s, capped at 86,400 (24h); `0` adopts
+   immediately; a cleared/empty env value is treated as unset (fails safe
+   to config). The grace window is the DEFAULT deadline — a site that knows
+   its ask's real expiry pins it (see Decision §1). `UAP_ATTENTION_OFF=1`
+   is the kill switch: no enqueue, no sweep, list returns nothing, and no
+   session-start hint — the rail goes quiet end-to-end while the file is
+   left alone.
+
+## Consequences
+
+- A parked placement now has three fates instead of two: answered
+  (operator decides — through the queue OR through the placement surface,
+  which closes the ask by origin), adopted (default the surface vouched
+  for, logged, at the deadline the site pinned), or escalated (no safe
+  default — visible, not silent). Never a quiet stall.
+- The session-start hint makes the queue self-advertising: the operator
+  does not need to know the command exists to encounter what is waiting —
+  and a mid-session sweep in the dashboard keeps the decider alive during
+  exactly the unattended runs it exists for.
+- Bounded: open items are never pruned but content-dedupe collapses
+  retry-floods to one ask per question; resolved history prunes past 250.
+  Open items still only ever leave the queue via ack/decide/sweep — a
+  surface that enqueues an ask with NO lifecycle of its own must provide
+  its own resolution path or its asks linger by design (visible, not
+  silent).
+- **Accepted v1 debt — lost-update race:** writers are unlocked
+  read-modify-write (last writer wins); a sweep racing an operator decide
+  in the same millisecond window can drop the operator's record. The
+  placement ledger solves this with `withLedger` advisory locking; the
+  queue inherits it only if the race is ever observed in practice (both
+  reviews rated it rideable for an advisory rail; the failure is a lost
+  audit row, never a wrong system action).
+- The decider is deliberately weak. Extending it to actually DO things
+  (issue grants, trigger displacement) would move it from bookkeeping to
+  agency and must be its own ADR with its own consent analysis.
+- Blast radius: new module + new CLI file + command registration; the
+  placement admit path gains one best-effort enqueue (with a charset gate
+  on model ids); apply/dismiss close their asks; the session-start
+  template gains a fail-open block; the dashboard server gains a 60s
+  fail-open sweep timer; the settings registry gains four keys. No
+  existing schema or contract changes; readers of `.uap/attention.json`
+  are only the new surface.

package/docs/architecture/adr/0011-sandbox-grants-and-network-egress-boundary.md

@@ -0,0 +1,219 @@
+# ADR 0011: Per-session sandbox grants and the network egress boundary
+
+- Status: Accepted
+- Date: 2026-10-11
+- Spec: session authority (D2) + network egress boundary (D1), responding to
+  the "agents with too much authority" gap in mtlynch.io's *Why Are Coding
+  Agents So Dumb?*
+- Supersedes: none — extends the bubblewrap sandbox (`uap sandbox`) and
+  the inference proxy; no existing schema changes.
+
+## Context
+
+`uap sandbox` (the base floor) is all-or-nothing authority: the workdir and
+scratch are writable, everything else is EROFS, and the only escape hatch
+was `UAP_SANDBOX_ALLOW=path:path` — an **unrecorded** env var: no session
+scope, no expiry, no reason, invisible to the operator, surviving forever
+in shell histories and hook templates. Meanwhile the sandbox shared the
+host network by design (the agent must reach the proxy), so "too much
+authority" had two open faces: unrecorded write holes and unrestricted
+network egress.
+
+The bar: **every new authority must state who consented.**
+
+## Decision
+
+### D2 — the consent ledger (`src/policies/sandbox-grants.ts`)
+
+Every extra writable hole is a **grant**, recorded in
+`.uap/sandbox-grants.json` at the main checkout root (the
+`mainCheckoutRoot` anchor the attention queue established in ADR 0010 —
+one ledger per checkout, shared by every surface; `UAP_SANDBOX_GRANTS`
+pins an explicit file):
+
+- `uap sandbox grant <path...> --session <id> --reason "..." [--ttl N]`
+  creates a grant `{id, sessionId, paths[], reason, grantedBy, grantedAt,
+  expiresAt}`. A grant is refused without a session, a stated reason, or a
+  grantable target (existing absolute path; `/`, `/home`, `$HOME` itself
+  are refused — an over-broad grant IS a sandbox escape). Default TTL 8h,
+  hard cap 7d: authority is bounded by construction. An identical open
+  grant is RENEWED, not duplicated.
+- `uap sandbox --session <id> -- <cmd>` resolves the session's ACTIVE
+  grants and opens exactly those `--bind` holes; `uap sandbox grants` /
+  `revoke <id>` list and remove them. (The `--` separator is REQUIRED
+  before the command: without it, the sandbox's own flags — `--session`,
+  `--net`, `--ttl`, `--reason`, `--json` — are parsed as sandbox options,
+  not passed through to the session command.)
+- Every run appends a line to `.uap/sandbox-audit.jsonl` — the consent
+  record: which grants were used, which network mode engaged, and any
+  legacy `UAP_SANDBOX_ALLOW` entries labeled `unrecordedAllow` (still
+  honored for compatibility, now named in the audit and the banner).
+- Store rules inherited from ADR 0010's hardened queue: sanitize at ingest
+  AND on load (the ledger is shared-write `.uap/` and a planted row must
+  not become a kernel-writable hole), atomic writes with unique tmp
+  names, malformed rows dropped, and an unreadable ledger treated as
+  EMPTY — the safe direction for an authority store is least authority.
+  "Sanitize" for this ledger means more than text fields: the load path
+  RE-VALIDATES every path with the full grantable-path rule (absolute,
+  existing, symlink-resolved, and not `/`, `/home`, or `$HOME` — the P4
+  review caught that a string-prefix check alone would let a planted
+  well-formed row bind the whole root) and refuses expiries beyond the
+  hard TTL bound (a planted `expiresAt: "9999"` must never load).
+  `UAP_SANDBOX_GRANTS_OFF=1` resolves zero grants; the sandbox's kernel
+  boundary itself is never disabled by any of this.
+- **Consent must come from the operator, not from inside the sandbox**
+  (the security review's forgeability finding, three parts):
+  1. `grant`/`revoke` are REFUSED when `UAP_SANDBOX_ACTIVE=1` — that env
+     is set by the sandbox itself on the untrusted side, so an agent
+     cannot write new authority or remove the operator's (listing stays
+     allowed: read-only).
+  2. The planner `--ro-bind`s the ledger and audit files over their host
+     paths in EVERY sandbox namespace (a missing file gets `/dev/null`
+     bound at the path). A bind-mounted file cannot be unlinked, replaced,
+     or written inside the namespace, so the sandboxed agent can neither
+     plant grant rows nor forge audit lines — the load-path re-validation
+     checks SHAPE, but shape cannot establish WHO consented; the kernel
+     mount does.
+  3. Granted paths are re-resolved (`realpath`) at PLAN time and the
+     resolved value is re-checked for breadth, closing the load→exec
+     TOCTOU window where a concurrent process could swap a granted path
+     for a symlink. (A microsecond window between this resolution and
+     bwrap's own remains — accepted, documented.)
+- Fail-closed everywhere authority is parsed: a garbage or negative
+  `--ttl` is REFUSED (the old expression silently granted the 8h default
+  — the wrong direction); `--ttl 0` floors to 1s; an unknown
+  `UAP_SANDBOX_NET` value fails loud with exit 2 rather than silently
+  meaning FULL network; and every persist is followed by a reload
+  verification (a concurrent writer's lost update is retried once, then
+  reported as failure — never a silent success).
+
+### D1 — the network egress boundary
+
+**`--net off`** — `uap sandbox --net off` adds `--unshare-net`
+with nothing brought up: no TCP, no DNS, not even loopback, at the kernel.
+Any `connect()` fails. This is the complete boundary, intended for
+untrusted code, evals, and data-only work; a harness that needs the model
+fails loudly with connection refused, which is the boundary working. The
+net mode defaults from `UAP_SANDBOX_NET=off`; every run's actual mode is
+audit-logged (`netMode: shared|off`).
+
+**The proxy's unix-socket surface** — `PROXY_SOCKET=<path>`
+makes `anthropic_proxy.py` serve the SAME app on an AF_UNIX socket
+(0600, parent dir 0700) alongside its TCP port: a permission-gated model
+choke point for shared boxes. Stale-socket policy (hardened by the
+security review): a live listener owns its path — and "live" includes a
+socket that cannot be dialed (`EACCES`/`EPERM` is not proof of death, so
+another user's socket is never evicted and impersonated); only a refused
+or missing socket is a corpse. A non-socket file at the path is NEVER
+unlinked (`PROXY_SOCKET` can arrive from the operator's env or the
+sandbox-writable `.uap/proxy.env`, so a typo or planted value must not
+become an arbitrary-file-delete primitive), and a group/other-writable
+parent dir draws a warning (another local user could unlink or squat the
+path). `uap proxy connect --socket <path> [--port N] --allow-anyone`
+re-serves that socket on local TCP for clients that cannot speak
+AF_UNIX — behind an explicit consent flag, because while the relay runs
+it inverts the socket's gate: every local user can reach the model path
+through the loopback port.
+
+### D1's rejected design: the "only proxy" netns (and why)
+
+The intended D1 was a netns cut with a SINGLE hole to the proxy: bwrap
+`--unshare-net` plus a bind-mounted `PROXY_SOCKET`, with an in-namespace
+relay re-serving the proxy on `127.0.0.1:4000`. **It cannot work on
+rootless Linux**, and the failure is worth recording because the design
+looks correct on paper:
+
+1. **AF_UNIX pathname sockets are network-namespace-scoped.** The socket
+   file bind-mounts fine, but `connect()` looks the listener up in the
+   CONNECTING process's netns unix-socket table and finds nothing:
+   empirically `ECONNREFUSED` from inside the namespace while the same
+   socket answers on the host (verified on Linux 7.2, bwrap 0.11). The
+   hole through the wall is a file that carries no reachability.
+2. **bwrap closes every inherited fd** (verified: an fd handed to the
+   child via `stdio` slot 3 arrives closed), so an SCM_RIGHTS broker that
+   passes pre-connected proxy sockets across the wall is impossible too.
+3. **The userspace network stacks cannot express the policy.**
+   pasta/slirp4netns bridge a rootless netns to the host, but neither
+   offers an outbound port allowlist — attaching one would give the
+   sandbox FULL egress, the exact opposite of the boundary.
+
+A boundary that requires a helper that isn't installed, or a mechanism
+the kernel doesn't provide, would be a suggestion rather than enforcement.
+So `--net proxy` was **cut, not faked**: the two REAL modes are `shared`
+(no claim) and `off` (kernel-complete), and the model-path choke point
+(`PROXY_SOCKET`, 0600) ships on the proxy side where permission gating
+actually holds.
+
+## Consequences
+
+- Write authority beyond the workdir requires a recorded, bounded,
+  revocable consent. The legacy `UAP_SANDBOX_ALLOW` env still works for
+  compatibility — every use is audited and named as unrecorded — and its
+  entries get the same plan-time realpath re-check recorded grants get:
+  a symlink entry binds its resolved target, and an entry whose resolution
+  is `/`, `/home`, or `$HOME` is refused with an operator-visible note,
+  never bound.
+- `--net off` gives untrusted-code runs a complete, kernel-enforced
+  egress boundary.
+- Model-path gating becomes a socket permission problem (0600/0700) for
+  multi-user or sandboxed-adjacent setups, rather than a TCP port anyone
+  on the box can dial.
+- The "agent session with ONLY model egress" use case remains open. The
+  honest paths to it: (a) upstream `pasta`-class outbound filtering, if it
+  ever grows port allowlists; (b) a setuid/privileged broker that can
+  join the sandbox netns; (c) rootful sandboxing (a future
+  `--net proxy,via:root` could revisit). None are rootless today, so none
+  are claimed.
+- The audit JSONL is bounded: every line carries a monotonic `seq`, and
+  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 — a pruned trail is an EXPECTED
+  state, never a silent one. Seq numbering is continuous across
+  compaction AND audit-file deletion: the trust anchor carries the
+  witnessed seq high-water (`seqHi`), and each line numbers from the max
+  of the file's last seq and the anchor's — a trail whose numbering can
+  restart is a forgeable trail. Honest limits: concurrent audit appends
+  can mint the same next-seq before either lands (a duplicate seq is
+  evidence to investigate, not proof of planting on its own), and an
+  older binary's next recorded mutation drops the optional `seqHi` field
+  — it is recomputed from the file at the next current-binary mutation,
+  which only matters if the audit file is deleted inside that
+  mixed-version window.
+- The dashboard's session view lists the active authority per session —
+  id, session, remaining TTL, reason, paths, and the revoke command per
+  grant — plus the trust-anchor verdict (an INTEGRITY MISMATCH renders
+  red, rows listed-but-unverified, same contract as the CLI listing).
+  The per-checkout-root anchoring guarantees it reads the same ledger the
+  sandbox does.
+- Tamper evidence (out-of-checkout anchor): every successful
+  grant/renew/revoke writes a 0600 anchor at
+  `$XDG_STATE_HOME/uap/sandbox-anchors/<hash-of-main-checkout-root>.json`
+  (`UAP_SANDBOX_ANCHOR_DIR` pins the dir for tests) recording the SHA-256
+  of the sanitized ledger as of that recorded operation. The key is the
+  MAIN checkout root (the same `git rev-parse --git-common-dir` root the
+  session-start hook and the python tools use), so a worktree session and
+  its main checkout share ONE anchor for the ONE ledger they share — a
+  worktree session is never silently unanchored, and a cross-cwd grant
+  never fabricates a mismatch. A granted path covering the anchor dir is
+  refused (a hole over the anchor would let the sandboxed side de-anchor
+  itself silently). Verification (`uap sandbox grants` states it; the
+  launch path enforces it) compares the on-disk ledger against the
+  anchor: a mismatch means something with the CHECKOUT's write reach
+  changed the ledger outside a recorded consent operation — new grants
+  are refused, and the session resolves ZERO grant-derived holes
+  (fail-closed; the kernel boundary is unaffected). A `revoke` on a
+  mismatched ledger still removes authority (the safe direction) but
+  re-anchors the remaining rows as the new baseline and names that at
+  the moment it stops being detectable.
+  What this remains honest about: it is tamper-EVIDENCE, not origin
+  proof. The anchor lives in the user's state dir, so a same-user process
+  OUTSIDE the checkout can still write it; a plant that predates the
+  first anchor is baselined into it (bootstrap cannot verify history);
+  and true origin proof (a different uid, a signed ledger, a hardware
+  key) stays open on purpose — the threat model closes the agent-side
+  vectors, and the anchor closes the checkout-write-reach side of the
+  operator residual.
+- Residual, accepted: the microsecond TOCTOU between the planner's
+  `realpath` and bwrap's own bind (a concurrent process with write on a
+  granted path's parent could still race it), and the anchor's same-user
+  limit named above.