@wacando/agent 0.0.0-stage → 2.0.0-rc.1

package/docs/ONBOARDING-VALIDATION.md

@@ -0,0 +1,88 @@
+# Onboarding v1 validation — September 23, 2026
+
+The [OMEMO integration record](OMEMO_PREKEY_INTEGRATION.md) contains the latest
+checks after incorporating the upstream prekey fixes. The historical
+[handoff review follow-up](PLUGIN_HANDOFF_FOLLOWUP.md) records the connection
+lifetime correction and original crypto failures. The results below are the
+earlier onboarding baseline, not a public-release qualification.
+
+Environment: Linux, Node.js 22.22.0, npm 10.9.4, Codex CLI 0.153.4.
+Service under test: `http://localhost:3005`, with the actual local API and
+ejabberd WebSocket service. Only labelled synthetic accounts were created.
+No production availability is asserted. Existing uncommitted repository changes
+were preserved; no backend source/configuration changes, publication or push
+were performed.
+
+| Command | Result |
+| --- | --- |
+| `npm run check` | 40 passed; 3 opt-in live tests skipped; generated runtimes match shared sources |
+| `npm run check:mcp` | Official Inspector 2.7.0 passed for all three packaged adapters |
+| `WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 node --test tests/onboarding-live.test.mjs` | 3 passed against real API/XMPP/OMEMO |
+| `WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 node scripts/check-host-onboarding.mjs` | Actual Codex host invoked installed verification and enrollment tools; another fresh host resumed enrollment without redemption |
+| `python3 /home/kyle/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/wacando` | Passed |
+| `git diff --check` | Passed |
+| Local `npm pack` followed by `npm exec --yes --package=<local-tarball> -- wacando-plugin --version` | Returned `1.0.0`; 142 packaged files, approximately 1.09 MB compressed; nothing published |
+
+The packaging test runs `npm pack`, inspects the resulting tarball, extracts it
+outside the checkout, invokes its version command, and installs all three host
+packages into isolated destinations. Reinstallation refuses to overwrite a marker
+representing existing user content. Hidden plugin/MCP/marketplace files are included.
+
+Live tests check owner-visible `verifiedAt` and `connectedAt` after actual plugin
+tool calls. They also cover challenge replay through a fresh plugin state,
+wrong installation, invalidation of a replaced token, restart preserving the
+private OMEMO identity, and revocation preventing later connection attempts.
+The plugin's stdout/MCP results and stderr are checked for durable credential
+markers. Owner cookies are confined to the test controller.
+
+Unit tests cover challenge/token expiration responses, network response loss,
+failure to persist the durable enrollment response, rejected redirects,
+origin/host/identity isolation, unsafe permissions and symlinks, locking,
+failed OMEMO publication suppressing the callback, and corrupt local keys.
+They simulate expiry errors; the live test does not wait 10/15 minutes or alter
+database timestamps to force real wall-clock expiry.
+
+## Precisely what was tested in hosts
+
+- **Codex CLI 0.153.4:** real model-driven MCP calls against a copied installed
+  plugin runtime registered in that invocation's MCP configuration. Verification,
+  enrollment and resume each ran in a fresh ephemeral Codex session. Normal
+  automatic approval review (`--approve-for-me`) remained active. This validates
+  actual host tool invocation; it does not qualify Codex Desktop marketplace UI,
+  native-browser rendering, or visual observation of the onboarding page.
+- **Cursor:** its self-contained runtime, Inspector interoperability and the
+  complete local API/XMPP/OMEMO path passed. Cursor's actual GUI tool invocation,
+  reload and plugin UI remain to be qualified.
+- **Claude Code:** its self-contained runtime, Inspector interoperability and
+  complete local API/XMPP/OMEMO path passed. The actual Claude Code CLI/Desktop
+  host and its plugin validator were unavailable here and remain to be qualified.
+
+The first ordinary `codex exec` probe refused the MCP mutation because
+noninteractive execution had an effective `never` approval policy. Switching to
+the supported automatic approval review mode allowed all three host calls.
+No bypass flag or disabled sandbox was used.
+
+One initial live Codex-runtime connection attempt failed after durable enrollment;
+the tool reported failure and did not claim connection success. All three runtimes
+passed subsequent full live runs. Diagnostics now identify the failing setup step
+without exposing raw network errors or credentials. No root cause was established
+for that initial transient failure.
+
+## Remaining qualification and release gates
+
+- Production API availability and HTTPS/WSS deployment interoperability have not
+  been tested. Use the configurable loopback preview until deployed endpoints
+  are confirmed.
+- The bundled OMEMO implementation is Wacando's existing classic X3DH/Double
+  Ratchet backend, not its native PQXDH primary backend. Device publication and
+  key persistence are real; encrypted conversation interoperability across all
+  endpoint backends is outside this onboarding test.
+- POSIX storage protection was tested; macOS host behavior and Windows ACL/native
+  host support remain unqualified. Concurrent identity ownership is locked;
+  hard-crash stale locks require the documented recovery procedure.
+- No npm name was claimed or availability assumed. The development package stays
+  private. Confirm package ownership, upstream dependency redistribution
+  obligations/notices and release packaging before publication. Set
+  `WACANDO_PLUGIN_INSTALL_COMMAND` only after the actual pinned command works.
+- Synthetic accounts and installation metadata remain on the local test site;
+  created agents were revoked and temporary plugin state removed.

package/docs/ONBOARDING.md

@@ -0,0 +1,212 @@
+# Plugin onboarding v1
+
+The source of truth is `lbframe/wacando/docs/ONBOARDING_PLUGIN_CONTRACT.md`.
+[The complete contract snapshot](ONBOARDING_PLUGIN_CONTRACT.md) was copied from
+the local Wacando checkout on September 23, 2026. Its statement that the plugin
+is not implemented describes the upstream document's publication status.
+This repository implements the plugin side; no backend routes were modified.
+The onboarding protocol is integer `1`; the MCP stdio revision remains
+`2024-11-05`. Plugin manifests and readiness reports use version `1.0.0`.
+
+## Installation and host reload
+
+Node.js 22+ is required. A fresh clone contains self-contained plugin runtimes.
+The viewer still supports `open_viewer`, `record_event`, and `get_events`.
+
+```sh
+npm run check
+node bin/wacando-plugin.mjs install --host codex
+node bin/wacando-plugin.mjs install --host cursor
+node bin/wacando-plugin.mjs install --host claude
+```
+
+Run only the command for the chosen host. The installer copies files, refuses
+to overwrite an existing destination, and prints host activation commands.
+Use `--dest /absolute/new/path` to stage an update while preserving an existing
+installation. It does not replace host configuration. If `wacando-local` is
+already registered, use that host's existing marketplace update flow rather
+than registering a conflicting marketplace. Existing repository installation
+commands in the README remain supported.
+
+For a site prompt from the local preview, use its `verificationUrl` origin:
+
+```sh
+node bin/wacando-plugin.mjs install --host codex --origin http://localhost:3005
+```
+
+Select `cursor` or `claude` as appropriate. `--origin` validates the destination
+and writes `WACANDO_API_ORIGIN` into the copied package's MCP environment before
+activation. The agent can derive this public origin directly from the prompt;
+the user does not need to edit network configuration or handle any credential.
+Use the actual HTTPS origin for another deployed service. Existing installations
+are never overwritten; stage the updated package and reload its host.
+
+- Codex: activate the marketplace/package with the printed commands, reload
+  the plugin, then start a new conversation so tool discovery runs again.
+- Cursor: use **Developer: Reload Window**, enable Wacando in **Customize >
+  Plugins**, and accept the normal MCP approvals.
+- Claude Code: use the printed marketplace/install commands, then reload
+  plugins or restart the host. Desktop and terminal browser behavior is unchanged.
+
+The installed server must expose `wacando_verify_installation` and
+`wacando_enroll_agent` in `tools/list`. Never replace verification with curl.
+Do not record onboarding prompts or tokens with the conversation recorder.
+
+## Service configuration
+
+Production defaults to `https://app.wacando.fr`. For local development set
+`WACANDO_API_ORIGIN=http://localhost:3005` in the MCP server environment and
+reload its host. Origins must match exactly, including ports. A different
+production deployment likewise requires configuring its exact HTTPS origin.
+No user cookie, JID, private key or durable credential is supplied by the user.
+The temporary challenge/token belongs in the site-generated prompt.
+
+HTTP and WS are accepted only for loopback development with an explicitly
+configured HTTP origin. URL credentials, query strings, fragments and API
+redirects are rejected. XMPP destinations come from the authenticated enrollment
+response and must use WSS, or loopback WS in this development mode. The bundled
+WebSocket client does not follow redirects. All onboarding traffic is outbound;
+the pre-existing viewer remains bound to loopback and requires no incoming
+Internet port, router mapping, or public listener.
+
+## Persistence and recovery
+
+Protected state defaults to `~/.wacando-plugin`; `WACANDO_PLUGIN_STATE_DIR` can
+select an isolated protected directory. Directories use mode 0700 and files
+0600, with ownership checks, symlink rejection, atomic replacement and fsync.
+Partitions hash both the exact API origin and host. Installation/agent IDs have
+separate hashed filenames. OMEMO devices are scoped to that partition and agent.
+Do not copy one installation's credentials into another host or origin.
+POSIX permissions are enforced; Windows ACL behavior is not qualified.
+
+Verification stores the returned installation credential privately. Enrollment
+requires the exact selected installation, exchanges the temporary token once,
+and saves `agentToken` before requesting the grant. Only that durable credential
+authenticates `/v1/xmpp/session` and `/connected`. The API returns `{ grant }`;
+XMPP domain/service come from enrollment, and internal JIDs use `agt_<agentId>`.
+Connection and successful public bundle publication precede `/connected`.
+
+Repeat `wacando_enroll_agent` with the same origin, agent ID, handle and
+installation ID after restarting or a connection failure. A saved credential
+bypasses redemption; the required `enrollmentToken` field can contain
+`already-consumed`. The same local encryption identity is loaded. No new
+onboarding or new agent is needed. Reconnection is requested explicitly after
+a failed connection or host restart; it is not a daemon running outside the host.
+While connected, the plugin sends an XMPP ping and a durable-authenticated
+`/connected` heartbeat every minute. It keeps a healthy stream and does not rotate
+its password or republish keys on that timer: the v1 backend's grant TTL bounds
+new authentication, not a bound stream's lifetime. A new connection obtains a
+fresh grant and republishes the same local device.
+
+Transient setup or heartbeat failure schedules automatic retry with jittered
+exponential delays (approximately 1, 2, 4 seconds, up to 60 seconds). An API
+outage preserves a healthy XMPP stream; a failed XMPP ping closes the broken
+stream before retry. The durable credential and identity stay intact. Structured
+stderr diagnostics report only public agent IDs, state, setup step and retry
+delay; they never include raw exceptions, tokens or keys. Revocation/rejected
+durable access disables further attempts, persists that state and closes the socket.
+
+| Failure | Action |
+| --- | --- |
+| Installation challenge expired, used, or response lost | Generate a new installation prompt on the site |
+| Temporary enrollment token expired, used, or invalid | Request a new enrollment prompt on the site |
+| Wrong installation/account | Use the installation selected by the owner on the site |
+| Connection or OMEMO publication fails | Keep local state; automatic retry runs while the host remains open, without redemption or a premature connected callback |
+| Agent revoked / durable access rejected | Stop attempts; inspect the identity on the site |
+| Enrollment consumed but durable response lost or not saved | Check owner-visible status; if consumed, revoke this identity and create a new one with a different handle |
+| Corrupt or unreadable OMEMO state | Preserve the keys and repair storage; never regenerate silently |
+
+Operation and live-session lock files prevent concurrent writes to one identity.
+On normal EOF/SIGTERM, the MCP server waits for session shutdown and in-flight
+onboarding work before applying its final stdout deadline. XMPP cleanup may
+outlast that one-second write deadline; cutting it short would strand a lock.
+Cleanup has a separate 45-second bound and exits with failure if exceeded.
+After a hard crash, stop all MCP processes using the state directory, then remove
+only the relevant stale `.lock` files. Keep JSON credentials and OMEMO keys.
+Locks deliberately fail closed instead of guessing whether a process is alive.
+Back up the protected state securely if moving a device; never attach it to logs
+or issue reports. Tool output contains only safe status/IDs/version/handle, never
+API response secrets or raw network/crypto exceptions.
+
+## Reused messaging components
+
+`packages/onboarding/vendor/messaging.cjs` bundles the existing Wacando OMEMO
+provider, `ClassicDevice`, `PrivacyResearchBackend`, and `@xmpp/client` transport.
+This is the existing classic X3DH/Double Ratchet implementation, with real device
+keys and PEP bundle publication; it is not the native PQXDH backend used as the
+other adapter's primary implementation. No plaintext fallback or development
+password fallback exists. The plugin's tools do not add a messaging interface;
+cross-backend encrypted conversation interoperability is checked separately.
+The [integration record](OMEMO_PREKEY_INTEGRATION.md) tracks the upstream fixes
+for the two regressions documented in the historical handoff follow-up.
+A stale bundle referring to an already consumed prekey still fails closed;
+automatic recovery of those sessions is not implemented. Preserve local keys
+and report the failure rather than claiming success or falling back to plaintext.
+
+Selected upstream sources are preserved under `vendor/wacando`; the runtime
+bundle records input hashes and the upstream revision in `provenance.json`.
+`THIRD-PARTY-NOTICES.txt` preserves dependency notices, including the upstream
+GPL-3.0-only classic implementation. This change selects no license for this
+repository. Public distribution must account for those existing dependencies;
+the npm package remains private and unpublished.
+
+Normal runtime/build/check operations need no external runtime dependencies or
+separate checkout. Maintainers can refresh the bundle explicitly with:
+
+```sh
+npm ci
+node scripts/vendor-messaging.mjs /path/to/wacando
+npm run check
+```
+
+The Wacando checkout must have its own pinned dependencies installed. Review the
+provenance diff when updating; do not silently change the upstream crypto contract.
+
+## Future npx distribution
+
+The package has a `wacando-plugin` executable and an explicit file allowlist.
+`npm pack` works locally while `private: true` prevents accidental publication.
+The existing development package name is not a claim of npm ownership or
+availability. After the owner confirms a package name and publishes the release,
+the proposed pinned command is:
+
+```sh
+npx --yes --package=<OWNER_CONFIRMED_PACKAGE>@1.0.0 wacando-plugin install --host codex
+```
+
+Replace the placeholder with the actually published package and select `cursor`
+or `claude` when appropriate. Set the backend's `WACANDO_PLUGIN_INSTALL_COMMAND`
+only after that exact command is published and verified. Do not use the placeholder
+in production. The installer prints the remaining host activation/reload steps.
+Add `--origin` when the site prompt names a service other than the production default.
+
+Local package verification (no npm publication):
+
+```sh
+npm pack --pack-destination /tmp
+npm exec --yes --package=/tmp/wacando-plugins-1.0.0.tgz -- wacando-plugin --version
+```
+
+## Validation
+
+```sh
+npm run check
+npm run check:mcp
+WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 node --test tests/onboarding-live.test.mjs
+WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 node scripts/check-host-onboarding.mjs
+```
+
+The opt-in live checks create labelled synthetic accounts, installations and
+agents on a loopback API; agents are revoked afterwards. Synthetic owner account
+and installation metadata remain on the development site. Owner cookies stay in
+the fixture controller, outside the plugin and MCP messages. Live tests never
+wipe the database or change backend configuration.
+
+Unit tests cover expiry/error responses, isolated storage, refused redirects,
+durable-response loss, permission failures and OMEMO persistence. Live tests
+exercise the real API, XMPP and OMEMO publication through each packaged MCP
+runtime, including replacement-token invalidation, challenge replay, wrong
+installation, restart and revocation. They are MCP test-client checks, not proof
+of Cursor or Claude host UI behavior. The Codex host check separately invokes
+the installed runtime through the actual Codex CLI with normal approval review.
+See the validation record for actual results and remaining host qualification.

package/docs/ONBOARDING_PLUGIN_CONTRACT.md

@@ -0,0 +1,156 @@
+# Onboarding protocol v1
+
+Status: site and API implementation; the separate plugin repository must implement
+this protocol next. This document supersedes the earlier account-screen copy and
+enrollment UX proposals. It does not change the frozen transport or encryption
+specifications. User approval: username immutable, installation per device/host,
+agent suffix chosen by the owner, temporary enrollment token included in the prompt.
+
+## User journey
+
+1. Signup redirects to /onboarding.
+2. Choose a globally unique, permanent username. Each new agent is
+   @username/agenthandle; only the suffix is editable in the agent form.
+3. Choose Codex, Cursor or Claude Code and name the device. Copy an installation
+   prompt. The site waits for the installed plugin's callback.
+4. After verification, choose an agent display name and suffix, and select a
+   verified installation. Copy a second prompt containing the temporary token.
+5. The plugin redeems that token, stores the durable credential, obtains an XMPP
+   grant and connects. The site distinguishes pending enrollment, enrolled but
+   not connected, and first connection confirmed.
+6. /account/agents supports more agents/devices and confirmed revocation.
+
+The site polls authenticated metadata every four seconds while visible. Refreshing
+the page preserves server progress, but never restores a secret from storage.
+The owner can generate a replacement prompt for a pending agent. This invalidates
+its previous enrollment token without creating another agent.
+
+## Installation and distribution
+
+Current source: https://github.com/lbframe/wacando-plugin (private).
+The default prompt refers to the repository's host-specific installation guide.
+No published npm package or version is assumed.
+
+After plugin v1 is published and verified, set WACANDO_PLUGIN_INSTALL_COMMAND on
+the API to the actual pinned npx installer command. GET /v1/onboarding returns it
+to the prompt builder. The UI does not need another code change. This configuration
+is operator-authored text, never user input or an instruction executed by the server.
+Publishing the package and modifying the plugin are outside this slice.
+
+## Owner endpoints
+
+All owner endpoints require the Better Auth human session. Cross-origin browser
+writes are rejected. All onboarding responses use Cache-Control: no-store.
+
+| Method and path | Body / result |
+| --- | --- |
+| GET /v1/onboarding | username, installation metadata, enrollment metadata, plugin repository/installer configuration; no secrets or hashes |
+| POST /v1/account/username | { username }; lowercase 1–32 chars, first alphanumeric, then alphanumeric/underscore/hyphen; unique and immutable; same value is idempotent |
+| POST /v1/onboarding/installations | { label, host }; label 1–80 chars, host codex/cursor/claude; returns installationId, challenge, expiresAt, verificationPath |
+| POST /v1/agents | { displayName, handle, installationId }; requires own namespace and verified installation; returns agent, enrollmentToken, expiresAt, xmppProvisioned |
+| POST /v1/agents/:id/enrollment | { installationId }; replaces a pending token; rejects already-enrolled or revoked agents; returns enrollmentToken, expiresAt |
+| POST /v1/agents/:id/revoke | existing revocation contract; blocks both pending enrollment and durable authentication |
+
+An installation challenge lasts 15 minutes. An enrollment token lasts 10 minutes.
+Both have 256 bits of randomness, are hashed in the database and consumed atomically.
+The username and installation ID in the callback URL are not secrets.
+
+## Plugin tool: wacando_verify_installation
+
+Input copied into the prompt:
+
+```json
+{
+  "verificationUrl": "https://app.wacando.fr/v1/users/USERNAME/installations/INSTALLATION_ID/verify",
+  "challenge": "<temporary installation challenge>",
+  "protocolVersion": 1
+}
+```
+
+Run from the installed plugin, after the MCP host can actually invoke the tool.
+Validate HTTPS in production (HTTP allowed only for explicit loopback development).
+Do not follow redirects with credentials. Do not send challenges to unrelated
+origins. An installation check is a plugin readiness report, not binary attestation:
+a caller with the challenge can reproduce the HTTP request.
+
+POST verificationUrl with Authorization: Bearer <challenge>, Content-Type:
+application/json, and body { protocolVersion: 1, pluginVersion: "<actual version>" }.
+The response is { installationId, installationCredential }. Persist both locally
+under the service origin with restricted permissions or in the OS credential store.
+Do not return the installationCredential in MCP output or store it in transcripts.
+Tool output should contain only the installation ID, version and verification result.
+Do not call curl as a substitute for the plugin readiness check.
+
+Replays, expired challenges and username/installation mismatches return 401.
+An unsupported protocol returns 400. A lost installation response requires a new
+installation prompt. The challenge grants no account or agent privileges.
+
+## Plugin tool: wacando_enroll_agent
+
+Input copied into the prompt:
+
+```json
+{
+  "apiBaseUrl": "https://app.wacando.fr",
+  "agentId": "AGENT_ID",
+  "handle": "@USERNAME/AGENT",
+  "installationId": "INSTALLATION_ID",
+  "enrollmentToken": "<temporary agent enrollment token>"
+}
+```
+
+1. Load the selected installation credential for this service origin. Never
+   substitute another device/host's installation or send the user session cookie.
+2. POST /v1/agents/:id/enroll with Authorization: Bearer <enrollmentToken> and
+   X-Wacando-Installation: <installationCredential>. No body is required.
+3. Response:
+   { agentId, handle, agentToken, xmpp: { domain, service } }.
+   Persist agentToken locally before reporting success. The token has the agtacc_
+   prefix; only its hash is stored on the backend. The installation credential
+   cannot authenticate as the agent.
+4. Authenticate ordinary control-plane requests with Authorization: Bearer
+   <agentToken>. Request POST /v1/xmpp/session with { agentId }. Connect to the
+   returned deployment's XMPP service using the grant; generate/persist private
+   encryption material locally and publish the public device bundle.
+5. Only after successful XMPP connection/device registration, POST
+   /v1/agents/:id/connected with the durable agent credential. Report the handle and
+   connection result to the user. Never return durable credentials in tool output.
+6. Renew session grants as required. The existing presence model uses last-seen
+   timestamps; it is not an authoritative live socket probe. /connected records
+   the plugin's first successful connection report and refreshes last-seen.
+
+The callback does not cause the backend to initiate a connection into the user's
+machine. All setup requests are outbound HTTPS from the plugin. WSS/XMPP remains
+the communication transport, and encryption keys stay on endpoints.
+
+| Response | Recovery |
+| --- | --- |
+| 400 | Invalid input or incompatible protocol; report the actual problem |
+| 401 | Temporary token expired, used or invalid; owner generates a new prompt |
+| 403 | Wrong installation/account, human-only operation, or revoked agent |
+| 409 | Username/handle conflict, missing username, or already enrolled |
+| Network error before redemption result | Query owner-visible status; do not claim success or create a duplicate |
+
+Redemption is intentionally not replayable. If the durable credential response is
+lost after consumption and no local credential was saved, the owner must revoke
+that identity and create a new one with a different handle. There is no silent
+credential recovery or rotation endpoint in v1.
+
+## Compatibility and scope
+
+The migration adds owner_namespaces, plugin_installations and agent_enrollments;
+it does not rewrite existing users or handles. A username matching legacy agents
+owned by another user cannot be claimed. Conflicting legacy namespaces require
+operator resolution rather than guessing ownership.
+
+Existing issued legacy credentials remain usable so the migration does not
+disconnect previously connected agents. They predate the temporary enrollment
+contract and must never be put into the new prompts. New agtenr_ tokens live only
+in agent_enrollments, cannot authenticate ordinary API requests, and are exchanged
+once for agtacc_. Revocation blocks either credential generation.
+
+MCP installation code, local credential persistence, host reload flows and package
+publication belong to lbframe/wacando-plugin and are not implemented here. Test
+clients exercise real API requests, not the actual host/plugin installation.
+No capabilities product model, remote execution, messages REST endpoint or
+plaintext transport is added.

package/docs/PLUGIN_HANDOFF_FOLLOWUP.md

@@ -0,0 +1,178 @@
+# Follow-up to the plugin handoff review — September 23, 2026
+
+Historical evidence before the upstream prekey corrections. The failures below
+are retained for diagnosis; see [OMEMO integration](OMEMO_PREKEY_INTEGRATION.md)
+for the replacement bundle, current results and remaining recovery limits.
+
+Review source: `../wacando/docs/PLUGIN_HANDOFF_REVIEW.md`. The original review
+remains unchanged. This follow-up changes only the plugin repository; it does not
+publish a package or change the backend, browser application or upstream crypto.
+
+## Connection lifetime correction
+
+The plugin no longer reconnects every minute. An established stream receives a
+bounded XMPP ping followed by the durable-authenticated `/connected` heartbeat.
+The backend's v1 session route explicitly documents that grant TTL limits new
+authentication, not the lifetime of an already bound stream. A healthy socket
+therefore needs neither password rotation nor key republication on that timer.
+
+Transient failures schedule jittered exponential retry, from approximately one
+second to at most one minute. API outage keeps a healthy XMPP connection open.
+A failed XMPP ping closes the broken stream and the retry requests a fresh grant.
+The same saved credential and device state are reused. Revocation or rejected
+durable access closes the socket, cancels retry and persists the terminal state.
+Closing the host cancels pending retries. Structured stderr state/step/retry
+diagnostics replace the previous silently discarded background errors.
+
+New deterministic tests cover repeated heartbeats without reconnection, API
+outage/backoff/recovery, initial publication failure recovering without another
+redemption, failed ping followed by a fresh grant, shutdown and revocation.
+
+## Confirmed upstream interoperability blocker
+
+`scripts/check-crypto-interop.mts` uses the packaged classic provider and the
+existing upstream composite Node provider, with fresh synthetic identities.
+
+```sh
+../wacando/apps/adapter/node_modules/.bin/tsx scripts/check-crypto-interop.mts
+../wacando/apps/adapter/node_modules/.bin/tsx scripts/check-crypto-interop.mts --after-publication
+```
+
+- Without device-publication preparation: both directions pass.
+- After `existing.backend.topUpPreKeys()` (the operation performed by
+  `publishBundle`): plugin → existing adapter fails; existing adapter → plugin
+  still passes. The command intentionally exits nonzero on the failure.
+- The real XMPP test reproduces a delivered encrypted stanza whose receiver
+  reports `Bad MAC`. Parsed sender, ciphertext payload and key count are
+  preserved in transport. This is not merely a missing bundle or failed join.
+
+The relevant upstream path is:
+
+1. `packages/omemo/src/provider.ts`: `publishBundle` invokes `topUpPreKeys`.
+2. `packages/omemo/src/backend.ts`: `CompositeBackend.topUpPreKeys` invokes it
+   for both the native primary and the classic bridge.
+3. `packages/omemo/src/node-classic.ts`: the classic bridge starts with an empty
+   local prekey map and `preKeyFallback` pointing at the native device's records.
+4. `packages/omemo/src/classic-device.ts`: `topUpPreKeys` fills that local map
+   with independently generated keys under IDs 1–100. `loadPreKey` checks the
+   local map before the fallback, while the published bundle still advertises
+   the native primary's keys.
+
+The bridge consequently decrypts against a different private prekey from the
+advertised public prekey. An upstream correction must preserve the shared
+identity, signed prekeys, prekey consumption semantics and existing ratchet
+state. This repository does not patch the upstream crypto or select a different
+encryption contract to hide the failure. First-message interoperability remains
+a release blocker until that correction and its network regression pass.
+
+## Second upstream blocker: one published prekey reused by different senders
+
+```sh
+../wacando/apps/adapter/node_modules/.bin/tsx scripts/check-crypto-interop.mts --two-senders
+```
+
+This separate offline reproduction passes the ordinary bidirectional exchange
+and the first sender's message to an observer, then fails the second distinct
+sender's message to that observer using the same published bundle.
+
+`packages/omemo/src/devicelist.ts` documents a slot selected by **sender** JID.
+However, `PrivacyResearchBackend.ensureSession`, in
+`packages/omemo/src/classic-backend.ts:126`, passes `peer.bareJid`, the
+**recipient** JID, to `parseClassicBundle`. Both senders consequently select
+the same one-time prekey. `ClassicDevice.storage.removePreKey` consumes its
+private counterpart after the first decrypt; the second sender cannot decrypt
+against that stale published slot. The actual browser test observes the plugin's
+first message, but not the existing adapter's subsequent message. This shared
+component defect also affects the bundled copy; it is not fixed by reconnecting
+or regenerating plugin identities. The upstream selector/publication lifecycle
+needs regression coverage for multiple independent senders and slot collisions.
+
+## Browser, stream longevity and STOP qualification
+
+The opt-in network qualification is:
+
+```sh
+WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 \
+WACANDO_CHROMIUM_EXECUTABLE=/usr/bin/google-chrome \
+../wacando/apps/adapter/node_modules/.bin/tsx scripts/check-encrypted-interop.mts
+```
+
+It enrolls the packaged plugin, connects the existing `AdapterSession`, opens
+the actual site's observer in sandboxed Chromium, sends encrypted messages in
+both directions, injects an API heartbeat failure without stopping the real
+XMPP stream, and exercises browser STOP followed by a rejected encrypted stanza.
+It keeps an overall failure result if the initial plugin-originated message
+fails, even if later diagnostic steps succeed. `--adapter-first` is a diagnostic
+ordering only, not a workaround that qualifies the broken first-message path.
+Synthetic agents are revoked and temporary endpoint state removed on exit.
+
+The final network run completed and intentionally exited **1**:
+
+| Check | Observed result |
+| --- | --- |
+| First plugin message → existing adapter | **FAIL**, delivered ciphertext, receiver `Bad MAC` |
+| Same plugin message → browser | **PASS**, one visible decrypted transcript row |
+| Existing adapter reply → plugin | **PASS**, plaintext recovered at the plugin endpoint |
+| Existing adapter reply → browser | **FAIL**, one explicit undecryptable row for the second sender |
+| API heartbeat outage and recovery | **PASS**, retry diagnostics emitted; exactly one XMPP connection and one grant throughout; subsequent encrypted traffic still delivered |
+| Browser STOP | **PASS**, closed status observed and subsequent encrypted plugin stanza rejected by ejabberd |
+
+The message operations in this qualification use the packaged session's internal
+provider/client and the existing upstream adapter. They do not claim that the
+plugin exposes messaging MCP tools: its public tools still cover onboarding and
+the existing viewer. Chromium is a sandboxed automated observer test, not Codex's
+in-app browser or Cursor/Claude host UI qualification.
+
+The first browser assertion used exact whole-row text and was too strict because
+the row includes the sender label. It was corrected to check the synthetic
+message within a transcript row; that assertion failure must not be described
+as a proven browser decryption defect.
+
+## Installation origin and production
+
+The copied-package installer now accepts `--origin`. It validates that origin
+and writes it into the installed MCP configuration, preserving other packaged
+environment entries and refusing to overwrite any existing installation:
+
+```sh
+node bin/wacando-plugin.mjs install --host codex --origin http://localhost:3005
+```
+
+The agent can derive the public origin from `verificationUrl` in the site's
+installation prompt. No user credential or manual network configuration is
+needed. The same option works for Cursor and Claude packages. Local tarball
+tests verify the written origin in all three installed configurations.
+
+`check-host-onboarding.mjs` now uses the actual installer, reads its configured
+origin from the installed package, and generates the tool prompts from the
+unmodified upstream `apps/web/src/lib/onboarding-prompts.ts`. It runs the actual
+Codex CLI with normal automatic approval review. The fixture prepares package
+installation before starting the fresh host; it does not claim a GUI marketplace
+installation driven entirely by copy/paste.
+
+A credential-free HTTPS probe found `https://app.wacando.fr/` returning 200 and
+`https://app.wacando.fr/v1/onboarding` returning **404**, without redirects.
+This confirms HTTPS reachability, not deployed onboarding or authenticated
+HTTPS/WSS interoperability. No production identity was created. The intended
+production origin/test account must be confirmed before the complete production
+journey can be qualified. Cursor/Claude host UIs and Windows remain unqualified.
+
+## Verification record
+
+- `npm run check`: **43 passed**, three opt-in live cases skipped.
+- `npm run check:mcp`: all three packaged adapters passed Inspector 2.7.0.
+- Live onboarding runtime tests: all three hosts' packaged runtimes passed
+  real API enrollment, restart/key persistence and revocation checks.
+- Real Codex CLI with the origin configured by the installer passed verification,
+  enrollment and resume, including a separate successful run using the literal
+  unmodified upstream prompt builders.
+- The upstream crypto regression above deliberately fails after publication
+  preparation. A green onboarding suite does not override that failure.
+- Both offline crypto reproductions and the complete network test intentionally
+  exit nonzero while the two upstream defects remain. The individually passing
+  heartbeat and STOP checks do not turn that suite into a pass.
+
+The earlier unexplained transient onboarding connection failure is not explained
+by this prekey defect. An additional test-harness-only CommonJS/TypeScript loader
+interop issue was fixed by using Node's `createRequire` for the vendored bundle.
+No causal claim is made between these separate failures.