feat: ship agent-first mission control v0.2.57

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.