@wacando/agent 0.0.0-stage → 2.0.1

package/docs/MCP-AUDIT.md

@@ -0,0 +1,355 @@
+# MCP implementation audit
+
+Date: September 22, 2026. Baseline: `60e06c39dac8bf7dcad4e08cd804a70591ce5915`.
+Environment: Node.js `v22.22.0`, Linux. Official MCP Inspector: `2.7.0`.
+
+## Remediation status
+
+All seven findings below have been corrected in the shared sources and regenerated
+in the Codex, Cursor and Claude plugin runtimes. The original observations are
+preserved below as baseline evidence; their line numbers refer to the audited
+commit, not the current files. The [MCP contract](MCP-CONTRACT.md) describes the
+resulting behavior, limits, and supported revision.
+
+| Finding | Correction | Regression coverage |
+| --- | --- | --- |
+| F1 | Invalid HTTP request targets return 400; unexpected handler failures are contained | [HTTP survival and retained-event test](../tests/http-hardening.test.mjs) |
+| F2 | Validate request IDs/envelopes and method parameters; ignore responses and notifications without replying | [Protocol negative tests](../tests/mcp-protocol.test.mjs) |
+| F3 | Share tool schemas and strict validation, reject extra/provider arguments, count Unicode code points consistently | [Schema and Unicode tests](../tests/mcp-protocol.test.mjs) |
+| F4 | Bound input/output frames, rates, store bytes, pages, connections and SSE queues; await output writes | [Protocol/resource tests](../tests/mcp-protocol.test.mjs), [HTTP/SSE tests](../tests/http-hardening.test.mjs), [viewer history tests](../tests/viewer-history.test.mjs) |
+| F5 | Complete handshakes in test clients and enforce initialization state in the server | [Protocol tests](../tests/mcp-protocol.test.mjs), [relocated plugin tests](../tests/plugins.test.mjs) |
+| F6 | HTTP sockets have a shutdown grace period; MCP also has a final exit deadline for unread stdout pipes | [HTTP shutdown tests](../tests/http-hardening.test.mjs), [stalled stdout test](../tests/mcp-protocol.test.mjs) |
+| F7 | Build into clean staging directories, preserve old runtimes on preparation failure, compare exact generated inventories and bytes | [Build regression](../tests/build.test.mjs), [generated-file check](../scripts/check-generated.mjs) |
+
+`open_viewer` now reports a visibility preference and an unknown browser state.
+All host skills identify recorded text as untrusted historical data and explain
+pagination, rate-limit retries, and the 8 MiB retention budget. The viewer merges
+live events with paginated history without duplicates or resurrecting evictions.
+
+The supported protocol remains `2024-11-05`, explicitly documented and tested.
+Migration to the modern revision and optional structured results are versioned
+feature work, not unresolved defects in this legacy contract. Runtime dependencies
+remain empty, and existing host installations have not been overwritten.
+
+Remediation verification: `npm run check` passes all **29 tests** and the exact
+runtime inventory/content checks. `npm run check:mcp` passes official Inspector
+tool discovery and synthetic recording for all three generated adapters. Native
+host browser behavior and Windows/macOS remain outside this verification.
+
+## Initial assessment (baseline)
+
+The server interoperates with the official Inspector through the legacy MCP
+protocol, but it is not ready for a blanket claim of protocol compliance or
+robustness. A malformed local HTTP request terminates the MCP process. JSON-RPC
+envelopes and tool inputs are insufficiently validated, resource limits are
+incomplete, and the automated tests do not exercise a complete MCP handshake.
+
+The initial audit changed documentation only. Its probes used disposable processes
+and synthetic fixtures, not real user conversations or installed host instances.
+The subsequent fixes are summarized in the remediation table above.
+
+## Scope and authoritative references
+
+Reviewed the shared MCP server, event store, HTTP/SSE viewer service, browser-side
+data handling, all three adapters, plugin manifests and MCP configurations,
+skills and browser instructions, package generation, installers, and tests.
+
+The protocol reference is **https://modelcontextprotocol.io**, using explicit
+revision URLs. The implementation announces `2024-11-05`; that revision is the
+baseline for its existing wire contract. The current official documentation also
+describes `2026-07-28`, which has substantially different discovery and versioning.
+
+The local HTTP service is a **viewer API**, not an MCP HTTP transport. Its SSE
+events are application events. Missing MCP HTTP headers, OAuth discovery, an MCP
+POST endpoint, or MCP HTTP session management are therefore not findings here.
+The authorization specification distinguishes stdio from HTTP authorization.
+See [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+
+The official protocol does not make using an SDK a prerequisite for conformance.
+The repository's zero-runtime-dependency constraint can be preserved, but the
+manual transport needs stronger validation and independent interoperability tests.
+
+## Findings
+
+### F1 — High: malformed viewer URLs terminate the MCP process
+
+Location: [HTTP handler](../packages/server/server.mjs), line 28.
+
+`new URL(req.url, origin)` is outside the handler's exception boundary. Sending
+`GET //[ HTTP/1.1` with the correct local Host header causes `ERR_INVALID_URL`.
+Because the asynchronous HTTP callback rejects without a handler, Node exits.
+
+Reproduced against a disposable Codex MCP process after valid initialization:
+
+```text
+HTTP client: ECONNRESET
+Server: TypeError: Invalid URL
+Location: packages/server/server.mjs:28:22
+Process exit: 1
+```
+
+The viewer and MCP share this process, so the failure disconnects the host and
+discards its entire in-memory store. All packaged adapters share the affected
+code. The demonstrated attack surface is local HTTP access with an accepted Host;
+this is not evidence of a remote cross-origin exploit.
+
+Correction: catch malformed request-target parsing and return HTTP 400. Contain
+unexpected handler failures without terminating the process, and add a regression
+test that confirms MCP calls and previously recorded events survive the request.
+This is a service robustness defect, not a missing MCP HTTP feature.
+
+### F2 — Medium: invalid JSON-RPC envelopes produce invalid successful replies
+
+Location: [MCP dispatch](../packages/mcp/server.mjs), lines 29–37.
+
+Only `jsonrpc` and `method` are checked. Requests with IDs `null`, `true`, `{}`,
+`[]`, or `1.5` receive successful `ping` results echoing those IDs. Scalar
+`params`, such as `"invalid"`, are also accepted. A response-shaped input is
+misclassified as a request and receives an error response.
+
+For example:
+
+```json
+{"jsonrpc":"2.0","id":true,"method":"ping"}
+```
+
+Observed reply:
+
+```json
+{"jsonrpc":"2.0","id":true,"result":{}}
+```
+
+MCP specifies string or integer request IDs, forbids null request IDs, and
+distinguishes requests, responses, and notifications.
+See [MCP messages](https://modelcontextprotocol.io/specification/2024-11-05/basic/messages).
+
+Correction: validate the envelope before dispatch; classify message kinds;
+reject malformed requests without echoing invalid IDs into success responses;
+validate method parameters; and avoid replying to valid notifications or
+unsolicited responses. Add malformed-message tests alongside valid string and
+integer ID cases. Error responses to unidentifiable malformed input should be
+treated separately from successful responses to valid MCP requests.
+
+### F3 — Medium: tool implementations do not enforce their advertised schemas
+
+Locations: [tool schemas and dispatch](../packages/mcp/server.mjs), lines 7–20
+and 39–45; [event validation](../packages/core/store.mjs), lines 14–25.
+
+Reproduced after calling the server:
+
+| Input | Observed behavior | Advertised contract |
+| --- | --- | --- |
+| Valid `record_event` fields plus `unexpected: true` | Event recorded | Additional properties forbidden |
+| `record_event` with `type: null` | Recorded as `message` | Type must be an enumerated string |
+| `open_viewer` with `arguments: 42` | Success | Arguments must be an object |
+| `get_events` with an unsupported conversation filter | Entire snapshot returned | No arguments accepted |
+
+The store enforces nonblank required strings and length limits, but those limits
+are absent from the published input schema. The packaging test even sends a
+`provider` argument that the schema forbids, then expects success.
+
+MCP requires validation of tool inputs.
+See [tool security requirements](https://modelcontextprotocol.io/specification/2024-11-05/server/tools#security-considerations).
+
+Correction: enforce object shape, allowed properties, types, enum values, and
+length constraints at the tool boundary. Keep store validation as a second
+layer. Publish the actual constraints and test schema/implementation agreement,
+including Unicode length semantics. Reject a client-supplied provider while
+continuing to assign provider identity from the adapter.
+
+Distinguish malformed `tools/call` envelopes from domain validation failures.
+Do not mechanically replace every `isError: true` with a JSON-RPC error: the
+official guidance explicitly allows tool-level input validation errors.
+See [tool error handling](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling).
+
+### F4 — Medium: framing, invocation rates, and result sizes need bounds
+
+Locations: [stdio input/output](../packages/mcp/server.mjs), lines 22–25;
+[get_events](../packages/mcp/server.mjs), line 42;
+[HTTP snapshots and streams](../packages/server/server.mjs), lines 30–51.
+
+There is no application-level invocation rate limit, no maximum incoming stdio
+line size, and no handling of stdout backpressure. `readline` can accumulate an
+arbitrarily long unfinished line before store validation is reached. A probe
+sent a one-megabyte unused argument to `open_viewer` and received success.
+
+`get_events` always returns the full store. With 1,000 valid events of 32,000
+ASCII characters each, serialization through the current result shape produced
+**32,274,017 bytes**. HTTP snapshots and SSE reconnection also copy the full
+history. Bounded event count does not provide a small response or bounded
+transport queues. This can overwhelm host tool-result/context limits and cause
+large memory spikes. Actual out-of-memory failure was not induced.
+
+MCP's tool security section explicitly requires rate limiting.
+See [tool security requirements](https://modelcontextprotocol.io/specification/2024-11-05/server/tools#security-considerations).
+The particular byte budgets below are implementation recommendations, not
+protocol-prescribed constants.
+
+Correction: bound input bytes before newline parsing, rate-limit calls, handle
+stdout backpressure with bounded queues, and cap response bytes. Give
+`get_events` a bounded page size and conversation/sequence selection with a
+continuation mechanism. Review SSE client limits, initial snapshots, and slow
+readers under the same memory budget. This is pagination of a tool's data;
+pagination of the three-item `tools/list` is not required to fix it.
+
+### F5 — Medium: current tests give incomplete lifecycle assurance
+
+Locations: [runtime MCP test](../tests/runtime.test.mjs), lines 52–72;
+[plugin tests](../tests/plugins.test.mjs), lines 31–56;
+[MCP test helper](../tests/helpers/mcp-client.mjs);
+[MCP lifecycle handling](../packages/mcp/server.mjs), lines 32–38.
+
+The runtime test sends `initialize` without the required parameters. Plugin
+tests do not send `notifications/initialized` or validate the negotiated
+protocol version. The store-isolation test invokes tools without initialization.
+The server accepts all these sequences and ignores every notification. A direct
+probe successfully recorded an event before initialization and successfully
+initialized with an empty object.
+
+For the announced legacy revision, initialization precedes normal operation,
+and the client sends the initialized notification after negotiation.
+See [legacy lifecycle](https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle).
+
+Correction: make test clients perform a complete handshake, check a supported
+negotiated version, and cover invalid initialization, notifications, framing,
+error replies, and shutdown. Define server handling of premature calls and
+repeated initialization explicitly. Treat pre-initialization rejection as
+defensive hardening; the legacy specification's client sequencing obligations
+do not themselves mandate a particular server rejection code.
+
+The official Inspector checks below improve confidence for normal clients, but
+they do not replace negative tests or establish complete conformance.
+
+### F6 — Medium: shutdown has no application-controlled deadline
+
+Locations: [MCP stop handler](../packages/mcp/server.mjs), lines 50–54;
+[HTTP close](../packages/server/server.mjs), lines 62–66.
+
+An accepted TCP socket with unfinished HTTP headers can keep `server.close()`
+pending. The code tracks SSE responses but not all sockets, and has no deadline
+for finishing shutdown. Once stopping begins, the stop guard also makes a
+subsequent SIGTERM ineffective at advancing shutdown.
+
+A disposable-process probe opened a socket, sent `GET / HTTP/1.1\r\n`, and closed
+MCP stdin. The process was still running after 1.5 seconds and after another
+second following SIGTERM. Closing the HTTP socket allowed a clean exit. This
+demonstrates a peer-dependent shutdown delay; the probe did not wait for Node's
+HTTP timeout and does not assert that the delay is infinite.
+
+Correction: stop accepting work, finish active responses, then destroy remaining
+connections after a short grace period. Test EOF and SIGTERM with an active SSE
+stream and incomplete HTTP requests. Legacy MCP discusses shutdown timeouts,
+and current stdio guidance recommends prompt exit on EOF.
+See [legacy lifecycle](https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle)
+and [current stdio shutdown](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio#shutdown).
+
+### F7 — Low: package builds retain deleted source files
+
+Location: [package builder](../scripts/build.mjs), lines 7–11.
+
+The build copies source trees into existing runtime directories without removing
+obsolete files. In an isolated copy of the repository, a synthetic source file
+was built, deleted from source, and built again. All three plugin runtimes still
+contained it. This can retain retired code or assets in distributed packages.
+No obsolete sensitive file was found in the current packages.
+
+Correction: generate each runtime into a clean staging directory and replace
+only the build-owned output, then check exact source/output inventories. In CI,
+verify that rebuilding does not leave uncommitted runtime changes. This is a
+packaging defect, not a protocol violation.
+
+## Compatibility and secondary recommendations
+
+- **Legacy-only support is a limitation, not automatically a negotiation bug.**
+  Always returning `2024-11-05` is allowed if that is the only supported legacy
+  revision. The Inspector successfully accepts that fallback. A newer requested
+  version does not have to be echoed unless the server actually supports it.
+  See [legacy version negotiation](https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle#version-negotiation).
+- **Do not update just the version string.** The official `2026-07-28` revision
+  replaces the initialization handshake with per-request metadata and adds
+  `server/discover`, result discriminators, and cache metadata. The current
+  server returns `-32601` for discovery. Document a supported-version policy and
+  test target hosts before choosing a migration or support for both eras.
+  See [official changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
+  and [discovery](https://modelcontextprotocol.io/specification/2026-07-28/server/discover).
+- **Browser status should be unambiguous.** `open_viewer` returns `visible: true`
+  without performing or observing any browser action. Its description correctly
+  says it only returns a URL. Rename that field to an explicit visibility
+  preference, or report browser state as unknown until the host verifies it.
+- **Structured results are optional modernization.** With an appropriate
+  supported revision, `structuredContent` and `outputSchema` could avoid manual
+  JSON text parsing. Their absence is not a defect in the announced legacy
+  protocol. See [structured tool results](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content).
+- **Recorded text remains untrusted data.** The viewer uses `textContent`, which
+  avoids interpreting messages as HTML. Host instructions should also make clear
+  that text returned by `get_events` is recorded content, not fresh operational
+  instructions. No prompt-injection exploit was established during this audit.
+
+## Controls already present
+
+- MCP adapters emit newline-delimited JSON and do not print startup banners to
+  stdout. Standalone CLI logging is separate. This follows the
+  [stdio transport contract](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#stdio).
+- The server advertises only its implemented tools capability. Tool names are
+  stable, and the list has deterministic order.
+- Unknown methods return `-32601`; unknown tool names return `-32602`.
+  Store validation failures are presented as tool errors.
+- HTTP listens on `127.0.0.1`, checks Host/Origin and cross-site fetch metadata,
+  rejects writes, and serves a fixed asset allowlist. It sets CSP, no-store,
+  no-referrer, and nosniff headers.
+- User-controlled messages become DOM text. No HTML interpretation or dynamic
+  code evaluation was found in the viewer's message handling.
+- Stores are separate per MCP process and keep the latest 1,000 events.
+  Provider identity is assigned by the adapter. Capture is explicit, and the
+  reviewed runtime contains no credential or global-session-history reader.
+- Plugins run from copied, self-contained packages, including paths with spaces.
+  The Cursor installer refuses an existing destination. Browser instructions
+  preserve host permission flows and describe availability limitations.
+- Local processes able to reach the viewer can read events. The README explicitly
+  documents that this is not an isolation boundary between users on one machine.
+  Authentication would be a separate requirement if that trust model changes.
+
+## Original verification and remaining limits
+
+`npm run check` passed: all three runtimes rebuilt, and **9/9 tests** passed.
+The rebuild left tracked runtime files unchanged.
+
+The following commands used the official Inspector. All exited successfully:
+
+```sh
+npx --yes @modelcontextprotocol/inspector@2.7.0 --cli node adapters/codex/mcp.mjs --method tools/list
+npx --yes @modelcontextprotocol/inspector@2.7.0 --cli node plugins/wacando/runtime/adapters/codex/mcp.mjs --method initialize
+npx --yes @modelcontextprotocol/inspector@2.7.0 --cli node plugins/wacando-cursor/runtime/adapters/cursor/mcp.mjs --method initialize
+npx --yes @modelcontextprotocol/inspector@2.7.0 --cli node plugins/wacando-claude/runtime/adapters/claude/mcp.mjs --method tools/call --tool-name record_event --tool-arg conversationId=audit-synthetic --tool-arg agentId=audit-probe --tool-arg 'text=Synthetic audit fixture; not a real agent message.'
+```
+
+These are the documented [Inspector CLI](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli)
+workflow, pinned for reproducibility. Each command creates its own short-lived
+server; the returned viewer URL is not a persistent preview. Inspector was not
+added as a runtime dependency. An npm warning concerned Inspector's own legacy
+transport dependency, not a dependency of Wacando.
+
+Additional direct Node probes established F1–F3, the oversized input and result
+measurements in F4, premature calls in F5, the shutdown delay in F6, and stale
+build output in F7. Large Unicode events were also delivered in an SSE probe;
+no claim of reproducible SSE message loss is made.
+
+No host was reinstalled, no host browser was opened, and no marketplace was
+modified. Current Codex/Cursor/Claude UI loading, native browser behavior,
+Windows/macOS behavior, and remote/container port access were not verified.
+The earlier host observations in [STATUS.md](../STATUS.md) remain historical
+evidence, not fresh end-to-end validation. Stress exhaustion and an exhaustive
+protocol conformance suite were outside this audit.
+
+## Original recommended order
+
+1. Fix F1 and add its process-survival regression test.
+2. Fix F2–F3 and repair the lifecycle test client in F5.
+3. Bound transport/resource usage and shutdown in F4/F6.
+4. Make generated packages exact in F7 and clarify browser result semantics.
+5. Choose and document the supported MCP revision set, then add a pinned
+   Inspector interoperability check for each packaged adapter.
+
+Implement fixes in shared sources, run `npm run check`, and regenerate all three
+plugin runtimes through the builder. Existing host installations require their
+normal update flow; changing this checkout alone does not update them.

package/docs/MCP-CONTRACT.md

@@ -0,0 +1,138 @@
+# MCP contract and verification
+
+The authoritative protocol reference is [modelcontextprotocol.io](https://modelcontextprotocol.io).
+Protocol changes must identify the supported revision and update interoperability
+and negative tests. Do not infer requirements for the viewer API from the MCP HTTP
+transport specification.
+
+## Supported revision and lifecycle
+
+Wacando implements **MCP `2024-11-05` over stdio**, with the `tools` capability.
+It supports `open_viewer`, `record_event`, `get_events`,
+`wacando_verify_installation`, and `wacando_enroll_agent`.
+The viewer needs no credentials. Onboarding manages protected local credentials
+and bundled messaging components; see [onboarding v1](ONBOARDING.md).
+No prompts, resources, sampling, server-initiated requests or task execution
+capabilities are advertised.
+
+The client sends valid `initialize` parameters, accepts the returned revision,
+then sends `notifications/initialized`. Only then are tools available. Ping is
+allowed during initialization. Invalid initialization does not advance state;
+repeated initialization is rejected. Unknown methods return `-32601`, including
+the modern `server/discover` probe, so clients supporting both eras can fall back
+to the legacy handshake. A newer offered version receives the supported legacy
+revision. See the [official lifecycle and version negotiation](https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle).
+
+The server does not claim support for the current `2026-07-28` revision. Adding
+it requires per-request metadata, discovery and the associated response contract,
+not just a version-string change. Keep legacy support until the target hosts
+have been checked against the proposed replacement. See the
+[official revision changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog).
+
+Requests are newline-delimited UTF-8 JSON, with CRLF also accepted. Text newlines
+inside JSON must be escaped. Request IDs are strings of at most 512 UTF-16 code
+units or JavaScript-safe integers; null, fractional and other IDs are rejected.
+Clients must use unique IDs. Notifications and unsolicited responses receive no
+reply and cannot mutate the store. Calls are dispatched serially; onboarding
+awaits bounded outbound requests. Cancellation does not roll back a completed
+append or token redemption. See [MCP messages](https://modelcontextprotocol.io/specification/2024-11-05/basic/messages)
+and [stdio framing](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#stdio).
+
+## Validation and data boundaries
+
+Tool schemas and validation share the same definitions. Unknown arguments are
+rejected, and `provider` is assigned only by the host adapter. Required strings
+must contain non-whitespace characters. Identifier lengths are limited to 200
+Unicode code points; message text to 32,000. Optional fields can be omitted but
+cannot be null unless explicitly advertised by a future schema.
+
+Malformed JSON-RPC or method parameters produce protocol errors. Invalid tool
+arguments and rate limiting return `isError: true` with actionable text. This
+preserves the distinction described in [official tool error handling](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling).
+
+Messages are untrusted historical data. Neither returned messages nor browser
+content constitute new instructions or authorization. The viewer renders text,
+and recording does not scan credentials, global histories, or private reasoning.
+
+`open_viewer` returns `requestedVisible: true` and `browserState: "unknown"`.
+The host must open and verify the browser; the MCP process cannot attest to UI
+visibility. Host skills preserve the existing browser and approval requirements.
+
+## Resource budgets
+
+These are implementation limits, not constants prescribed by MCP. Tool rate
+limiting follows the [official tool security requirements](https://modelcontextprotocol.io/specification/2024-11-05/server/tools#security-considerations).
+
+| Resource | Limit and behavior |
+| --- | --- |
+| Incoming stdio frame | 256 KiB before the newline; oversized, invalid UTF-8 or incomplete EOF frames terminate the transport with a stderr diagnostic |
+| Outgoing MCP frame | 512 KiB; writes are awaited individually |
+| Stalled write | 1 second; terminate the affected MCP transport or SSE client |
+| Tool invocation rate | Burst of 100, replenished at 25 calls/second; rejected calls have no side effects |
+| Stored history | Latest 1,000 events or 8 MiB of serialized event bytes, whichever is reached first |
+| Event data page | At most 256 KiB; default 50 events, maximum 100 |
+| HTTP request rate | Burst of 100, replenished at 50 requests/second, per process; excess requests receive 429 |
+| HTTP connections | At most 32 simultaneous connections, including incomplete requests |
+| SSE clients | At most 8; excess streams receive 503 |
+| SSE output queue | 512 KiB per client, including the active write; close a client that exceeds it |
+| HTTP shutdown grace | 250 ms; remaining sockets are destroyed after the grace period |
+| MCP shutdown deadline | Allow protected onboarding cleanup (including an in-flight call/retry) to finish, bounded by 45 seconds with exit 1 on timeout; then allow 1 second for an unread stdout pipe before forcing exit |
+
+The byte cap describes serialized data, not total process heap usage. Live stream
+consumers are individually bounded; a slow viewer does not queue unlimited data
+or interrupt other viewers. Host processes and browsers should reconnect after a
+transport failure. Normal stdin EOF and SIGTERM close the viewer, including active
+streams and incomplete HTTP requests.
+
+## Reading events
+
+`get_events` and `GET /api/events` accept:
+
+- `conversationId`: optional exact conversation filter.
+- `afterSequence`: exclusive cursor, default zero.
+- `throughSequence`: inclusive upper bound, default the current sequence.
+- `limit`: maximum events, from 1 to 100, default 50.
+
+Each response includes `events`, `sequence`, `oldestSequence`, `retention`,
+`byteLimit`, `retainedBytes`, `historyTruncated`, and `nextAfterSequence`.
+Keep the first page's `sequence` as `throughSequence` and follow
+`nextAfterSequence` until it is null. A page may be shorter than `limit` because
+of its byte budget. An unknown conversation produces an empty page. Evicted
+history cannot be recovered; `historyTruncated` indicates the requested cursor
+predates retained history, independently of the conversation filter.
+
+Example tool arguments:
+
+```json
+{"conversationId":"task-1","afterSequence":50,"throughSequence":120,"limit":50}
+```
+
+SSE sends a bounded `snapshot` page first. The viewer fetches remaining history
+over paginated HTTP while live `message` events continue. Each live payload is
+`{event, oldestSequence}`. The viewer merges by ID, sorts by sequence, respects
+eviction, and ignores history responses from superseded connections. Export is
+disabled while the snapshot is incomplete. This SSE format belongs to the viewer
+application, not the MCP transport.
+
+## Builds and checks
+
+```sh
+npm run check
+npm run check:mcp
+```
+
+`check` regenerates runtimes from clean staging directories, compares every
+generated file against its source, and runs the regression suite. Preparation
+failures preserve the previous runtime. Only build-owned runtime directories are
+replaced; plugin manifests, skills and existing host installations are preserved.
+
+`check:mcp` runs the official Inspector pinned to `2.7.0` against each generated
+adapter, checking discovery through `tools/list` and a synthetic recording. It
+uses npm's executable cache and may need network access on its first run. The
+Inspector is development verification tooling, not a runtime dependency. See the
+[official Inspector CLI](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli).
+
+For CI, run both commands and `git diff --exit-code -- plugins/*/runtime` to ensure
+the checked-in packages match regenerated output. Commit runtime changes alongside
+their shared sources. Host installation and native-browser tests are separate;
+a successful CLI check does not verify a host's browser UI.

package/docs/MIGRATION-2.0.md

@@ -0,0 +1,36 @@
+# Migrating to runtime 2.0 (official libsignal OMEMO)
+
+Runtime/plugin 1.x encrypted with the **classic** OMEMO backend
+(`@privacyresearch/libsignal-protocol-typescript`, GPL-3.0, no PQXDH). The
+Wacando desktop apps use only the official `@signalapp/libsignal-client` and
+cannot decrypt classic sessions. Runtime 2.0 ships **only** the official
+backend (`@wacando/omemo`): bundles carry Kyber prekeys and sessions
+use PQXDH.
+
+There is no in-place key conversion: an identity key is bound to its device,
+its published bundle and its peers' trust pins.
+
+## What happens to an existing 1.x identity
+
+On connect, the runtime finds `classic-state.json` in the identity's protected
+state directory and stops with:
+
+> This identity was created by plugin 1.x with the retired classic OMEMO format
+> ... revoke it on the site and pair a new identity with a different address
+
+Nothing is deleted, rewritten or published: the classic keys stay on disk, no
+native device is created next to them, and no plaintext path exists.
+
+## Re-enrollment
+
+1. Stop every host or daemon using the old identity.
+2. In the Wacando app, revoke the old agent.
+3. Pair a new identity (new address) with this runtime: `wacando-agent pair
+   <code>` or the `wacando_pair` MCP tool ([pairing](AGENT_TOOLS.md)). The runtime generates a new
+   native device locally.
+4. Optionally archive, then delete, the old protected state directory once you
+   no longer need it (`~/.wacando-plugin/<partition>/omemo-<digest>/`). The
+   runtime never does this for you.
+
+Conversations of the old identity are not migrated; observers keep their own
+history.

package/docs/OMEMO_PREKEY_INTEGRATION.md

@@ -0,0 +1,125 @@
+# OMEMO prekey integration — September 23, 2026
+
+The upstream corrections described in
+`/home/kyle/work/wacando/docs/OMEMO_PREKEY_REVIEW.md` are now incorporated into
+this plugin checkout. The shared messaging bundle, preserved upstream sources,
+provenance and all three generated runtimes were regenerated. No backend or API
+contract changes, publication, deployment or push were performed here.
+
+## Included corrections and provenance
+
+- Publication replenishes the backend that owns the advertised prekeys; the
+  classic bridge cannot shadow them with different private material.
+- Classic consumption removes and persists the canonical native prekey.
+- Session initiation selects a sender-specific slot.
+- Replenishment allocates monotonically increasing, persisted prekey IDs.
+
+The upstream revision recorded in provenance is
+`babaa329fe288aa56cfb5e6b6b3c89a2d9aad86c`. The upstream fixes were uncommitted:
+that revision alone does **not** identify the imported code. All 154 input hashes
+in `packages/onboarding/vendor/provenance.json` were checked against the upstream
+working tree. Bundle and provenance copies match in all three runtimes.
+
+SHA-256 of `packages/onboarding/vendor/messaging.cjs`:
+`f316806787afce10d6df0a499a2e6b2b2ed5899fb47898b9e31024dffe08e5b3`.
+
+Existing identity keys, signed prekeys and ratchet state are preserved. There is
+no automatic identity reset or plaintext fallback. Restart the MCP host to load
+an updated installed package; keep its existing protected state directory.
+The installer refuses to overwrite an existing installation, so stage the new
+package separately and update the host registration using the
+[installation guide](ONBOARDING.md).
+
+## Independently repeated in the actual plugin checkout
+
+Environment: Linux, Node.js 22.22.0, npm 10.9.4, local service
+`http://localhost:3005`, actual ejabberd and a sandboxed headless system Chrome
+observer. The fixtures create synthetic accounts and revoke their test agents.
+
+```sh
+node scripts/vendor-messaging.mjs /home/kyle/work/wacando
+npm run check
+npm run check:mcp
+WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 node --test tests/onboarding-live.test.mjs
+
+WACANDO_CHECKOUT=/home/kyle/work/wacando \
+  /home/kyle/work/wacando/apps/adapter/node_modules/.bin/tsx \
+  scripts/check-crypto-interop.mts --after-publication --two-senders
+
+WACANDO_CHECKOUT=/home/kyle/work/wacando \
+WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005 \
+WACANDO_CHROMIUM_EXECUTABLE=/usr/bin/google-chrome \
+  /home/kyle/work/wacando/apps/adapter/node_modules/.bin/tsx \
+  scripts/check-encrypted-interop.mts
+```
+
+| Check | Result |
+| --- | --- |
+| Build and exact generated-runtime verification | PASS, all three runtimes |
+| `npm run check` final run | 43 PASS, three opt-in live tests skipped |
+| Official MCP Inspector 2.7.0 | PASS, all three runtimes |
+| Explicit live onboarding suite | 3/3 PASS: verification, enrollment, OMEMO, restart and revocation |
+| Offline crypto regression | 4/4 PASS: both directions and two observer senders after publication preparation |
+| Packaged plugin → native adapter and real browser | PASS |
+| Native adapter → plugin and real browser | PASS |
+| Injected heartbeat outage and recovery | PASS, one XMPP connection and one grant; subsequent encrypted traffic received |
+| Browser STOP | PASS, subsequent encrypted plugin stanza rejected by ejabberd |
+| Server canary scans | PASS, zero occurrences for all three prefixes in fresh dumps, logs and spool |
+| `git diff --check` | PASS |
+
+The first `npm run check`, overlapping the crypto/network checks, had five
+deadline failures: three MCP request timeouts and two relocated-package test
+timeouts (38 passed, three failed, two cancelled, three skipped). An unchanged
+rerun passed all 43 tests in 10.5 seconds. No timeout threshold or product code
+was changed to obtain the passing run. Scheduling contention is a possible
+explanation, not a proven root cause; these failures do not explain the earlier
+transient enrollment failure recorded in the baseline.
+
+Server scans were repeated from `/home/kyle/work/wacando` for each of
+`SYNTHETIC_PLUGIN_`, `SYNTHETIC_ADAPTER_`, `SYNTHETIC_AFTER_HEARTBEAT_`:
+
+```sh
+EJABBERD_CONTAINER=wacando-preview-xmpp \
+  bash packages/omemo/scripts/canary-scan.sh SYNTHETIC_PLUGIN_
+```
+
+The upstream 49/49 OMEMO unit-test result is reported in its review; it was not
+rerun here. The plugin regression and full encrypted network path above were
+rerun against this checkout's regenerated bundle. The older failing results in
+[the handoff follow-up](PLUGIN_HANDOFF_FOLLOWUP.md) are historical evidence.
+
+## Remaining limits and resumption
+
+- A cached bundle can still select an already consumed prekey, including a
+  collision between devices belonging to one sender. Such a session is rejected.
+  Automatic bundle refresh and complete recovery of old broken sessions are not
+  implemented. Do not delete identity files or claim that lost private prekeys
+  can be reconstructed. The successful two-sender run does not prove that all
+  possible slot collisions are avoided.
+- Production onboarding's reported 404 remains unresolved. HTTPS/WSS production
+  onboarding was not qualified by these local checks.
+- Actual Codex CLI 0.153.4 tool invocation and literal site prompts were repeated
+  against the final bundle after this vendor refresh: verification, enrollment
+  and fresh-host resume all passed using `WACANDO_LIVE_TEST_ORIGIN=http://localhost:3005
+  WACANDO_CHECKOUT=/home/kyle/work/wacando node scripts/check-host-onboarding.mjs`.
+  No durable credential markers appeared in host output. Runtime tests cover all three MCP
+  runtimes. Cursor Agent CLI 2026.08.25-3e8eec8 subsequently passed verification,
+  enrollment and fresh-host resume using the final copied plugin; see the public
+  readiness record for the command and scope. Claude and graphical host UIs,
+  Codex Desktop installation UI, Windows and long outage campaigns remain to
+  be qualified. The browser here is a Playwright-controlled web observer, not
+  Codex's in-app browser.
+- The encrypted-message fixture uses the packaged session's internal provider
+  and client. It does not add or imply a public messaging MCP tool.
+- Preserve saved credentials and keys when resuming a completed enrollment.
+  Reinvoke enrollment with the same origin, installation and identity; do not
+  redeem the consumed temporary token again. The separate API limitation when
+  enrollment consumes a token but its durable response is lost remains unchanged;
+  follow the recovery guide rather than claiming enrollment succeeded.
+- No npm package name availability is asserted. The versioned npx command in
+  the installation guide remains a publication placeholder. Nothing was
+  published or deployed.
+
+The [public onboarding readiness record](PUBLIC_ONBOARDING_READINESS.md) tracks
+deployment preparation, public probes, remaining host work and the proposed
+consumed-prekey recovery design. Initial deadline failures remain unexplained.