ur-agent 1.47.1 → 1.48.0

package/docs/AGENT_FEATURES.md

@@ -9,6 +9,52 @@ reproducible autonomous software engineering agent: every substantial task can
 be driven as `spec -> plan -> patch -> test -> report -> rollback`, with the
 spec as the durable source of truth and command evidence as the success gate.
 
+## v1.48.0 Additions
+
+- `ur cloud --runner managed` persists remote environment/session lifecycle,
+  cursor reconciliation, bounded output, explicit remote branches, cancellation,
+  and idempotent steering. Only PASS results with safe review branches are
+  eligible; all eligible results receive deterministic ranks rather than an
+  unverified comparative-quality score. Cancellation wins over a concurrent
+  session start. The authenticated A2A compatibility task API exposes the same
+  owner-isolated steering boundary for mobile clients.
+- `ur learn playbooks` mines repeated proof-backed run shapes behind a Wilson
+  confidence floor, rejects unsafe/secret-like traces, and requires explicit
+  approval before materializing a normal validated workflow. Disabling verifies
+  that workflow and moves it to the private disabled archive.
+- Project task memory accepts content-digested file and run citations plus
+  explicit user/web citations. Resolution revalidates freshness and excludes
+  rejected, superseded, stale, or missing evidence by default.
+- `ur agent-ci` runs untrusted event tasks in detached worktrees with actor
+  policy, read-only GitHub permissions, scrubbed code subprocesses, bounded
+  redacted output, exact NUL-delimited path policy, pre/post verification-state
+  binding, and a post-check hash-addressed patch for a separate publish decision.
+- Eval cases capture redacted control-flow trajectories and grade tool choice,
+  order, success, repetition, failures, permission denials, and turns. `ur eval
+  gate` makes those scores and outcome/cost/duration regressions enforceable.
+- `ur desktop-qa` drives bounded Electron fixtures and attaches teardown-safe,
+  masked screenshots, hashes, diagnostics, and reports to the artifact review
+  surface. Raw video/trace evidence is available only without selector
+  redaction; incompatible fixtures fail validation. Attachment sources reject
+  symlinks and unsafe MIME types download as sandboxed octet streams.
+- `/btw` is now a durable, private, hash-chained side chat with
+  create/continue/list/show/rename/close lifecycle and cancellation, while every
+  fork remains one-turn and tool-free.
+- `ur workspace` enrolls canonical repository identities, validates a
+  dependency DAG, serializes writers per repository, uses isolated worktrees,
+  resumes private state, runs repository gates, and emits PR/rollback plans
+  without executing them.
+- `ur arena` now has deterministic, model, and hybrid judges. Only
+  proof-backed, verification-passing, safety-eligible candidates reach the
+  strict anonymous judge schema; oversized full diffs are excluded rather than
+  partially judged, and apply requires the original clean base.
+- Background, managed-cloud, A2A/mobile, artifacts, evals, and the standard CLI
+  share bounded/idempotent control, nonzero CI failure semantics, private state,
+  and reviewable evidence.
+
+See [Frontier Agent Workflows](FRONTIER_AGENT_FEATURES.md) for commands and
+trust boundaries.
+
 ## v1.47.0 Additions
 
 - `ur ag-ui serve` adds a secure AG-UI HTTP/SSE boundary for user-facing

package/docs/AGENT_TRENDS.md

@@ -2,7 +2,7 @@
 
 UR is a provider-flexible, local-first terminal coding agent. This page tracks
 how UR maps to current agent-platform trends and where future work should go
-next. The factual comparison below is a **2026-07-15 research snapshot**; run
+next. The factual comparison below is a **2026-07-26 research snapshot**; run
 `ur agent-trends` for the versioned machine-readable report and re-check the
 linked primary sources before acting on prerelease standards.
 
@@ -75,18 +75,23 @@ Inside an interactive session:
 | MCP Tasks and MCP Apps | Covered | Negotiated Tasks lifecycle, owner-isolated durable state, and a self-contained Apps resource through `ur mcp serve-http` | Reconcile final extension schemas and broaden client interoperability tests |
 | A2A / Agent Card interoperability | Covered | Stable-SDK v0.3 plus strict v1 ProtoJSON JSON-RPC/HTTP+JSON, negotiated cards, tenant isolation, durable artifacts, and TCK coverage | Adopt the stable v1 SDK when released; add signed-card verification and streaming only with truthful end-to-end tests |
 | AG-UI agent-to-frontend interoperability | Covered | Official-schema HTTP/SSE adapter, truthful capabilities, ordered state/text/tool events, cancellation, exact CORS, bounded requests/output, and loopback-or-bearer security | Add independent frontend fixtures before advertising optional interrupts, binary/WebSocket transport, or client tools |
-| Durable workflows and checkpoints | Covered | resume, rewind, `ur bg` background runs, optional worktrees/PRs, cron/workflow internals, file restore | Publish a checkpointed workflow format for repeated automations |
+| Durable workflows and checkpoints | Covered | resume, rewind, steerable `ur bg`/managed-cloud runs, optional worktrees/PRs, cron/workflow internals, file restore, and resumable multi-repo DAG state | Add authenticated cross-machine checkpoint replication |
+| Managed cloud workers | Covered | `ur cloud --runner managed` persists remote session IDs/cursors/branches, reconciles lifecycle, accepts idempotent steering, deterministically ranks only PASS results with safe review branches, and never silently merges | Add provider-neutral managed-runner adapters behind the same lifecycle |
+| Mobile agent steering | Covered | authenticated owner-isolated A2A compatibility task messages plus bounded background/cloud steering and cancellation | Add push notifications without widening delegated scopes |
+| Durable side chats | Covered | private hash-chained `/btw` create/continue/list/show/rename/close history with tool-free one-turn forks and cancellation | Add optional encrypted export/import |
+| Multi-repository coordination | Covered | canonical repository/remote identity, dependency DAGs, one writer per repo, isolated worktrees, resume, verification, and explicit PR/rollback plans | Add forge-neutral stacked-review adapters without automatic publishing |
+| Self-learning playbooks | Covered | proof-backed candidates, confidence floor, unsafe-trace rejection, explicit approval/rejection/disable, and standard workflow execution | Add drift detection and approval renewal when evidence changes materially |
 | Multi-agent orchestration | Covered | built-in planning, exploration, verification, and general-purpose agents; custom agents | Document reusable team patterns and role selection |
-| Long-term memory | Partial | Existing memory/retrieval plus a provenance-rich SHA-256 project task-memory chain with private atomic writes, verification, quarantine, and rollback | Extend the same deletion and integrity guarantees to team, semantic, embedding, and legacy stores |
+| Long-term memory | Partial | Existing retrieval plus a provenance-rich SHA-256 task-memory chain, file/run/user/web citations, freshness resolution, private atomic writes, quarantine, and rollback | Extend citation/deletion/integrity guarantees to semantic, embedding, and legacy stores |
 | Portable Agent Skills | Covered | Native and `.agents/skills/` project/user discovery, strict validation, deterministic tree/permission digests, Ed25519 signing, trusted keys, and invocation-time integrity checks | Require registry attestations and dependency review before community one-command installation |
 | Semantic codebase retrieval | Covered | local embedding-based code index (`ur code-index`), opt-in `CodeSearch` tool, incremental re-index, auto-reindex watcher, Ollama embeddings | Add richer symbol-aware ranking |
 | Reliable repo editing | Covered | `ur repo-edit` builds a file/symbol index, performs AST-aware JS/TS identifier rename planning, previews patches before writing, and applies multi-file edits transactionally with rollback on syntax or check failure | Extend AST edits beyond identifier rename into import moves and signature-aware refactors |
 | Permission and safety policy | Covered | `ur safety`, `.ur/safety-policy.json`, pre-Bash safety evaluation, read/write/execute/network command classes, destructive-command approval, sandbox recommendations, and secret exfiltration denial | Record sandbox attestation in every risky command's evidence trail |
 | Project context management | Covered | `ur context-pack`, `.ur/project-manifest.json`, `.ur/context/*`, Project DNA, instruction files, verify gates, and task memory for decisions/constraints/commands/diffs | Feed the generated project manifest into subagent prompt selection and verifier gate choice |
 | AGENTS.md interoperability | Covered | `AGENTS.md` loaded as runtime project context (before `UR.md`), plus imported by the `/init` command | Keep aligned as the AGENTS.md spec evolves |
-| Browser and computer-use workflows | Covered | `/browser`, `/chrome`, Playwright-aware tasks, WebSearch, WebFetch, risky-action approval | Add more release fixtures with screenshots and replay assertions |
-| Provenance and citations | Partial | WebFetch source URLs, `/cite`, `/graph`, `/trace`, evidence ledgers | Add claim-to-source mapping for web/MCP answers |
-| Evals and observability | Partial | verifier gates, `.ur/verify.json`, `/verify`, `/trace`, OpenTelemetry hooks, replayable evals, dashboard, benchmark adapters | Grade complete trajectories in CI and publish versioned pass rates by category |
+| Browser and computer-use workflows | Covered | `/browser`, `/chrome`, Playwright-aware tasks, plus bounded Electron desktop fixtures with assertions, teardown, masked screenshots, and optional raw video/trace only when selector redaction is disabled | Add OS-native non-Electron fixtures behind equally testable drivers |
+| Provenance and citations | Partial | WebFetch source URLs, `/cite`, `/graph`, `/trace`, evidence ledgers, and task-memory citations with digest freshness | Add authenticated reopening for user citations and explicit network refresh for web/MCP citations |
+| Evals and observability | Covered | isolated eval worktrees, redacted structured trajectories, policy/outcome/cost/duration CI gates, reliability reports, dashboards, benchmark adapters, and OpenTelemetry | Publish opt-in signed versioned pass-rate snapshots by category |
 | Standard GenAI telemetry | Covered | Explicit OTLP/console exporters; GenAI inference, agent/workflow, tool, memory, token, cache, response, latency, streaming time-to-first-chunk/inter-output-chunk, and error semantics; content off by default | Add trajectory policy graders and cross-provider dashboards without increasing content capture/cardinality |
 | Test-first execution | Covered | `ur test-first` detects compile/test/lint commands, stores failure traces, retries through a fix agent, and installs detected commands into `.ur/verify.json` for edit-time gates | Add per-package command plans for large monorepos |
 | Security and prompt-injection resistance | Covered | allow/ask/deny permissions, shell safety analysis, secret scan, untrusted web-content guidance, OS-level execution sandbox (macOS Seatbelt, Linux bubblewrap) | Continuously test web/MCP/repository/skill/memory injection, confused-deputy, and tool-abuse cases |
@@ -94,9 +99,9 @@ Inside an interactive session:
 | Multimodal workflows | Partial | `/image`, `/video`, `/youtube`, `/voice`, browser workflows | Add model-aware multimodal capability reporting for local Ollama setups |
 | Spec-driven development | Covered | `ur spec` scaffolds requirements/design/tasks under `.ur/specs/`, tracks phase/approvals, and runs the Spec Kit / Kiro task list one task at a time | Add bidirectional sync with an external `specs/` directory |
 | Capability-aware model escalation | Covered | `ur escalate` selects fast/oracle tiers from `model-doctor`, runs routine work fast, and auto-escalates hard/failed work to the strong local model | Learn per-model success rates to tune the difficulty threshold |
-| Best-of-N agent judging | Covered | `ur arena` runs N agents per task in isolated worktrees and judges diffs with the self-review gate; winner is selectable/appliable | Add an optional model judge alongside the deterministic scorer |
-| Self-healing CI | Covered | `ur ci-loop` reports its resolved cwd, preserves assertion/stack context, stops no-test configuration failures before invoking a fixer, and re-runs real failures with bounded retries; commits/pushes require explicit flags and are self-review gated | Wire to `ur trigger` so a failed CI webhook can explicitly launch the loop |
-| Verifiable artifacts | Covered | `ur artifacts` records plans/diffs/test-runs with approve/reject/feedback under `.ur/artifacts/`; comments steer active background agents through stream-json inbox injection | Attach browser-QA screenshots and link artifacts to claim-ledger entries |
+| Best-of-N agent judging | Covered | `ur arena` verifies isolated candidates, gates safety eligibility, and supports deterministic, strict anonymous model, or hybrid judging with clean-base apply | Calibrate judge agreement across local/provider model families |
+| Self-healing and agentic CI | Covered | bounded repair loops plus `ur agent-ci` actor policy, isolated worktrees, credential separation, safe event ingestion, redacted/hash-addressed artifacts, and separate publishing | Add forge-neutral workflow compilers with the same trust split |
+| Verifiable artifacts | Covered | plans/diffs/tests plus hashed screenshot attachments and privacy-compatible optional video/trace attachments, approve/reject/feedback, local previews, and steering links | Link every QA attachment directly to claim-ledger entries |
 | Native IDE review | Covered | `ur ide diff` bundles, a VS Code tree/webview/comment surface with background task controls, and a buildable JetBrains ACP client with cancellation | Add signed marketplace packaging and keep behavior parity covered in editor-host integration tests |
 | ACP / IDE agent server | Covered | Official-SDK ACP v1 with durable list/load/delete/resume/close, exact replay, modes, config options, commands, permissions, MCP, roots, streaming, and cancellation | Add editor-host interoperability fixtures before expanding optional UX capabilities |
 | Provider-native durable inference | Covered | Chat Completions remains default; opt-in Responses adds SSE, background polling/cancel, WebSocket continuation, compaction, deferred tools, and `store=false` | Generalize explicit provider capability discovery without silently emulating native features |
@@ -153,26 +158,26 @@ and model selection are explicit, credentials are resolved through the
 credential layer, and the optional fallback setting is diagnostic advice rather
 than an automatic provider switch.
 
-## v1.47 Frontier Priorities
+## v1.48 Frontier Priorities
 
-The `1.46.0` frontier set is implemented in `1.47.0`. A second free/open-source
-scan after the version bump also closed AG-UI frontend interoperability,
-cross-client `.agents/skills/` discovery, and the latest OpenTelemetry
-`invoke_workflow`/streaming-chunk latency gap. The remaining ordered backlog keeps
-prerelease protocols opt-in and focuses on evidence and trust:
+The `1.48.0` work closes the managed-worker, steering, learned-playbook,
+cited-memory, Agentic CI, trajectory-grading, desktop-QA, durable-side-chat,
+multi-repository, and model-judge gaps from the 2026-07-26 scan. The remaining
+ordered backlog keeps prerelease protocols opt-in and focuses on evidence and
+trust:
 
 1. Adopt final MCP 2026 and stable A2A v1 SDK artifacts when published, while
    preserving dual-stack negotiation and independent-client fixtures.
 2. Add A2A signed-card verification, streaming/resubscription, and push only
    with authenticated end-to-end conformance tests.
-3. Extend task-memory provenance, deletion proofs, quarantine, and rollback to
-   every team, semantic, embedding-backed, and legacy memory store.
-4. Turn trajectory graders for tool choice, handoffs, policy compliance,
-   recovery, and outcome quality into versioned CI regression gates.
+3. Extend task-memory citations, deletion proofs, quarantine, and rollback to
+   every semantic, embedding-backed, and legacy memory store.
+4. Publish opt-in, signed, versioned trajectory/outcome pass-rate snapshots and
+   calibrate model-judge agreement without capturing prompt/tool content.
 5. Require registry attestations, dependency review, revocation, and update
    transparency before one-command community skill/plugin installation.
-6. Enforce claim-to-source links for final web/MCP answers and complete Windows
-   OS-sandbox parity.
+6. Reopen authenticated user citations, explicitly refresh web/MCP citations,
+   enforce final claim-to-source links, and complete Windows OS-sandbox parity.
 
 ## Source And Trust Policy
 

package/docs/CONFIGURATION.md

@@ -437,7 +437,10 @@ ur context-pack remember --decision "Use package scripts before ad hoc commands"
 ur context-pack remember --constraint "Do not expose secret values"
 ur context-pack remember --command "bun run typecheck"
 ur context-pack remember --diff "Safety policy wired into Bash permission checks"
+ur context-pack remember --decision "Keep streaming" --cite-file src/parser.ts --lines 20:48
 ur context-pack memory verify
+ur context-pack memory revalidate
+ur context-pack memory search --query "streaming"
 ur context-pack memory quarantine
 ur context-pack memory rollback --to <entry-id>
 ur context-pack compress
@@ -451,8 +454,10 @@ Generated files:
   other manifests.
 - `.ur/context/architecture.md` — human-readable architecture summary.
 - `.ur/context/task-memory.jsonl` — private, append-only decisions,
-  constraints, commands, diffs, and notes with explicit provenance, UUIDs, and
-  a SHA-256 content/hash chain. Legacy entries are anchored when the chain
+  constraints, commands, diffs, and notes with explicit provenance, optional
+  file/run/user/web citations, UUIDs, and a SHA-256 content/hash chain. File
+  and run citations are digest-revalidated; stale and superseded entries are
+  excluded from normal resolution. Legacy entries are anchored when the chain
   starts rather than silently rewritten.
 - `.ur/context/compressed.md` — compressed task context summary.
 

package/docs/FRONTIER_AGENT_FEATURES.md

@@ -0,0 +1,210 @@
+# Frontier Agent Workflows
+
+UR 1.48 adds ten production-oriented agent capabilities. They are designed
+around explicit trust boundaries: no command in this document silently
+publishes, deploys, pushes, opens a pull request, or bypasses permissions.
+
+## Managed cloud workers and steering
+
+Run verified best-of-N worktrees locally, or launch multiple isolated
+candidates in a managed UR environment:
+
+```sh
+ur cloud environments
+ur cloud run "fix the parser race" --runner managed --environment <id> --attempts 3
+ur cloud sync
+ur cloud show <task-id>
+ur cloud logs <task-id> --tail 200
+ur cloud steer <task-id> --message "preserve the public API" --request-id review-1
+ur cloud cancel <task-id>
+```
+
+Managed session IDs, cursors, branches, bounded output, and idempotent steering
+receipts survive CLI restarts in the private cloud-task manifest. Managed mode
+does not claim comparative quality judging: after every candidate terminates,
+UR deterministically ranks candidates that returned PASS with a safe, nonempty
+review branch and reports the first eligible branch as the selection. UR never
+fetches or merges it automatically. Cancellation remains terminal when a
+remote session finishes starting concurrently. Local background agents
+support the same bounded steering pattern:
+
+```sh
+ur bg steer <task-id> --message "also cover the timeout case" --request-id timeout-1
+```
+
+Authenticated A2A compatibility tasks expose owner-isolated mobile steering at
+`POST /a2a/tasks/<id>/messages` (or `/steer`) with:
+
+```json
+{"message":"run the focused regression test","requestId":"mobile-1"}
+```
+
+The task must belong to the authenticated caller and be backed by a running
+background agent. Messages are size-bounded, terminal tasks reject new input,
+and repeated request IDs are deduplicated.
+
+## Evidence-backed learned playbooks
+
+UR can mine repeated, verified run trajectories into candidates:
+
+```sh
+ur learn playbooks mine --min-runs 3
+ur learn playbooks list --status candidate
+ur learn playbooks show <id>
+ur learn playbooks approve <id> --name parser-repair
+ur learn playbooks run <id> --max-concurrency 2
+ur learn playbooks reject <id> --reason "insufficient coverage"
+ur learn playbooks disable <id>
+```
+
+Candidates require successful command evidence and a confidence floor. Unsafe,
+secret-like, publishing, deployment, or destructive trajectories are excluded.
+Promotion is always explicit. Approval materializes a normal validated workflow;
+rejected candidates cannot later be approved. Disabling verifies that the
+promoted workflow is unchanged, moves it to a private
+`.ur/learning/disabled/*.yaml.disabled` archive, and prevents future runs.
+
+## Citation-validated shared memory
+
+Task memory can cite project files, run artifacts, user messages, and web
+sources:
+
+```sh
+ur context-pack remember --decision "Keep the parser streaming" \
+  --cite-file src/parser.ts --lines 20:48
+ur context-pack remember --note "Regression passed" \
+  --cite-run <run-id>:manifest.json
+ur context-pack remember --constraint "Keep the public API" \
+  --cite-user <session-id>:<message-id>
+ur context-pack remember --note "Protocol requirement" \
+  --cite-web https://example.com/spec
+ur context-pack memory revalidate
+ur context-pack memory search --query "parser streaming"
+```
+
+File excerpts and run artifacts carry captured SHA-256 digests. Resolution
+excludes rejected, superseded, missing, and stale entries by default and emits
+bounded source labels suitable for prompts. User and web citations remain
+explicitly unverifiable until their source is reopened; UR does not make a
+network request merely because memory was searched.
+
+## Agentic CI and trajectory gates
+
+Create a policy and a pinned, read-only GitHub workflow:
+
+```sh
+ur agent-ci init default
+ur agent-ci validate default
+ur agent-ci workflow default --force
+ur agent-ci run default --event "$GITHUB_EVENT_PATH" \
+  --event-name "$GITHUB_EVENT_NAME" --output-dir "$RUNNER_TEMP/ur-agentic-ci"
+```
+
+The agent job checks out a trusted base without persisted credentials, accepts
+issue comments only from configured repository associations, consumes event
+JSON from a file rather than shell source, scrubs code-subprocess secrets, and
+runs in a detached worktree. It emits a bounded, hash-addressed patch, redacted
+check tails, and a manifest. Path policy uses exact NUL-delimited Git records,
+so control characters cannot alter parsing and rename sources remain visible
+as removals. UR hashes staged, unstaged, tracked/untracked, and index-visibility
+state before and after checks. Any mutation blocks and suppresses the patch;
+otherwise the post-check patch is bound to `verificationStateSha256`.
+Publishing belongs in a separate trusted job or a human review step.
+
+Eval cases may declare structured trajectory rules in `expect.trajectory`,
+including required, forbidden, ordered, and successfully completed tools;
+tool-call, failure, repetition, permission-denial, and turn limits. Captured
+events retain control-flow metadata only—never prompts, paths, tool input,
+tool output, or assistant text.
+
+```sh
+ur eval run starter
+ur eval gate starter --min-pass-rate 1 --min-trajectory-score 0.9
+```
+
+Eval cases use detached worktrees by default. `--no-isolate` is an explicit
+opt-out. A requested gate fails closed when its metric is unavailable.
+
+## Desktop application QA
+
+Desktop QA drives Electron applications through bounded declarative fixtures:
+
+```sh
+ur desktop-qa init
+ur desktop-qa validate .ur/desktop-qa/fixtures/smoke.json
+ur desktop-qa doctor
+ur desktop-qa run .ur/desktop-qa/fixtures/smoke.json
+```
+
+Fixtures support click, fill, key press, select, checkbox, wait, text/visibility
+assertions, and screenshots. Every run closes the application, redacts
+secret-like diagnostics, and records bounded evidence with hashes and a JSON
+report. Selector redaction is applied to screenshots as an opaque mask. Because
+raw video and trace data cannot guarantee that mask, fixtures with
+`redactSelectors` must disable both `recording.video` and `recording.trace` or
+validation fails closed. A failed assertion exits non-zero, making the command
+suitable for CI. Attachment persistence copies only bounded regular
+non-symlink files. The loopback viewer serves a small image/video allow-list
+inline; every other type becomes an octet-stream download with private/no-store
+and sandbox headers.
+
+## Durable side chats
+
+`/btw` now keeps private, hash-chained side-chat history outside the repository:
+
+```text
+/btw Why does this parser use a sentinel?
+/btw continue <chat-id> What invariant does it protect?
+/btw list
+/btw show <chat-id>
+/btw rename <chat-id> Parser notes
+/btw close <chat-id>
+```
+
+Each invocation is still a one-turn, tool-free fork, so the main task continues
+independently. History, individual turns, chat count, and storage size are
+bounded; cancellation reaches the forked request.
+
+## Multi-repository coordination
+
+Define repositories and a dependency DAG, then run one writer per repository
+in isolated worktrees:
+
+```sh
+ur workspace init checkout
+ur workspace add checkout api ../api --base main --verify "bun test"
+ur workspace add checkout web ../web --base main --verify "bun test"
+ur workspace task checkout api-contract --repo api \
+  --prompt "add the checkout response field"
+ur workspace task checkout web-client --repo web \
+  --prompt "consume the checkout response field" --depends-on api-contract
+ur workspace validate checkout
+ur workspace run checkout --max-concurrency 4
+ur workspace verify checkout
+ur workspace pr-plan checkout
+ur workspace rollback-plan checkout
+```
+
+Enrollment pins each canonical repository root and a hash of its remote
+identity. The durable run state refuses resume after the specification changes.
+Tasks with dependencies wait; tasks targeting the same repository serialize.
+PR and rollback commands are plans only. Every repository retains its own base
+branch, while cross-repository dependencies determine review order.
+
+## Verified model-judged best-of-N
+
+Arena candidates are eligible only after a proof-backed `PASS`, a non-empty
+bounded diff, safety review, and all configured verification commands:
+
+```sh
+ur arena "repair the cache race" --agents 3 \
+  --judge hybrid --judge-model <model> \
+  --verify "bun run typecheck" --verify "bun test"
+```
+
+`deterministic`, `model`, and `hybrid` modes are supported. The model judge sees
+bounded, secret-redacted, anonymous candidate material and must return a strict
+schema referring only to eligible candidate IDs. A candidate whose full
+redacted diff exceeds the judge bound is excluded rather than partially judged.
+Invalid judge output yields no winner. `--apply` additionally requires the
+original clean worktree and exact base commit to remain unchanged.

package/docs/USAGE.md

@@ -221,16 +221,22 @@ ur context-pack remember --preference "Use bun test over jest"
 ur context-pack remember --accepted "Use p-map for bounded concurrency" --scope project
 ur context-pack remember --rejected "Switch to esbuild" --alternative-to "Keep bun bundle"
 ur context-pack remember --attempt "Tried Deno runtime" --status superseded
+ur context-pack remember --decision "Keep streaming" --cite-file src/parser.ts --lines 20:48
 ur context-pack memory verify
+ur context-pack memory revalidate
+ur context-pack memory search --query "streaming"
 ur context-pack memory quarantine
 ur context-pack memory rollback --to <entry-id>
 ur context-pack compress
 ```
 
-New entries carry explicit source provenance and form a SHA-256 hash chain.
-Reads fail closed on malformed or tampered state. `quarantine` preserves the
-complete original privately and restores the verified prefix; `rollback`
-preserves a backup before truncating to the requested entry.
+New entries carry explicit source provenance, optional file/run/user/web
+citations, and form a SHA-256 hash chain. File and run citations are rechecked
+against captured content digests; stale and superseded memory is excluded from
+normal resolution. Reads fail closed on malformed or tampered state.
+`quarantine` preserves the complete original privately and restores the
+verified prefix; `rollback` preserves a backup before truncating to the
+requested entry.
 
 ## Lifecycle hooks
 
@@ -273,7 +279,16 @@ UR includes slash commands and CLI subcommands for common workflows:
 - `ur agents` to list configured agents
 - `ur agent-trends` to inspect coverage for current agent technology trends
 - `ur a2a card` to print UR's Agent Card metadata for A2A discovery
-- `ur bg ...` to run detached local background agents with optional worktrees and PRs
+- `ur bg ...` to run and idempotently steer detached local background agents
+  with optional worktrees and PRs
+- `ur cloud ...` to run, synchronize, steer, and cancel local or managed
+  best-of-N workers; managed selection requires explicit `PASS` plus a safe
+  review branch and never fetches or merges it
+- `ur agent-ci ...` to generate and run a policy-gated isolated CI agent that
+  emits only a post-check, state-bound patch and manifest
+- `ur workspace ...` to coordinate dependency-aware changes across repositories
+- `ur learn playbooks ...` to mine and explicitly approve reusable workflows
+- `/btw ...` to create or continue private durable tool-free side chats
 - `ur repo-edit ...` to index the repo, plan AST-aware renames, preview patches, and apply with rollback
 - `ur safety ...` to inspect project shell safety policy and preview command risk
 - `ur context-pack ...` to summarize architecture and persist project memory (decisions, constraints, commands, diffs, architecture, preferences, attempts, accepted, rejected)
@@ -284,18 +299,24 @@ UR includes slash commands and CLI subcommands for common workflows:
 - `ur memory retention ...` to prune project-local memory by TTL, max entries, and decay
 - `ur spec ...` to scaffold requirements, design, and tasks, run a spec task list, and verify with strict proof gates
 - `ur escalate ...` to plan, run, or ask an oracle model for hard tasks
-- `ur arena ...` to run multiple agents on the same task and select a winner
+- `ur arena ...` to verify multiple isolated candidates and select a winner
+  with deterministic, model, or hybrid judging; oversized full diffs are
+  excluded from model judging
 - `ur test-first ...` to detect compile/test/lint commands, store failure traces, and install after-edit gates
 - `ur ci-loop ...` to run tests in an explicit working directory, repair real
   failures, and rerun with a bounded loop. A "No tests found" result stops
   after one attempt and reports how to correct `--cwd`.
-- `ur artifacts ...` to capture reviewable diffs, test runs, notes, and feedback
+- `ur artifacts ...` to capture reviewable diffs, test runs, notes, feedback,
+  and bounded non-symlink attachments with safe download headers/MIME fallback
 - `ur ide diff ...` to capture editor-readable inline diff bundles
 - `ur acp stdio` for the official-SDK ACP v1 editor transport with durable
   list/load/delete/resume, modes, config options, and commands; and
   `ur acp serve|stop|status` for the separate UR HTTP JSON-RPC API
 - `ur exec ...` to run prompts in non-interactive mode with optional concurrency
-- `ur eval run ...` to run a suite, grade results, and capture execution metrics
+- `ur eval run ...` to run isolated cases, grade redacted tool trajectories,
+  and capture execution metrics
+- `ur eval gate ...` to enforce pass, trajectory, test, cost, duration, and
+  regression thresholds
 - `ur eval report ...` to show a saved report or write a single-suite dashboard
 - `ur eval dashboard` to generate the local HTML dashboard across all reports
 - `ur eval bench ...` to import local SWE-bench, Terminal-Bench, or Aider Polyglot exports
@@ -314,6 +335,8 @@ UR includes slash commands and CLI subcommands for common workflows:
 - `ur model-doctor` and `ur model-route ...` to inspect local Ollama models and pick one by capability fit
 - `ur local-first` to report readiness for offline/no-cloud environments
 - `ur browser-qa ...` to validate and smoke-run browser QA replay fixtures
+- `ur desktop-qa ...` to run Electron fixtures with hashed masked screenshots;
+  raw video/trace requires selector redaction to be disabled
 - `ur trigger ...` to parse GitHub/Slack webhook payloads and optionally launch a headless run
 - `ur agent-templates ...`, `ur agent-task ...`, `ur agent-inspect`, `ur agent-features`, and `ur agent-trends` for agent template, PR handoff, timeline, and coverage utilities
 - `ur role-mode ...` to install built-in Architect, Code, Debug, and Ask role modes
@@ -330,6 +353,10 @@ Source checkouts print
 `Development build detected. To update, pull latest source or install from npm.`
 instead of attempting to mutate the checkout.
 
+See [Frontier Agent Workflows](FRONTIER_AGENT_FEATURES.md) for the complete
+managed-worker, steering, learned-playbook, cited-memory, Agentic CI,
+trajectory, desktop-QA, side-chat, multi-repository, and arena trust model.
+
 ## Status bar
 
 Interactive sessions include a compact bottom status bar when stdout is a real
@@ -368,7 +395,9 @@ ur spec init demo --goal "1. add a utils.add function 2. add a test"
 ur spec run demo --all --dry-run
 ur spec run demo --all --kernel
 ur spec verify demo --kernel
-ur arena "implement a debounce helper" --agents 2 --dry-run
+ur arena "implement a debounce helper" --agents 3 --judge hybrid --verify "bun test"
+ur agent-ci init default
+ur cloud run "fix the parser race" --runner managed --attempts 3
 ur escalate run "refactor the cache layer" --force-oracle --dry-run
 ur test-first detect
 ur test-first --dry-run
@@ -383,7 +412,9 @@ ur safety check --command "rm -rf build"
 ur context-pack scan
 ur context-pack remember --constraint "Run command evidence before claiming success"
 ur context-pack remember --accepted "Use p-map for concurrency" --scope project
+ur context-pack remember --decision "Keep streaming" --cite-file src/parser.ts --lines 20:48
 ur context-pack memory verify
+ur context-pack memory revalidate
 ur context-pack compress
 UR_MCP_HTTP_TOKEN='<secret>' ur mcp serve-http --port 8976
 ur acp serve --port 8123
@@ -391,6 +422,9 @@ ur exec "add tests for the parser" --concurrency 4 --json
 ur ci-loop --command "bun test" --cwd . --dry-run
 ur artifacts capture-diff
 ur bg run "fix the flaky parser test" --worktree --dry-run
+ur learn playbooks mine --min-runs 3
+ur workspace init checkout
+ur desktop-qa validate .ur/desktop-qa/fixtures/smoke.json
 ur worktree list
 ur worktree clean --dry-run
 ur repo-edit index
@@ -401,6 +435,7 @@ ur ide diff capture --title "Working tree review"
 ur eval bench list
 ur eval run starter --dry-run --json
 ur eval run starter --metrics --json
+ur eval gate starter --min-pass-rate 1 --min-trajectory-score 0.9
 ur eval report starter --dashboard
 ur eval dashboard
 ur crew create parser-crew --goal "fix the flaky parser test" --decompose --dry-run

package/docs/VALIDATION.md

@@ -19,7 +19,7 @@ You need:
 
 ```sh
 ur --version
-# expected for this release: "1.47.1 (UR-Nexus)"
+# expected for this release: "1.48.0 (UR-Nexus)"
 ```
 
 ## 0.1 First-workspace model selection (1.45.4)
@@ -179,6 +179,67 @@ bun run release:check
 bun run package:check
 ```
 
+## 0.7 Frontier agent workflow gates
+
+These deterministic suites use temporary repositories, fake managed-cloud
+clients, injected runners, and mock desktop drivers. They make no paid model
+calls:
+
+```sh
+bun test test/cloudDesktopQa.test.ts
+bun test test/learnedPlaybooks.test.ts test/memoryCitations.test.ts
+bun test test/agenticCi.test.ts test/trajectoryCapture.test.ts
+bun test test/sideChats.test.ts test/workspaceCoordinator.test.ts
+bun test test/arenaModelJudge.test.ts
+```
+
+Expected coverage:
+
+- Managed cloud fan-out selects only completed candidates with explicit
+  `PASS` and safe non-empty review branches. Ordering is deterministic and
+  never fetches or merges a branch. Cancellation remains terminal even when a
+  remote session finishes starting concurrently.
+- Cloud, local-background, and owner-scoped A2A steering reject terminal or
+  foreign tasks, bound message/receipt storage, and deduplicate request IDs
+  before delivery.
+- Learned playbooks require proof-backed safe evidence and explicit approval.
+  Rejection is terminal; disable verifies the promoted workflow, moves it to
+  the private disabled archive, and prevents execution.
+- Cited memory revalidates file excerpts and run artifacts by digest, excludes
+  stale/missing entries by default, and leaves user/web sources explicitly
+  unverifiable without reopening them.
+- Agentic CI treats event text as data, uses a read-only pinned workflow,
+  isolates credentials, checks deletion/rename-source and path policy using
+  exact NUL-delimited Git metadata, and emits only a bounded hash-addressed
+  patch plus its manifest. A passing verification command that changes staged,
+  unstaged, untracked, or index-visible state must block and emit no patch.
+- Trajectory capture retains control-flow metadata only. Requested trajectory
+  or report metrics fail closed when absent or below the configured gate.
+- Desktop QA tears down on every path, masks configured screenshot selectors,
+  and refuses raw video or trace recording whenever selector redaction is
+  configured. Artifact evidence rejects symlink sources and normalizes unsafe
+  MIME declarations to a safe type; downloads use a bounded store path,
+  no-store/sandbox headers, a small safe inline allow-list, and octet-stream
+  fallback.
+- Side chats survive reload, validate their hash chain, stay tool-free and
+  bounded, and reject continuation after close.
+- Workspace coordination validates remote identity and the dependency DAG,
+  permits independent repositories to run concurrently, serializes one writer
+  per repository, refuses changed-spec resume, and produces PR/rollback plans
+  without executing them.
+- Arena model/hybrid judging sees only bounded, redacted, anonymous eligible
+  candidates; an oversized full diff is excluded rather than partially judged,
+  invalid decisions yield no winner, and apply requires the original clean
+  base.
+
+Check the public documentation surfaces after any contract change:
+
+```sh
+bun test test/docsCommands.test.ts test/docsCoverage.test.ts
+node --check documentation/app.js
+bun run lint
+```
+
 ## 1. Marketplace tree resolves
 
 In a fresh interactive session: