feat: ship agent-first mission control v0.2.57

docs/audits/2026-07-30/agent-first-performance-v2/IMPLEMENTATION_AND_ACCEPTANCE.md

@@ -0,0 +1,347 @@
+# Nexus Agent-first and Performance V2 — implementation and acceptance
+
+**Milestone date:** 2026-07-30
+**Final documentation review:** 2026-07-30
+**Scope:** local combined working tree; no commit, push, deployment or VPS write
+**Outcome:** core architecture implemented locally; production provisioning,
+live OpenClaw acceptance and measured load gates remain blocked or unproven
+
+## Executive verdict
+
+Nexus now has a coherent durable path for owner-approved agent proposals,
+PostgreSQL-backed workflow events, typed frontend contracts and an efficient
+Task Board read model. The implementation materially reduces duplicate
+requests and broad refreshes for the migrated domains.
+
+This is not a production-readiness or performance-budget claim:
+
+- productive OpenClaw writes remain intentionally disabled until a pinned
+  OpenClaw release officially supports an external Nexus or generic operator
+  Client ID;
+- no real OpenClaw pairing, agent creation or
+  `Nexus -> OpenClaw -> OpenAI -> Nexus` write flow was performed;
+- the controlled Playwright server is synthetic;
+- Docker/Testcontainers, Toxiproxy, k6, Promptfoo live evaluation,
+  `EXPLAIN (ANALYZE, BUFFERS)` and the browser p95 budget require separate,
+  isolated acceptance runs.
+
+## Implemented architecture
+
+### One typed API contract
+
+- ASP.NET Core emits OpenAPI 3.1 to
+  `backend/openapi/Nexus.Api.json`.
+- `openapi-typescript` generates
+  `frontend/src/api/generated/schema.d.ts`; `openapi-fetch` is the typed
+  transport for migrated endpoints.
+- CI regenerates the schema and rejects a diff.
+- `ProblemDetails` and `ValidationProblemDetails` are the common HTTP error
+  shape. The server attaches `traceId`; the frontend uses one error adapter.
+- `EntityRefDto`, `OperationResultDto`, `DomainEventDto` and
+  `TaskBoardPageDto` are explicit public contracts rather than view-model
+  inference.
+
+### Server-state migration
+
+TanStack Vue Query owns the migrated server state:
+
+- Task Board;
+- projects and project-scoped tasks;
+- agent proposals and create options;
+- Nexus activity and notifications;
+- OpenClaw overview, agents, runs, cron and models;
+- agent details and configuration reads; and
+- owner-only Memory, Docs, Incidents and Security reads.
+
+The Query-key factory makes multiple consumers share one request. Background
+refresh keeps previous visible data. Pinia still owns authentication, command
+and Iris modal state, setup/wizard workflow state, local drafts and shared
+mutation facades; it does not duplicate canonical runtime collections.
+
+After route and error-state parity checks, the legacy operations/task/
+notification/dashboard server-state stores, static agent inventory and
+mappers, duplicate `liveSync.ts`/`live-sync.ts` modules and the old generic
+live-service reader were removed. The backend compatibility endpoints remain
+temporarily available, but no active frontend consumer uses them as its
+canonical cache.
+
+Memory, Docs and Incidents no longer use host workspace mounts. Their
+owner-only services read OpenClaw workspace content through confined RPC,
+return source-agent and workspace-path provenance and expose no arbitrary
+workspace write path.
+
+### PostgreSQL workflow and event backbone
+
+Migration `20260730224500_AddAgentProvisioningAndBoardIndexes` adds:
+
+- `AgentProposals`;
+- `AgentProvisionRequests`;
+- `OperationClaims`; and
+- `OutboxEvents`.
+
+For migrated Nexus-owned mutations, domain state and outbox event are stored in
+the same EF transaction. The registered OpenClaw mutation claim store also uses
+PostgreSQL `OperationClaims` plus a database transaction and lock; the former
+JSONL path is exposed only for discovery of an immutable legacy archive and is
+not read or appended. The background worker:
+
+- leases pending work with `FOR UPDATE SKIP LOCKED`;
+- uses a bounded single-process wake-up channel plus database polling for
+  restart recovery;
+- publishes content-minimized events to subscriber queues of 64 entries;
+- retains at least 24 hours and at least 10,000 global sequences; and
+- exposes at most 512 replay deltas per reconnect.
+
+`GET /api/v1/events?afterSequence=` resumes by global sequence. A missing or
+expired range produces `resync_required`; the browser refreshes affected Query
+domains rather than silently accepting a gap. The existing OpenClaw event
+projection remains a separate sanitized Runtime adapter during migration.
+
+### Authenticated SSE hub
+
+The frontend uses one fetch-based `AuthenticatedSseHub` with:
+
+- bearer authentication and the existing refresh path;
+- `eventsource-parser`;
+- abort and subscriber lifecycle;
+- heartbeat detection;
+- jittered reconnect; and
+- a 256 KiB maximum parser buffer.
+
+Task events normally reconcile one card through
+`GET /api/v1/tasks/{id}/board-card`. Other events batch small Query-domain
+invalidations. The Dashboard legacy SSE path was hardened for cursor
+continuation and cancellation but remains a compatibility surface.
+
+## Agent proposal and provisioning flow
+
+### Shared flow
+
+The manual `/agents/new` UI and Iris use the same durable service:
+
+```text
+local form draft -> awaiting_approval -> provisioning
+                                      -> ready | partial | failed | in_doubt
+                 -> rejected
+```
+
+New APIs:
+
+- `GET /api/v1/openclaw/agents/create-options`
+- `GET|POST /api/v1/openclaw/agent-proposals`
+- `GET /api/v1/openclaw/agent-proposals/{proposalId}`
+- `POST /api/v1/openclaw/agent-proposals/{proposalId}/approve`
+- `POST /api/v1/openclaw/agent-proposals/{proposalId}/reject`
+- `POST /api/v1/openclaw/agent-proposals/{proposalId}/retry`
+
+Proposal lists use a stable `(CreatedAt, Id)` keyset cursor, including equal
+timestamps. Owner mutations require an Idempotency Key, correlation ID,
+optimistic proposal revision and authenticated actor.
+
+### Iris boundary
+
+Iris receives only:
+
+- `nexus_propose_agent`; and
+- `nexus_get_agent_proposal`.
+
+Both MCP tools return structured content and stable state/error information.
+They cannot approve a proposal or call OpenClaw. Tool annotations describe
+read-only, destructive, idempotent and open-world behavior but are not used as
+authorization.
+
+### Provisioning safety
+
+After explicit owner approval, Nexus rechecks:
+
+- local `ManagementEnabled`;
+- official external Client-ID support;
+- normalized endpoint and TLS trust;
+- current capability hash and required advertised methods;
+- `operator.admin`;
+- proposal revision; and
+- idempotency claim.
+
+The workspace root is server-controlled and checked against live OpenClaw
+configuration. Nexus calls `agents.create` at most once. After a possible
+dispatch timeout it records `in_doubt` and permits only read-only inventory
+reconciliation before another action. A successful create is not `ready` until
+`agents.list` confirms it. Approved standard files are written through
+`agents.files.set` and read back; a later file failure becomes `partial` and
+does not trigger automatic deletion.
+
+The production button remains disabled because OpenClaw `2026.7.1` does not
+register the required external Nexus/generic operator identity. Nexus does not
+impersonate CLI, Control UI or `gateway-client/backend`.
+
+## Task Board V2
+
+`GET /api/v1/tasks/board?doneLimit=50&doneCursor=` returns:
+
+- every non-Done card on the initial page;
+- the newest 50 Done cards by default;
+- an opaque `(UpdatedAt, Id)` keyset cursor for further Done pages; and
+- a stable board revision.
+
+The repository uses `AsNoTracking` and direct DTO projection. Child counts and
+latest activity are correlated scalar projections rather than N+1 reads. The
+initial path uses at most three SQL statements; a Done continuation skips the
+active-card query and uses two. The migration adds state, partial Done,
+activity, child and agent-workflow indexes.
+
+The Vue client uses `useInfiniteQuery`, deduplicates Done cards and keeps all
+active columns mounted for drag-and-drop. Moves are optimistic and roll back on
+failure. Create, update, move and domain events fetch only the affected
+`board-card`; full invalidation is a recovery path. Dashboard, sidebar,
+Command Palette and Task Board use the same Query key instead of parallel board
+loads.
+
+No claim is made that the p95 budgets are met until the recorded
+1,000-task/10,000-activity dataset, k6 run, SQL trace/plans and repeated browser
+timing run have been executed.
+
+## Cross-page result navigation
+
+- `EntityRefDto` contains type, ID and optional label but no backend-generated
+  URL.
+- The frontend resolver maps agent, proposal, project, task, run, cron,
+  incident, document, notification and event-stream references to registered
+  routes.
+- Iris and proposal mutations can show `OperationResultCard` with primary and
+  affected entities plus operation/trace metadata.
+- Projects now have a real `/projects` index and
+  `GET /api/v1/projects/{id}/tasks`; Project Detail no longer loads unrelated
+  tasks.
+- Activity and Notifications use typed, authenticated domain queries and
+  navigate to available related entities.
+
+The 2026-07-31
+[structured operation-results follow-up](../../2026-07-31/operation-results-deep-links/IMPLEMENTATION_AND_ACCEPTANCE.md)
+closed the remaining task, project, notification, cron, config, approval,
+session and agent-file mutation gap. A global result tray now exposes the
+typed references and the addressed target surfaces consume their deep-link
+selection.
+
+## Resilience and observability
+
+- `Microsoft.Extensions.Http.Resilience` protects safe OpenClaw reads with a
+  10-second attempt timeout, 30-second total budget, bounded jittered retries
+  and a circuit breaker.
+- Management mutations and Chat/Run have no automatic retry; Gateway
+  WebSocket reconnect remains inside the connector.
+- OpenTelemetry instruments ASP.NET Core, HttpClient, Npgsql, Task Board,
+  Gateway RPC, proposals/provisioning, outbox and SSE-related metrics.
+- OTLP export is opt-in through configuration; no extra production container
+  is introduced.
+- `web-vitals` reports an allow-list of metric, value, rating, route name,
+  build version, live mode and correlation ID to
+  `POST /api/v1/telemetry/browser`.
+- Redaction removes URL queries/full URLs, SQL text, exception messages/stacks
+  and content-bearing attributes. Prompts, chat text, Markdown, tool arguments,
+  credentials, headers and entity names are not telemetry.
+
+## Dependency decisions
+
+Implemented and pinned:
+
+- `@tanstack/vue-query` `5.101.4`
+- `eventsource-parser` `3.1.0`
+- `openapi-fetch` `0.17.0`
+- `openapi-typescript` `7.13.0`
+- `web-vitals` `5.3.0`
+- Playwright `1.62.0`
+- Testcontainers PostgreSQL/Toxiproxy `4.13.0` in the test project only
+- OpenTelemetry `1.17.0`
+- `Microsoft.Extensions.Http.Resilience` `10.0.0`
+
+`ModelContextProtocol.AspNetCore` remains pinned to `1.4.1`. The
+`scripts/qa/test-mcp2-compatibility.ps1` candidate mode copies the project to a
+temporary directory and may probe `2.0.0`, but it cannot open the upgrade gate
+without isolated live OpenClaw negotiation. The local isolated `2.0.0`
+compile/test probe is green; production deliberately remains on `1.4.1`.
+
+Not introduced: Redis, NATS, Kafka, RabbitMQ, Temporal, Hangfire, Quartz,
+GraphQL, SignalR, RxJS, direct OpenAI Agents/Responses orchestration, OPA,
+OpenFGA, pgvector or a second production service.
+
+## Automated verification
+
+The following non-live checks were completed on 2026-07-30:
+
+| Gate | Result |
+|---|---|
+| .NET 10 / MCP `1.4.1` baseline | **Passed: 360; failed: 0; skipped: 5; total: 365** |
+| Isolated MCP `2.0.0` candidate copy | **Passed: 360; failed: 0; skipped: 5**; compatibility probe only |
+| MCP production pin/static markers | **Passed**; production project remains `1.4.1` |
+| Promptfoo wrapper `-ValidateOnly` | **Passed**; configuration only, no live evaluation |
+| PowerShell AST parse for all QA scripts | **Passed** |
+| `node --check` for k6, QA mock and Promptfoo provider | **Passed** |
+| Frontend typecheck | **Passed**; full Vue application and E2E TypeScript projects |
+| Frontend unit tests | **Passed: 12 files, 28 tests** |
+| Frontend production build | **Passed: 1,984 modules transformed** |
+| Playwright controlled contract suite | **Passed: 24 tests** across all 20 core routes and 375/768/1024/1440/1920 px |
+| Production dependency audit | **Passed**; no known vulnerabilities after pinning PostCSS `8.5.18` |
+| OpenAPI generation repeatability | **Passed**; checked-in backend contract and generated TypeScript schema were stable |
+
+The five skips are three explicitly gated PostgreSQL/Testcontainers
+provisioning tests, one Toxiproxy test and one PostgreSQL operation-claim
+concurrency test. Docker CLI was available but its daemon was not running.
+They were not executed and must not be described as passed integration
+evidence. The Playwright server is a controlled local contract fixture, not a
+real OpenClaw.
+
+## Not executed or not proven
+
+The following acceptance evidence was not produced by this milestone:
+
+1. real pairing or scope upgrade against Bao's OpenClaw;
+2. a live agent create, file write or recovery mutation;
+3. a complete `Nexus -> OpenClaw -> OpenAI -> Nexus` run;
+4. Docker-backed PostgreSQL/Toxiproxy evidence when the environment gate or
+   Docker daemon is unavailable;
+5. k6 p95 thresholds on a verified 1,000-task/10,000-activity fixture;
+6. `EXPLAIN (ANALYZE, BUFFERS)` and independent SQL-statement-count evidence;
+7. repeated browser `navigation -> cards visible` p95 evidence;
+8. live Promptfoo accuracy/injection evaluation against an isolated Nexus and
+   test OpenClaw;
+9. live MCP 2.0 `tools/list`, Streamable HTTP and down-level negotiation; and
+10. production OTLP or `pg_stat_statements` activation.
+
+The repository contains guarded scripts and tests for several of these checks.
+Static syntax/config validation proves only the artifacts, not their external
+systems or thresholds.
+
+## Residual work and release gates
+
+1. Obtain and pin official external Nexus/generic-operator Client-ID support.
+2. Run read-only pairing and inventory acceptance, then a separately approved
+   disposable management-write sequence.
+3. Run Docker integration, Toxiproxy, k6, SQL-plan, repeated browser and
+   Promptfoo release gates with archived sanitized evidence.
+4. Enable `pg_stat_statements` only through a separately approved PostgreSQL
+   maintenance window because it requires server configuration/restart.
+5. Reconsider virtualization, pgvector/QMD and external policy engines only
+   after measurements or multi-operator/tenant requirements justify them.
+
+## Primary code and evidence pointers
+
+- `backend/openapi/Nexus.Api.json`
+- `backend/Data/Migrations/20260730224500_AddAgentProvisioningAndBoardIndexes.cs`
+- `backend/Services/AgentProposalService.cs`
+- `backend/Services/DomainEventStreamService.cs`
+- `backend/Repositories/TaskRepository.cs`
+- `frontend/src/api/queryClient.ts`
+- `frontend/src/api/taskBoard.ts`
+- `frontend/src/services/sseHub.ts`
+- `frontend/src/services/domainEvents.ts`
+- `frontend/e2e/agent-proposals.e2e.ts`
+- `frontend/e2e/route-smoke.e2e.ts`
+- `frontend/e2e/task-board.e2e.ts`
+- [QA automation and evidence boundaries](../../../QA_AUTOMATION.md)
+- [Agent-first target contract](../../../AGENT_FIRST_MISSION_CONTROL.md)
+- [OpenClaw Attach & Adopt evidence](../openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md)
+
+## External compatibility reference
+
+- [OpenClaw `2026.7.1` client-ID registry](https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts)
+- [OpenClaw Gateway protocol](https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/gateway/protocol.md)

docs/audits/2026-07-30/openclaw-agent-first-hardening/ACCEPTANCE_EVIDENCE.md

@@ -0,0 +1,222 @@
+# OpenClaw Agent-first Hardening — Acceptance Evidence
+
+**Datum:** 2026-07-30
+**Scope:** Security-Grenze, Gateway-Verbindung, Mutationssicherheit,
+Eventprojektion, durable Runs, globaler Agent-first-Einstieg und wahrheitsgetreue
+Telemetrie
+**Ergebnis:** Lokale Implementierungs- und Testabnahme bestanden;
+Live-Gateway-/Produktionsabnahme offen
+
+## Abnahmeurteil
+
+Die sieben priorisierten Hardening-Punkte sind im aktuellen Working Tree
+implementiert und durch den unten dokumentierten automatisierten Baseline-Lauf
+abgesichert. Das ist kein Produktionsfreigabe-Nachweis: Es wurde in diesem
+Checkpoint weder ein reales Remote-Gerät gepaart noch ein vollständiger
+OpenClaw-/OpenAI-Lauf in der Zielumgebung ausgeführt.
+
+## 1. Security boundary
+
+**Status:** lokal abgenommen
+
+- `backend/Extensions/ServiceCollectionExtensions.cs` setzt eine
+  authentifizierte Fallback-Policy.
+- Nur Authentifizierungs-/Session-Bootstrap und explizite Health-Probes sind
+  anonym. Die OpenClaw-, Run-, Event-, Dashboard-, Task-, Agent- und
+  Security-Flächen bleiben geschützt.
+- `backend/Services/RequestAuthorizationHelper.cs` behandelt `X-Agent-Id` nur
+  nach bereits verifizierter Service- oder privilegierter User-Identität als
+  allow-gelisteten Actor-Hinweis.
+- OpenClaw-Control- und Run-Mutationen sind owner-only. Das MCP- und
+  Bridge-Datenplane akzeptiert verifiziertes JWT oder `X-Nexus-Api-Key`, aber
+  keinen frei gesetzten Agent-Header als Credential.
+- Negative Auth-, Rollen- und Header-Eskalationsfälle liegen in
+  `backend-tests/SecurityBoundaryTests.cs` sowie den fokussierten
+  Controller-/MCP-Tests.
+
+## 2. Reale Gateway-Verbindungsgrundlage
+
+**Status:** Protokoll und Pairing-Zustand implementiert; Live-Pairing offen
+
+- `backend/Services/OpenClawGatewayProtocol.cs` und
+  `backend/Services/GatewayConnector.cs` verwenden Protocol v4 und den
+  bestätigten Stable-Release-Pin `2026.7.1`. `2026.7.2-beta.1` ist als
+  Vorabversion bewusst nicht der Default.
+- Nur `127.0.0.1`, `::1` und `localhost` gelten als direkte Loopback-Topologie.
+- `backend/Services/OpenClawDeviceIdentityStore.cs` persistiert die
+  Ed25519-Geräteidentität und nach erfolgreichem Pairing den Device-Token.
+- Die Challenge-Signatur bindet die kanonische v3-Payload an den vom Gateway
+  gelieferten Nonce. `PAIRING_REQUIRED` samt konkreter Request-ID wird bis UI
+  und Settings weitergegeben.
+- Die Compose-Konfiguration hält Device- und Audit-Dateien in
+  `nexus-openclaw-device` über Container-Neustarts stabil.
+- Protokoll-, Versions-, Loopback-, Challenge-, Pairing- und
+  Persistenzverhalten wird durch `backend-tests/GatewayConnectorTests.cs`,
+  `backend-tests/OpenClawGatewayProtocolTests.cs` und
+  `backend-tests/OpenClawDeviceIdentityAndAuditTests.cs` geprüft.
+
+## 3. Zuverlässige Mutationen
+
+**Status:** lokal abgenommen; Single-Writer-Grenze bleibt
+
+- Frontend-Mutationen erzeugen über
+  `frontend/src/services/mutationContext.ts` einen Idempotency Key, eine
+  Correlation ID und einen gültigen W3C-`traceparent`.
+- Der Backend-Rand leitet den Actor ausschließlich aus dem authentifizierten
+  Principal ab. Die Invocation-Metadaten werden bis zum Gateway transportiert.
+- `backend/Services/OpenClawOperationAuditStore.cs` speichert einen
+  append-only Metadaten-Ledger mit gehashten Idempotency Keys, nicht Prompts,
+  Tool-Argumenten, Rohresultaten oder Credentials.
+- Ein gleicher Schlüssel und Intent liefert das vorhandene Ergebnis; ein
+  abweichender Intent wird abgelehnt. Ein nach Neustart nicht sicher
+  abgeschlossenes Ergebnis wird `in_doubt` und nicht automatisch wiederholt.
+- Geschlossene OpenClaw-Control-Schemas erhalten kein erfundenes
+  `params.idempotencyKey`. Nexus dedupliziert sie lokal. Durable Run-Aktionen
+  persistieren ihre Idempotency- und Transition-Daten zusätzlich in
+  PostgreSQL.
+
+## 4. Eventprojektion
+
+**Status:** lokal abgenommen
+
+- `GET /api/v1/openclaw/events` liefert authentifiziertes SSE.
+- `Last-Event-ID` und `lastEventId` unterstützen Replay aus dem begrenzten
+  Connector-Buffer.
+- Connection-, Heartbeat- und Gap-Events machen Verbindungs- und
+  Replay-Zustand explizit. Run-, Session-, Tool-, Approval-, Artifact- und
+  sonstige Gateway-Ereignisse werden klassifiziert, sequenziert und redigiert.
+- Sequenzlücken und Resets bleiben sichtbar; ein veralteter Cursor löst einen
+  autoritativen Refresh statt einer stillen Datenlücke aus.
+- `frontend/src/services/openclawLive.ts` und
+  `frontend/src/stores/openclaw.ts` verwenden SSE zuerst, reconnecten mit
+  begrenztem Backoff und fallen nur bei fehlender Live-Verbindung auf
+  60-Sekunden-Polling zurück.
+- Backend-Abdeckung:
+  `backend-tests/OpenClawEventProjectionTests.cs` und
+  `backend-tests/OpenClawEventSubscriptionCoordinatorTests.cs`.
+  Frontend-Abdeckung: `frontend/tests/openclaw-live.test.ts`.
+
+## 5. Durable Run
+
+**Status:** Start, Stop, Retry, Historie und Reconnect-Projektion lokal
+abgenommen; Same-run-Resume bewusst nicht verfügbar
+
+- Die Migration
+  `backend/Data/Migrations/20260730130442_AddOpenClawRunProjection.cs`
+  ergänzt dauerhafte Runs und Transition-Historie.
+- `backend/Controllers/OpenClawRunsController.cs`,
+  `backend/Services/OpenClawRunService.cs`,
+  `backend/Services/OpenClawRunGateway.cs` und
+  `backend/Repositories/OpenClawRunRepository.cs` implementieren:
+  - Liste und Detail;
+  - persist-before-dispatch Start;
+  - exakten Run-Stop ohne Session-weites Abbrechen;
+  - Retry als korrelierten neuen Run;
+  - Nexus-Transitionen plus redigierte Gateway-Historie;
+  - Task-, Projekt-, Session-, Actor-, Correlation- und Trace-Bezug;
+  - Event-Reconciliation einschließlich per-Run-Sequenzlücke.
+- `/runs/:id` zeigt Zustand, Korrelationen, Transitionen, Recovery-Aktionen
+  und Sync-/Gap-Zustand. Resume ist deaktiviert und der Backend-Endpunkt
+  antwortet `unsupported`, da der gepinnte Gateway-Vertrag keinen belegten
+  Same-run-Resume-RPC bietet.
+- Abdeckung:
+  `backend-tests/OpenClawRunServiceTests.cs`,
+  `backend-tests/OpenClawRunGatewayTests.cs` und
+  `frontend/tests/openclaw-runs.test.ts`.
+
+## 6. Globaler Agent-first-Einstieg
+
+**Status:** lokal abgenommen
+
+- `Ctrl/Cmd+K` öffnet
+  `frontend/src/components/mission-control/CommandPalette.vue` auf allen
+  authentifizierten Routen.
+- Die Palette navigiert zu Kernflächen und geladenen Projekten, Tasks, Agents
+  und Sessions. Für Task, Projekt und Agent kann sie einen korrelierten Run
+  vorausfüllen.
+- Iris ist ein globales, standardmäßig geschlossenes Modal. Der gesendete
+  Kontext ist auf Route, Surface, Entity-Typ und Entity-ID begrenzt.
+- `backend/Services/MissionControlContextFormatter.cs` normalisiert diesen
+  Kontext und markiert ihn als nicht vertrauenswürdige Metadaten, bevor die
+  eigentliche Nutzeranweisung folgt.
+- Keyboard-Auswahl, Escape, gegenseitiger Ausschluss der Dialoge und
+  Fokus-Rückgabe sind in der UI implementiert.
+- Abdeckung:
+  `frontend/tests/mission-control.test.ts` und
+  `backend-tests/MissionControlContextFormatterTests.cs`.
+
+## 7. Wahrheitsgetreue Telemetrie
+
+**Status:** lokal abgenommen
+
+- `backend/Services/DashboardService.cs` übernimmt Fortschritt nur aus einem
+  gemeldeten Nexus-Task und Tokens nur aus einer gemeldeten
+  OpenClaw-Session.
+- Cost bleibt `null`, solange die Runtime keinen autoritativen Wert liefert.
+- Dashboard- und Agentenkomponenten zeigen unbekannte Werte als
+  „Nicht gemeldet“ und erzeugen keine synthetischen Thinking-Items,
+  hartcodierten Fortschritte, Kosten, Laufzeiten oder nächsten Schritte.
+- Reale Runtime-Status- oder Activity-Typen dürfen weiterhin „thinking“
+  enthalten; entfernt wurde die präsentativ erfundene Telemetrie, nicht ein
+  autoritatives Ereignis.
+
+## Automatisierte Baseline
+
+Ausgeführt am 2026-07-30 im Repository-Root beziehungsweise in `frontend/`:
+
+| Gate | Ergebnis |
+|---|---|
+| `.tools\dotnet\dotnet.exe test backend-tests/Nexus.Api.Tests.csproj --configuration Release --no-restore` | bestanden: 271, fehlgeschlagen: 0, übersprungen: 0 |
+| `pnpm typecheck` | bestanden |
+| `pnpm test` | 6 Dateien, 11 Tests bestanden |
+| `pnpm build` | bestanden; 1.897 Module transformiert |
+
+## Operierte Browser-QA
+
+Ausgeführt am 2026-07-30 gegen die sichtbar als `QA SIMULATION` markierte
+Repository-Fixture `scripts/qa/openclaw-ui-mock.mjs`:
+
+- alle 19 Seitenrouten bei 1440 px ohne Dokument-Overflow oder sichtbare
+  Alerts; die bereits authentifizierte `/login`-Navigation leitete erwartbar
+  zu `/dashboard`;
+- alle 18 authentifizierten Seiten bei 375 px ohne Dokument-Overflow;
+- Dashboard, Run Control, Run Detail, Task Board, Calendar und Settings
+  zusätzlich bei 768, 1024 und 1920 px ohne Dokument-Overflow;
+- Command Palette per Button und `Ctrl/Cmd+K`, Escape-Schließen,
+  Fokus-Rückgabe und Objekt-Navigation;
+- Iris als standardmäßig geschlossenes Modal mit erhaltenem Run-/Task-Kontext;
+- Task-korrelierter Run-Start, exakter Stop und Retry als neuer korrelierter
+  Run mit unveränderter Quellhistorie;
+- keine Browser-Warnungen oder -Fehler im finalen Konsolencheck.
+
+Die Fixture führte keine reale OpenClaw- oder OpenAI-Aktion aus. Diese
+Browser-QA belegt ausschließlich UI-Verträge, Interaktion, responsive
+Geometrie und den simulierten Lifecycle.
+
+## Verbleibende Grenzen vor Produktionsfreigabe
+
+1. **Live-Gateway:** Remote-Pairing mit realer Request-ID, Device-Token-Reuse,
+   Reconnect und Versionsfehlermodus in der Zielumgebung beweisen.
+2. **End-to-end Provider:** Einen vollständigen
+   `Nexus -> OpenClaw -> OpenAI -> Nexus`-Lauf ausführen und belegen, dass
+   OpenAI in OpenClaw tatsächlich der primäre Provider ist.
+3. **Live-Events:** SSE-Reconnect, Cursor-Replay, Gap-Recovery und
+   Run-Reconciliation unter echtem Gateway-Verkehr und längerer Laufzeit
+   testen.
+4. **Multi-Replica:** Den lokalen JSONL-Idempotency-Ledger vor horizontaler
+   Skalierung durch einen geteilten transaktionalen Ledger mit eindeutigem
+   Key-Claim ersetzen.
+5. **Resume und weitere Control-Flächen:** Same-run-Resume bleibt unsupported.
+   Tool-/Policy-, Channel-, Node-, Connector-, Secret- und vollständige
+   Schedule-Verwaltung sind weiterhin Produkt-Roadmap, nicht Teil dieses
+   Hardening-Slices.
+6. **Datenbank-/Deployment-Nachweis:** Die neue EF-Migration muss in einer
+   PostgreSQL-Zielumgebung angewendet und zurücklesbar geprüft werden. In diesem
+   Checkpoint gab es keinen Commit, Push oder Deployment.
+
+## Kanonische Folgedokumente
+
+- [Agent-First Mission Control](../../../AGENT_FIRST_MISSION_CONTROL.md)
+- [OpenClaw Gateway connection contract](../../../OPENCLAW_GATEWAY_CONNECTION.md)
+- [Mission Control Roadmap](../../../MISSION_CONTROL_ROADMAP.md)
+- [Route and agent-first evaluation](ROUTE_AND_AGENT_FIRST_EVALUATION.md)

docs/audits/2026-07-30/openclaw-agent-first-hardening/ROUTE_AND_AGENT_FIRST_EVALUATION.md

@@ -0,0 +1,290 @@
+# Nexus Route- und Agent-first-Evaluation
+
+**Stand:** 2026-07-30
+**Bewertungsbasis:** aktueller Working Tree, registrierte Routen in
+`frontend/src/router.ts`, Implementierungs- und Testnachweise in
+`ACCEPTANCE_EVIDENCE.md` sowie die ausdrücklich als Simulation markierte
+Browser-QA vom 2026-07-30
+**Ziel:** Nexus als browser-sichere, agent-first Mission Control über OpenClaw,
+mit OpenAI als primärem Provider innerhalb von OpenClaw
+
+## Gesamturteil
+
+Nexus ist inzwischen eine belastbare **Control-Plane-Implementierung**, aber
+noch kein nachgewiesener vollständiger Ersatz für die OpenClaw-Oberfläche im
+Produktionsbetrieb.
+
+- **Architektur- und Implementierungsreife:** etwa **78/100**
+- **Reife als täglicher OpenClaw-Ersatz:** etwa **55/100**
+- **Produktionsnachweis:** etwa **30/100**
+
+Diese Werte sind bewusst getrennt. Gute lokale Tests und eine saubere
+Architektur ersetzen weder ein reales Gateway-Pairing noch einen
+credentialed `Nexus -> OpenClaw -> OpenAI -> Nexus`-Lauf.
+
+Die Anwendung ist bereits agent-first in Einstieg und Grundworkflow:
+`Ctrl/Cmd+K`, globales Iris-Modal, Objektkontext und korrelierte durable Runs
+reduzieren den Weg von einer Mission zu einer Agentenausführung deutlich.
+Sie ist noch nicht vollständig agent-native: Ein Agent kann noch nicht alle
+Runtime-, Tool-, Provider-, Schedule-, Connector- und Recovery-Aufgaben
+innerhalb von Nexus durchführen.
+
+## Bewertungsmaßstab
+
+Die Route-Wertung für Agent-first-Reife verwendet:
+
+- **1/5:** notwendige Basisfläche, aber kein Agentenworkflow;
+- **2/5:** globaler Iris-/Command-Einstieg, überwiegend lesend;
+- **3/5:** agentenrelevanter Kontext oder einzelne echte Aktionen;
+- **4/5:** kontextgebundene Ausführung und operativer Rückkanal;
+- **5/5:** vollständiger, autoritativer Agentenworkflow ohne Ausweichfläche.
+
+„Funktioniert“ bedeutet in diesem Dokument: im Code vorhanden und durch die
+genannte lokale Evidence gestützt. Es bedeutet nicht automatisch, dass die
+Funktion gegen das reale Ziel-Gateway bewiesen wurde.
+
+## Gesamtwertung nach Dimension
+
+| Dimension | Reife | Evidenz | Wichtigste Grenze |
+|---|---:|---|---|
+| Security Boundary | 9/10 | Authentifizierte Fallback-Policy; nur Auth-/Health-Ausnahmen anonym; `X-Agent-Id` ist kein Credential; owner-only OpenClaw-Mutationen; negative Auth-/Rollen-/Header-Tests | MFA/Passkeys, aktive Geräte-/Sessionverwaltung und Zielumgebungs-Härtung fehlen; JSONL-Idempotency-Ledger ist noch Single Writer |
+| Gateway Readiness | 7/10 | Protocol v4; Default-Pin auf bestätigtem Stable-Tag `2026.7.1`; striktes Loopback; persistente Ed25519-Geräteidentität und Device-Token; Pairing Request ID bis zur UI | Kein reales Pairing, Token-Reuse, Versionsfehler- oder Reconnect-Proof gegen das Ziel-Gateway |
+| Effizienz der UI-Kommunikation | 7/10 | Browser spricht nur mit Nexus; authentifiziertes SSE zuerst; `Last-Event-ID`; Gap-/Heartbeat-/Connection-Signale; begrenzter Reconnect; 60-s-Fallback; gefilterte und debouncte Consumer | Events invalidieren häufig noch breite Aggregate; zwei Dashboard-Live-Sync-Module und separate Live-Pipelines erzeugen Drift-/Doppelarbeit-Risiko |
+| Durable Runs | 8/10 | Persist-before-dispatch; Liste, Detail, Historie, exakter Stop, korrelierter Retry, Task-/Projekt-/Session-/Actor-/Trace-Bezug und Gap-Reconciliation | Same-run-Resume ist korrekt `unsupported`; Tool-Trace, Approvals, Artefakte, Usage, Branch/Handoff und Live-E2E fehlen |
+| Agent-first UX | 7/10 | Globale Command Palette; Objekt-Navigation; kontextuelles Iris; vorausgefüllter Run für Task/Projekt/Agent; Run Control als Operatorfläche | Kontext enthält nur Route/Typ/ID; keine serverseitig angereicherte Objektakte, keine natürliche Command-Ausführung mit Plan/Freigabe, wenige proaktive Agentenaktionen |
+| Truthful Telemetry | 9/10 | Kein erfundenes Thinking, keine hartcodierten Fortschritte/Kosten/Laufzeiten; unbekannte Werte bleiben „Nicht gemeldet“; Tokens/Fortschritt nur aus gemeldeten Quellen | Autoritative Kosten, Latenz, Tool-Usage und vollständige Run-Usage werden noch nicht geliefert |
+| Täglicher OpenClaw-Ersatz | 5/10 | Kernübersicht, Chat, Runs, Sessions, Approvals, Modelle, Cron-Run-now, Agents und Recovery-Diagnostik sind erreichbar | Agent-Lifecycle, Tools/Policies, Provider/Auth-Profile, vollständiges Cron CRUD, Nodes/Channels/Connectoren, Secrets, Artefakte und Recovery bleiben unvollständig |
+| Production Proof | 3/10 | Automatisierte lokale Baseline ist grün; aktuelle Browser-QA deckt alle Seitenrouten und den simulierten Run-Lifecycle mit klar markierter Fixture ab | Kein credentialed Zielsystem-E2E, kein reales Pairing, kein Live-Event-Soak, keine Ziel-PostgreSQL-Migrationsabnahme |
+
+## Kommunikationspfad und UI-Optimierung
+
+Der beabsichtigte Vertrauenspfad ist im aktuellen Code sauber:
+
+```text
+Browser
+  -> Nexus Auth / RBAC / Policy
+  -> typisierte Nexus-OpenClaw-Fassade
+  -> OpenClaw Gateway
+  -> OpenAI und Tools
+```
+
+Der Browser erhält weder OpenClaw- noch OpenAI-Credentials. OpenClaw bleibt
+autoritative Runtime für Agents, Sessions, Models, Cron, Approvals und
+Gateway-Events. Nexus besitzt Benutzer, Projekte, Produkt-Tasks und die
+durable Run-/Korrelationsprojektion.
+
+### Was bereits effizient ist
+
+- `GET /api/v1/openclaw/events` ist der primäre Live-Pfad.
+- Der Client sendet den Cursor sowohl als `Last-Event-ID` als auch optionalen
+  Query-Parameter und kann aus dem begrenzten Backend-Buffer wiederaufsetzen.
+- Reconnect verwendet 2, 5, 10 und maximal 30 Sekunden Backoff.
+- Polling ist für OpenClaw-Übersicht, Runs, Chat und Agenten nur der
+  **60-Sekunden-Fallback**, wenn der Eventstream nicht live ist.
+- Run-Consumer reagieren nur auf `openclaw.run`, `openclaw.gap` und
+  `openclaw.connection` und debouncen 350 ms.
+- Chat reagiert nur auf Session-, Run- und Gateway-Ereignisse und debounct
+  400 ms.
+- Agenten debouncen 500 ms; Modelle werden nur bei Gateway-, Connection- oder
+  Sessionereignissen zusätzlich neu geladen.
+- Heartbeats lösen keinen fachlichen Refresh aus.
+
+### Was noch nicht optimal ist
+
+Die Live-Consumer sind **nach Eventtyp gezielt**, die Datenaktualisierung ist
+aber noch nicht vollständig gezielt:
+
+1. `stores/openclaw.ts` lädt nach jedem Nicht-Heartbeat-Ereignis das gesamte
+   `/api/v1/openclaw/overview`-Aggregat neu.
+2. `stores/agents.ts` lädt bei jedem Nicht-Heartbeat-Ereignis erneut die ganze
+   Agentenliste. Bei demselben Gateway-Ereignis können deshalb Overview-,
+   Agenten- und Run-Requests parallel entstehen.
+3. Runs laden nach einem passenden Ereignis die Run-Liste und bei offenem
+   Detail zusätzlich die vollständige Historie.
+4. `stores/liveSync.ts` und `stores/live-sync.ts` sind inhaltlich doppelte
+   Module mit demselben Pinia-Store-Namen. Parallel existieren der allgemeine
+   Dashboard-SSE-Pfad, direkte Dashboard-Live-Abonnements im Agent Detail und
+   der neue OpenClaw-SSE-Pfad.
+5. Nexus-Domainflächen wie Dashboard, Board und Notifications besitzen
+   weiterhin eigene 30-Sekunden-Poller. Das ist fachlich getrennt von
+   OpenClaw, erhöht aber die Gesamtzahl gleichzeitiger Refreshpfade.
+
+**Empfohlene Zielstruktur:** genau ein authentifizierter Live-Orchestrator,
+normalisierte Entity-Stores und eine Event-zu-Invalidierungs-Matrix. Wenn ein
+Event bereits die sichere Projektion enthält, sollte der Store lokal patchen;
+sonst sollte er nur das betroffene Endpoint-Aggregat laden. Ein
+`openclaw.gap` bleibt der korrekte Anlass für einen vollständigen
+autoritativen Refresh.
+
+## Route-für-Route-Evaluation
+
+`/` und `/:pathMatch(.*)*` sind reine Redirects auf `/dashboard` und keine
+eigenständigen Produktflächen. Die folgenden 19 registrierten Seitenrouten
+sind die eigentliche UI.
+
+| Route | Aktueller Nutzen | OpenClaw-Anbindung und Autorität | Agent-first | Wichtigste fehlende Features |
+|---|---|---|---:|---|
+| `/login` | Login, Redirect zur ursprünglich angeforderten Route, Fehlermeldung und Rate-Limit-Countdown | Nexus Auth ist autoritativ; schützt die gesamte OpenClaw-Fassade indirekt | 1/5 | Passkeys/2FA, Recovery, Geräte- und aktive Sessionverwaltung |
+| `/dashboard` | Verdichtete Live-Orchestrierung, Agentenmodal, gemeldete Telemetrie, Task-Leiste; Iris bleibt platzsparend verborgen | Gemischte Projektion: OpenClaw-Agenten/-Sessions plus Nexus-Tasks; Modellwechsel geht über Nexus an OpenClaw | 4/5 | Direkter Run-Start/Stop im Graph, echte Session-/Tool-/Approval-Kanten, normalisierte eventbasierte Patches statt mehrerer Poll-/SSE-Pfade |
+| `/memory` | Memory-Liste, Suche, Reader, Lade-/Leer-/Fehlerzustände | Inhalt ist Nexus-/Workspace-owned; nur globaler OpenClaw-Status und Iris-Kontext | 2/5 | Ingestion, Scope, Provenienz, Freshness, Retention, Retrieval-Evals und agentengesteuerte Kuratierung |
+| `/docs` | Kategorien, Suche, Dokumentliste und Reader | Dokumente sind Nexus-/Workspace-owned; kein autoritativer OpenClaw-Sync | 2/5 | Upload/Import, Versionen, Freigabe, Zitate, Syncstatus und Zuordnung zu Agent/Run |
+| `/agents/:id` | Agentenstatus, Aktivität, Zusammenfassung und Editor für Identitäts-/Policy-Dateien mit Validierung und Backup | Runtime-/Historienanteile kommen über Backend/OpenClaw; Konfigurationsdateien bleiben Nexus-/Workspace-verwaltet; Reload ist explizit nicht unterstützt | 4/5 | Create/import, enable/disable/restart, effektive Toolrechte, Budget/Evals, Driftanzeige und kontrolliertes Gateway-Apply/Reload |
+| `/security` | Nexus-Authstatus, Token-/Cookie-/Passwortzustand sowie effektive Gateway-, Scope- und Approval-Grenze | Nexus Security plus read-only OpenClaw-Trust-/Capability-Projektion | 2/5 | Remediation-Aktionen, effektive Policy-Matrix, Scope-Diffs, Geräte-/Sessionverwaltung, MFA/Passkeys und Security-Audit-Timeline |
+| `/incidents` | Incident-Dateien lesen; aktuelle fehlgeschlagene Runtime-Tasks erkennen; Recovery-Link zu Run Control | Incident-Akte ist Nexus-owned, Runtime-Failure-Slice kommt aus OpenClaw | 2/5 | Create/ack/assign/escalate/resolve, automatische Eventkorrelation, Runbook-Ausführung, Postmortem und dauerhafte Run-/Trace-Links |
+| `/calendar` | OpenClaw-Jobs, nächste/letzte Ausführung und owner-bestätigtes „Run now“ | `cron.list` und `cron.run`; OpenClaw ist autoritativ | 3/5 | Create/edit, enable/pause/delete, Zeitzone, vollständige Historie, Retry, Ergebnis-/Run-Korrelation |
+| `/projects` | Nexus-Projektportfolio und Projektanlage; Detailnavigation | Nexus ist autoritativ; dynamische Command-Suche kann geladene Projekte öffnen | 2/5 | Runtime-Rollup pro Projekt, Agents/Runs/Approvals/Budget/Artefakte und direkte Delegation |
+| `/projects/:id` | Projekt bearbeiten/archivieren und zugehörige Tasks sehen | Nexus-Projekt bleibt autoritativ; Command Palette kann einen `projectId`-korrelierten Run vorbereiten | 3/5 | Eingebettete Run-Liste, Automationspolicy, Budget, Artefakte, Statusrückfluss und „Iris übernimmt“-Workflow |
+| `/tasks` | Vollständiges Kanban, CRUD, Statuswechsel, Child-/Waiting-/Stale-Sicht und OpenClaw-Runtime-Strip | Task ist Nexus-owned; Live-Dashboard-Sync und OpenClaw-Übersicht laufen parallel; Übergabe zu Run Control vorhanden | 3/5 | Sichtbare persistente Task↔Run/Session-Korrelation auf Karten, Inline-Start/Stop/Retry/Approval und einheitlicher Live-Store |
+| `/tasks/:id` | Task bearbeiten, Status, Child-Tasks, Kommentare und Aktivität | Nexus ist autoritativ; Command Palette bereitet einen `taskId`-korrelierten durable Run vor | 4/5 | Verknüpfte Runs/Sessions direkt anzeigen, Tool-/Approval-/Artefakt-Timeline, Run-Ergebnis zurückschreiben und Replay |
+| `/agents` | OpenClaw-nahe Agenteninventur mit Status, Modell, Aufgabe und nur gemeldeter Progressanzeige | Runtimezustand über Nexus-Fassade/OpenClaw; statische Fallbacks liefern nur beschreibende Metadaten, keine erfundene Telemetrie | 3/5 | Lifecycle, Import/Create, Capability-/Toolpolicy, Budget, Health-Historie, Drift und Bulk-Aktionen |
+| `/runs` | Stärkste Operatorfläche: durable Run starten, Work Graph, Tasks, Sessions, Approvals, Cron, Events, Capabilities, Cancel/Abort/Resolve/Run-now | OpenClaw ist Runtime-Autorität; Nexus ist durable Ledger-, Policy- und Korrelationsschicht | 4/5 | Same-run-Resume oder belegte Alternative, Branch/Handoff, Tooltrace, Artefakte, Usage/Cost, bessere Run-Filter und Ende-zu-Ende-Ergebnisfluss |
+| `/runs/:id` | Durable Run, exakter Zustand, Stop/Retry, Transitionen, redigierte Gateway-Historie, Korrelationen, Gap-Warnung und Reconcile | Nexus-Run-Ledger plus OpenClaw-Ausführung/-Historie; Resume wird ehrlich als unsupported gezeigt | 4/5 | Same-run-Resume, Tool-/Approval-/Artefakt-Timeline, Token/Kosten/Latenz, Child-Runs, Branch/Handoff und positives Live-Gateway-Proof |
+| `/models` | Live-Katalog, Providerfilter, Verfügbarkeit, Kontextgröße und aktuelle Sessionnutzung | `models.list`; OpenClaw ist autoritativ, Browser sieht keine Secrets | 2/5 | OpenAI-Auth-Profilstatus, Primary/Alias/Fallback-Policy, Limits/Budgets, Testlauf und kontrollierte Default-Änderung |
+| `/activity` | Gemeinsame Suche/Filterung für OpenClaw- und Nexus-Ereignisse mit Detailansicht | Gemischte, klar markierte Quellen; OpenClaw-Runtime-Events bleiben von Nexus-Events unterscheidbar | 3/5 | Durchgängige Correlation-/Trace-Links, Actor/Diff, Pagination, Export, Retention, Run-Deep-Link und direkte Recovery |
+| `/notifications` | Nexus-Benachrichtigungen, Mark-read/Mark-all und Zusammenfassung offener OpenClaw-Approvals | Nexus besitzt Notifications; OpenClaw besitzt Approvalstatus | 2/5 | Inline allow/deny, exakte Objekt-Deep-Links, Snooze, Quiet Hours, Routingpräferenzen, Eskalation und Incident-Aktionen |
+| `/settings` | Profil, Passwort, User-Administration und Gatewaydiagnostik mit Version, Device ID, Scopes und Pairing Request ID | Nexus-Konfiguration plus read-only OpenClaw-Verbindungs-/Pairingzustand; Secrets bleiben außerhalb des Browsers | 2/5 | Pairing-Abschlussworkflow, validierte Provider-/Auth-Profil-/Policy-Formulare, Config-Diff, Backup, kontrollierter Reload/Rollback und Connectorverwaltung |
+
+## Ist Nexus sinnvoll für OpenClaw und „agent first“ optimiert?
+
+**Ja, architektonisch und im Kernworkflow. Noch nicht vollständig operativ.**
+
+Positiv:
+
+1. Das Frontend kennt keine OpenClaw-Transportdetails und keine
+   Provider-Secrets.
+2. OpenClaw-Aktionen laufen durch Auth, Rolle, Capability-Prüfung,
+   Idempotency, Correlation, Trace und Audit.
+3. Die Command Palette macht Agents, Sessions, Tasks und Projekte zu
+   adressierbaren Arbeitsobjekten.
+4. Iris erhält auf jeder authentifizierten Route einen begrenzten,
+   serverseitig als nicht vertrauenswürdig markierten Kontext.
+5. Runs sind nicht mehr nur flüchtige Chataktionen, sondern durable,
+   korrelierte Objekte mit eigener URL und Historie.
+6. Unbekannte Runtimewerte werden nicht länger durch optisch überzeugende
+   Fantasiewerte ersetzt.
+
+Noch nicht ausreichend:
+
+1. Der Iris-Kontext enthält nur Surface, Route, Entity-Typ und ID. Für eine
+   wirklich agent-first Bedienung sollte das Backend nach Autorisierung eine
+   kompakte Objektakte mit Zustand, erlaubten Aktionen, Freshness und
+   Korrelationen ergänzen.
+2. Die Command Palette startet Navigation oder öffnet Formulare, führt aber
+   noch keinen strukturierten natürlichen Befehl mit Planvorschau,
+   Risikoklasse, Approval und Ergebnisrückgabe aus.
+3. Agenten können über Nexus noch nicht ihren vollständigen Lifecycle, ihre
+   effektiven Tools, Provider-Policies, Schedules, Connectoren und Secrets
+   kontrollieren.
+4. Ein Run endet in der UI noch nicht als vollständiges Arbeitsprodukt aus
+   Tooltrace, Freigaben, Artefakten, Usage, Bewertung und Rückschreiben in
+   Task/Projekt.
+5. Ohne echte Evals ist nicht belegt, dass Iris das richtige Tool mit den
+   richtigen Argumenten wählt und eine fachlich korrekte Mission abschließt.
+
+## Evidence: Simulation, lokale Abnahme und Live-Nachweis
+
+### Lokal automatisiert abgenommen
+
+Die aktuelle Acceptance Evidence dokumentiert:
+
+| Gate | Ergebnis |
+|---|---|
+| Backend-Tests | 271 bestanden, 0 fehlgeschlagen, 0 übersprungen |
+| `pnpm typecheck` | bestanden |
+| `pnpm test` | 6 Dateien, 11 Tests bestanden |
+| `pnpm build` | bestanden, 1.897 Module transformiert |
+
+Damit sind Security-Invarianten, Gateway-Protokoll, Pairingpersistenz,
+Mutationsmetadaten, Eventprojektion, durable Run-Domain, Context-Sanitizing und
+Frontend-Stores lokal abgesichert.
+
+### QA-Simulation
+
+Die operierte Browser-QA vom 2026-07-30 nutzte
+`scripts/qa/openclaw-ui-mock.mjs`. Die Antworten waren mit
+`X-Nexus-QA-Fixture` markiert und die UI zeigte `QA SIMULATION`.
+
+Die aktuelle Evidence belegt:
+
+- alle 19 Seitenrouten bei 1440 px ohne Dokument-Overflow oder sichtbare
+  Alerts; `/login` leitete die bestehende authentifizierte Session erwartbar
+  zu `/dashboard` weiter;
+- alle 18 authentifizierten Seiten bei 375 px ohne Dokument-Overflow sowie
+  Dashboard, Run Control, Run Detail, Task Board, Calendar und Settings
+  zusätzlich bei 768, 1024 und 1920 px;
+- Command Palette per Button und `Ctrl/Cmd+K`, Escape-Schließen und
+  Fokus-Rückgabe;
+- globales und seitenbezogenes Iris-Modal mit erhaltenem Route-/Objektkontext;
+- Task-korreliertes Vorausfüllen eines neuen Runs;
+- simulierten exakten Stop sowie Retry als neuen korrelierten Run mit
+  unveränderter Quellhistorie;
+- eine leere Browserkonsole für Warnungen und Fehler im finalen Lauf.
+
+Diese Evidence belegt **nicht**:
+
+- ein reales OpenClaw Gateway;
+- ein echtes Device Pairing;
+- einen OpenAI-Providerlauf;
+- reale Gateway-SSE-Replay-/Gap-Bedingungen;
+- die positive `/runs/:id`-Route gegen einen echten Run.
+
+### Noch nicht live bewiesen
+
+- Remote-/Container-Pairing mit realer Request ID und wiederverwendetem
+  Device-Token;
+- Version-Pin und kontrollierter Fehlermodus gegen den installierten Gateway;
+- vollständiger `Nexus -> OpenClaw -> OpenAI -> Nexus`-Lauf;
+- Start, Live-Events, Approval/Tool, Ergebnis, Stop/Retry und Reconnect im
+  selben realen Szenario;
+- Anwendung und Rücklesetest der neuen EF-Migration in Ziel-PostgreSQL;
+- Multi-Replica-Idempotency und längerer Event-Soak.
+
+## Priorisierte Schritte bis zu einem belastbaren täglichen Ersatz
+
+### P0 — Produktionswahrheit
+
+1. Reales Device Pairing und Gateway-Reconnect in der Zieltopologie beweisen.
+2. Einen OpenAI-over-OpenClaw-Run mit Provider-/Modellnachweis, negativem
+   Authfall, Audit und Event-Replay vollständig aufzeichnen.
+3. Ziel-PostgreSQL migrieren und Run-Ledger/History nach Neustart rücklesen.
+
+### P1 — Eine vollständige Agentenmission
+
+1. Run um Tooltrace, Approval-Timeline, Artefakte, Usage und Ergebnis erweitern.
+2. Task/Projekt zeigen ihre korrelierten Runs und übernehmen autoritative
+   Ergebnisse.
+3. Branch/Handoff und eine belegte Resume-Strategie ergänzen.
+4. Iris-Befehle als strukturierte, bestätigbare Pläne mit Policy-Vorschau
+   ausführen.
+
+### P1 — OpenClaw nicht mehr öffnen müssen
+
+1. Agent-Lifecycle und effektive Tool-/Approval-Policies.
+2. OpenAI-Auth-Profile, Modellrouting, Fallbacks, Budgets und Limits.
+3. Vollständiges Cron CRUD und Run-Historie.
+4. Nodes, Channels, Connectoren, Pairing und kontrollierte
+   Config-Reload-/Rollback-Flächen.
+5. Incident- und Notification-Lifecycle mit operativen Aktionen.
+
+### P2 — Skalierung und Qualität
+
+1. Die doppelten Live-Sync-Module und parallelen Streams in einen
+   Live-Orchestrator konsolidieren.
+2. Eventpayloads normalisiert patchen und Aggregate nur bei Gap oder echter
+   Invalidierung nachladen.
+3. Den lokalen JSONL-Ledger vor horizontaler Skalierung durch einen geteilten
+   transaktionalen Idempotency-Store ersetzen.
+4. Agenten-Evals für Toolauswahl, Argumentgenauigkeit, Policy-Verhalten und
+   fachliches Ergebnis als Release-Gate einführen.
+
+## Schlussfolgerung
+
+Nexus ist jetzt sinnvoll auf OpenClaw ausgerichtet und deutlich agent-first:
+Die Vertrauensgrenze stimmt, Live-Kommunikation ist SSE-first, Ausführungen
+werden durable, und der globale Einstieg ist objektbezogen. Die Behauptung
+„Nexus ersetzt OpenClaw im Alltag“ wäre trotzdem noch verfrüht.
+
+Die nächste Qualitätsstufe entsteht nicht durch weitere read-only Seiten,
+sondern durch einen real belegten, vollständigen Missionsloop und durch das
+Schließen der verbleibenden Control-Flächen. Bis dahin sollte OpenClaw als
+Break-glass-/Recovery-Oberfläche verfügbar bleiben.

docs/audits/2026-07-30/openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md

@@ -0,0 +1,265 @@
+# Nexus OpenClaw Attach & Adopt — implementation and acceptance
+
+**Date:** 2026-07-30
+**Scope:** local Nexus working tree; no commit, push, deployment or VPS write
+**Status:** implemented locally; final automated/browser suite pending entry;
+production release blocked
+
+## Outcome
+
+Nexus now has a coherent, agent-first path for connecting one OpenClaw
+instance, adopting its live inventory without copying Runtime data, and
+deliberately elevating from read-only to management. The same typed boundary
+now supplies agent files, read-only workspace content, schema-driven
+configuration, cron lifecycle and sanitized model authentication status.
+
+This is not a production-readiness claim. The pinned OpenClaw `2026.7.1`
+client registry does not yet support the external Nexus-/Generic-Operator
+identity required by this integration. Real pairing, scope upgrade, live test
+mutations and a complete OpenAI execution remain mandatory blockers.
+
+## Authority contract
+
+| State | Authority |
+|---|---|
+| Users, roles, projects, product tasks, approvals and Nexus audit | Nexus |
+| Agents, bootstrap/workspace files, OpenClaw config, cron, models, sessions, channels and nodes | OpenClaw |
+| Model execution and provider secrets | OpenAI through OpenClaw |
+| Connection/adoption metadata and local management consent | Nexus `primary` profile |
+
+Adoption stores no agent-file content, cron definition, provider credential,
+model configuration, channel or node. OpenClaw remains the source of truth and
+Nexus refreshes these resources through advertised RPCs.
+
+## Implemented setup contract
+
+### Single persisted profile
+
+The EF-backed `primary` profile stores the normalized endpoint,
+discovery source, required version, optional TLS pin, adoption state,
+management consent, capability hash, timestamps and an optimistic concurrency
+version. Adoption returns a live inventory snapshot but does not persist its
+resource contents.
+
+Device private key and device token remain in the server-side device store.
+Tokens are bound to endpoint, TLS fingerprint, role and scopes. OpenAI keys,
+Gateway passwords, bootstrap token plaintext and provider secrets are not
+stored in the profile or returned to the browser.
+
+### Owner-only API
+
+| Method | Route | Result |
+|---|---|---|
+| `GET` | `/api/v1/openclaw/setup` | Current setup, trust, pairing, adoption and management state |
+| `POST` | `/api/v1/openclaw/setup/discover` | Only known candidates; optional explicit mDNS |
+| `POST` | `/api/v1/openclaw/setup/probe` | Transport, TLS, version, identity and capability proof |
+| `POST` | `/api/v1/openclaw/setup/attach` | Transient bootstrap credential and `operator.read` attachment |
+| `POST` | `/api/v1/openclaw/setup/verify` | Re-check pairing, endpoint, device, scopes and capabilities |
+| `POST` | `/api/v1/openclaw/setup/adopt` | Return live inventory and persist adoption/capability metadata without copying resources |
+| `POST` | `/api/v1/openclaw/setup/management` | Deliberate scope-upgrade request and local management gate |
+| `DELETE` | `/api/v1/openclaw/setup/connection` | Confirmed detach of profile, socket and bound token |
+
+All routes require the owner role. Mutation routes are rate-limited and use
+profile concurrency checks where applicable. Wizard Gateway mutations
+additionally require an Idempotency Key and correlation context; resource
+mutation audit is described in the sections below.
+
+### Discovery, transport and secrets
+
+- Discovery is limited to a configured endpoint,
+  `openclaw-gateway:18789`, loopback, `host.docker.internal`, and expressly
+  requested mDNS. The current build reports mDNS as unsupported and performs no
+  network scan. There is no subnet scan and no Docker-socket access.
+- External endpoints require `wss://` and a confirmed certificate
+  fingerprint. Clear `ws://` is limited to loopback or an explicitly allowed
+  internal Docker topology.
+- A bootstrap token can be submitted through a masked owner field or a
+  server-side SecretRef. It remains in memory only until the Device Token is
+  issued.
+- Initial adoption rejects an already admin-scoped connection. Management
+  begins as a separate scope upgrade and requires renewed pairing approval.
+- Detach clears the persisted profile, local management gate and matching
+  Device Token, and closes the connector. A separately configured server
+  bootstrap secret must still be revoked at its own source.
+
+### External client identity gate
+
+Nexus uses `nexus` as its intended external identity and does not imitate
+OpenClaw's reserved `gateway-client/backend`, CLI or Control UI identities.
+`OPENCLAW_EXTERNAL_CLIENT_ID_SUPPORTED` therefore defaults to `false`.
+Discovery and UI can explain the blocker, but productive Attach/Adopt remains
+blocked until a pinned OpenClaw version officially registers the external
+identity and passes the contract suite.
+
+## Implemented agent-first resource management
+
+### Agents and files
+
+- Agent inventory comes from `agents.list`; newly created OpenClaw agents no
+  longer require a Nexus Compose edit or static sanitized inventory.
+- File tabs are generated from `agents.files.list`.
+- `agents.files.get/set` supplies and mutates the supported bootstrap files:
+  `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`,
+  `HEARTBEAT.md`, `BOOTSTRAP.md` and optional `MEMORY.md`.
+- Every write carries `content`, `expectedHash` and `Idempotency-Key`. Nexus
+  re-reads before the mutation, rejects drift with `409`, writes through
+  OpenClaw and verifies the new content through a second read.
+- The success copy is limited to “saved and read back”; no unconfirmed hot
+  reload is claimed.
+- Extra files such as `DREAMS.md` or `memory/YYYY-MM-DD.md` are browsable
+  through `agents.workspace.list/get` and remain read-only because the pinned
+  OpenClaw contract has no safe arbitrary workspace-write RPC.
+- The old `/api/v1/agents/{id}/config*` endpoints remain temporarily as
+  owner-only compatibility adapters to the live RPC implementation.
+
+Standing Orders are maintained in a controlled `AGENTS.md` section covering
+goals, triggers, permitted actions, approval boundaries, escalation and
+verify/report rules.
+
+### OpenClaw configuration
+
+Settings uses `config.schema.lookup`, `config.get` and `config.patch` rather
+than raw host-file writes. Edits include `baseHash`, diff preview and explicit
+`replacePaths`. A stale snapshot is rejected, a successful patch is read back,
+and secret values are never projected to the browser.
+
+### Cron lifecycle
+
+OpenClaw remains the only cron data source. Nexus adds typed contracts for:
+
+- paginated list and detail;
+- paginated run history;
+- create and hash-guarded patch;
+- enable/disable through patch;
+- delete; and
+- immediate run with returned `runId` correlation.
+
+A force run is displayed as queued. Only authoritative `cron.runs` data
+determines success or failure. Mutations require owner, advertised RPC,
+persisted `ManagementEnabled`, `operator.admin`, rate limit, audit and
+Idempotency Key. Patch, delete and force run also require the current job hash;
+create has no pre-existing resource hash.
+
+Command payloads and `on-exit` schedules remain blocked by default through
+`AllowCommandCron=false`. Delivery destinations are masked in collections,
+logs and audit; full values belong only in the owner detail/edit context.
+The unsafe legacy Dashboard-to-Gateway delete path no longer performs cron
+deletion.
+
+### Models auth status
+
+`GET /api/v1/openclaw/models/auth-status` projects `models.authStatus` into a
+browser-safe provider summary. It does not expose auth-profile IDs, e-mail
+addresses, credentials, billing/usage windows or secret-bearing provider
+payloads. OpenClaw `2026.7.1` does not provide all desired provenance fields;
+Nexus leaves unavailable provenance empty rather than inventing it.
+
+### Official OpenClaw wizard
+
+Nexus renders the official `wizard.start`, `wizard.next`, `wizard.status` and
+`wizard.cancel` protocol through owner-only setup routes. It supports notes,
+selection, text, confirmation, multi-selection, progress, actions, device
+codes and external links.
+
+The backend requires an active connection, advertised method,
+`operator.admin` and local management consent. It starts only the setup flow
+with daemon installation disabled, redacts sensitive steps and rejects secret
+answers from browser fields. Nexus does not install OpenClaw, perform SSH
+bootstrap, or automatically run migrations or `doctor --fix`.
+
+## Legacy filesystem boundary
+
+The Attach & Adopt resource path does not derive workspaces as
+`/mnt/workspace-{agentId}` and does not use `agents-sanitized.json` as agent
+authority. The same implementation checkpoint removed those production
+dependencies after RPC parity. Final repository review found no remaining
+`AgentConfigPath`, `agents-sanitized` or fixed per-agent workspace derivation
+in production backend code or backend tests.
+
+The separate Nexus Memory/Docs/Incidents compatibility surfaces may retain one
+explicitly configured, confined Iris content root until their own OpenClaw RPC
+migration. That bounded content reader must not be used to infer live agents or
+map an agent ID to a host path.
+
+## UI contract
+
+- Settings is the owner-only Setup Center:
+  Discover → Probe → Pair read-only → Inventory → Adopt → optional Management.
+- Agents uses live file tabs, dirty-state protection, hash-conflict recovery,
+  read-only workspace browsing and Standing Orders.
+- Calendar provides list/detail, create/edit, enable/disable, delete, queued
+  run and paginated history.
+- Security exposes device, endpoint trust, scopes and capability boundaries.
+- Models shows only catalog data and sanitized `models.authStatus`.
+- Loading, empty, blocked, incompatible, conflict and failure states remain
+  explicit. A failed RPC is never converted into a plausible empty list.
+
+The responsive and accessibility proof targets are defined in
+[Structural Proof Preflight](STRUCTURAL_PROOF_PREFLIGHT.md).
+
+## Final local verification
+
+The following checks were rerun against the combined working tree on
+2026-07-30 after the RPC cutover, Legacy-FS cleanup, QA-fixture expansion and
+the final Settings layout correction.
+
+| Check | Required command/evidence | Final result |
+|---|---|---|
+| Backend | `.tools\dotnet\dotnet.exe test backend-tests/Nexus.Api.Tests.csproj --configuration Release` using the bundled .NET 10 SDK | **Passed: 312/312, 0 skipped** |
+| Frontend typecheck | `pnpm typecheck` in `frontend/` | **Passed** |
+| Frontend unit tests | `pnpm test` in `frontend/` | **Passed: 6/6 files, 12/12 tests** |
+| Frontend production build | `pnpm build` in `frontend/` | **Passed: 1,914 modules**; existing 500 kB chunk advisory remains |
+| Working-tree hygiene | `git diff --check` | **Passed**; Windows line-ending notices only |
+| Browser functional QA | Settings setup/discovery and `wizard.*`, config patch/read-back, agent file write/read-back, read-only workspace, Calendar create/detail/history/run correlation, Models auth detail and Iris modal through the controlled mock | **Passed** |
+| Responsive/overflow QA | All 18 authenticated core routes at 375 and 1440 CSS px; Dashboard, Settings, Agent Detail, Calendar and Run Control additionally at 768, 1024 and 1920 CSS px | **Passed: zero document overflow** |
+| Console/accessibility QA | Named controls and dialogs, focus transfer, status announcements, modal close and browser console | **Passed: no console warnings or errors** |
+
+The controlled mock is explicitly synthetic evidence. It verifies Nexus UI
+contracts and interaction semantics without representing a successful live
+OpenClaw connection or authorizing any VPS mutation.
+
+## Production blockers and separate live acceptance
+
+Production readiness remains **blocked** until all of the following are
+demonstrated:
+
+1. The pinned OpenClaw release officially supports the external Nexus or
+   generic operator Client ID.
+2. Bao's explicitly scoped OpenClaw accepts the real read-only Pairing and the
+   later management Scope Upgrade.
+3. The previously observed inventory expectation of 9 agents and 7 cron jobs
+   is reverified read-only without inspecting or enumerating resources outside
+   Bao's scope.
+4. Hash-conflict and verified write/read-back tests succeed on explicitly
+   named disposable agent-file, config and cron test objects.
+5. A real `Nexus -> OpenClaw -> OpenAI -> Nexus` run proves OpenAI as primary
+   provider without exposing prompt, token, delivery target or credential
+   data.
+6. Reconnect, missing method, version drift, denied scope, `{ok:false}`,
+   timeout, stale write, idempotent replay and uncertain-outcome recovery pass
+   in the target topology.
+
+No live mutation, pairing approval, OpenClaw patch, deployment or access to
+out-of-scope resources was authorized or performed by this implementation
+checkpoint.
+
+## Remaining product work
+
+- Official external client identity and real topology acceptance.
+- Agent create/enable/disable/restart/delete and template workflows.
+- Tool catalog, effective rights, policies, channels and nodes.
+- Safe arbitrary workspace mutation if OpenClaw adds a suitable RPC.
+- Full provider/model policy editing, budgets, evals and authoritative usage.
+- Cron templates plus retry, missed-run and alerting policies.
+- Transactional shared idempotency/audit storage before multiple API writers.
+- Full OpenAI E2E, recovery, security and release gates.
+
+## Primary references
+
+- [Stable OpenClaw `2026.7.1` client registry](https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts)
+- [Gateway protocol](https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/gateway/protocol.md)
+- [Operator scopes](https://docs.openclaw.ai/gateway/operator-scopes)
+- [Gateway configuration](https://docs.openclaw.ai/gateway/configuration)
+- [Agent workspace](https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/concepts/agent-workspace.md)
+- [OpenClaw wizard](https://docs.openclaw.ai/reference/wizard)
+- [Cron operations](https://docs.openclaw.ai/cli/cron)

docs/audits/2026-07-30/openclaw-attach-adopt/STRUCTURAL_PROOF_PREFLIGHT.md

@@ -0,0 +1,100 @@
+# OpenClaw Attach & Adopt — structural proof preflight
+
+## Product surface and direction
+
+- Surface: operational product UI.
+- Visual authority: the existing authenticated Nexus dashboard and
+  `docs/NEXUS_DESIGN_SYSTEM.md`.
+- Concept sentence: Nexus exposes one calm, evidence-bound operator path from
+  discovering an OpenClaw Gateway to inspecting it read-only and deliberately
+  enabling management.
+- Entry mode: `task-first`.
+- Product-surface restraint: setup, conflict, failure, and destructive states
+  use plain glass surfaces and semantic status color; the blue-violet gradient
+  remains reserved for the active step and primary action.
+- Imagery: not applicable. Diagrams, photographs, or generated media would not
+  improve this trust-sensitive operational task.
+
+## Bounded first journeys
+
+### Gateway setup
+
+1. Entry: owner opens Settings and sees the current setup state.
+2. Primary action: discover bounded candidates or enter an explicit endpoint.
+3. Proof: probe shows endpoint, transport trust, version, protocol, and
+   capability status without changing OpenClaw.
+4. Commit: attach requests read-only pairing; adopt stores only the connection
+   profile and inventory fingerprint.
+5. Recovery: failed probe, pairing-required, incompatible client identity,
+   version mismatch, and disconnect each keep a local recovery action.
+6. Privilege change: management scope elevation is a separate owner action.
+
+### Agent configuration
+
+1. Entry: select a live file returned by OpenClaw.
+2. Primary action: edit an allowed bootstrap file.
+3. Proof: visible saved hash and current file metadata.
+4. Conflict: a stale expected hash blocks the write and offers reload.
+5. Success: Nexus reports only verified read-back, not unproven hot reload.
+6. Custom workspace documents remain visibly read-only.
+
+### Cron management
+
+1. Entry: inspect a real OpenClaw job and its current resource hash.
+2. Primary action: create, edit, enable/disable, run, or delete.
+3. Proof: mutations show queued/committed state and refreshed Gateway data.
+4. Recovery: hash conflict reloads the current job; failed or uncertain
+   operations never claim success.
+5. High-risk command/on-exit payloads stay unavailable unless local policy is
+   explicitly enabled.
+
+## Section grammar
+
+| Surface section | Role | Narrow transformation | State responsibility |
+| --- | --- | --- | --- |
+| Setup progress | Orient | Horizontal steps become a concise ordered list | Current step, completed steps, blocked reason |
+| Candidate/probe panel | Act | Controls stack in semantic order | Idle, loading, empty, invalid, probe failure |
+| Trust evidence | Prove | Definition list remains in source order | Endpoint, TLS pin, version, protocol, scopes |
+| Inventory | Prove | Counts become a two-column grid | Fresh, stale, partial, unavailable |
+| Management gate | Act | Confirmation follows consequences | Read-only, pairing, enabled, forbidden |
+| Agent file navigation | Orient/Act | Wrapping tabs with current-file context | Loading, missing, readonly, dirty |
+| Agent editor | Act/Recover | Header actions stack above editor | Saving, verified, conflict, error |
+| Cron job list/detail | Compare/Act | List precedes selected detail | Loading, empty, disabled, stale, error |
+| Mutation dialogs | Act/Recover | One-column consequence-first layout | Pending, failed, committed, focus return |
+
+## State and copy truth table
+
+| State | Visible fact | Allowed action | Forbidden claim | Recovery/focus |
+| --- | --- | --- | --- | --- |
+| Unconfigured | No active OpenClaw profile | Discover, enter endpoint | Connected/imported | Candidate action |
+| Probing | Endpoint is being inspected read-only | Cancel/await | Paired/adopted | Probe status |
+| Client identity blocked | OpenClaw lacks an approved Nexus identity | Review requirement | Gateway failure or bad secret | Compatibility explanation |
+| Pairing required | Exact current request ID | Verify after external approval | Approved/connected | Verify button |
+| Inspectable | Read-only inventory is current | Adopt | Management enabled | Adopt button |
+| Adopted read-only | OpenClaw is authoritative; writes blocked | Request management | Editable | Management action |
+| Scope upgrade pending | Wider scopes require approval | Verify | Admin granted | Pairing request |
+| Management enabled | Local gate and Gateway scopes both allow mutation | Supported mutations | Universal admin capability | Relevant first action |
+| Stale agent file | Current Gateway hash differs | Reload | Saved/overwritten | Reload file |
+| Cron run queued | OpenClaw returned a run ID | Open Run Control | Executed successfully | Run detail |
+| Mutation uncertain | Terminal outcome is not known | Refresh/investigate | Retried or successful | Recovery action |
+
+## Responsive and accessibility proof targets
+
+- Required widths: 375, 768, 1024, 1440, and 1920 CSS pixels.
+- First actions and dialog actions remain fully visible with the authenticated
+  62px topbar and overlay sidebar contract.
+- All dialogs use semantic controls, initial focus, Escape, focus containment,
+  and focus restoration.
+- Status changes use `role=status` or `aria-live`; failures use `role=alert`.
+- No trust-bearing endpoint, fingerprint, job ID, run ID, or hash is truncated
+  without a full accessible value.
+- Long Gateway errors, IDs, German labels, and delivery destinations wrap
+  without document-level horizontal overflow.
+
+## Proof boundary
+
+Automated tests and a controlled mock can establish contract and UI behavior.
+Only a separately authorized read-only live check against Bao's Gateway can
+establish inventory parity. Live mutation, pairing approval, OpenClaw patching,
+deployment, and any access to Maxi-owned resources are outside this
+implementation checkpoint.