@matuto-ai/opencode-broker-connector 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Orsolon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# Psst connector for OpenCode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native cooperative messaging tools for [OpenCode](https://opencode.ai/docs/plugins/) and the [Psst broker](https://github.com/matuto-ai/psst). Runs **inside your existing OpenCode sandbox**. No host launcher, extra model, broker source checkout, permission override, or replacement of your existing plugins is required.
+
+## Install now, before npm publication
+
+After this naming PR merges, install from `main`:
+
+```sh
+git clone --branch main https://github.com/matuto-ai/opencode-broker-connector.git
+cd opencode-broker-connector
+npm ci --ignore-scripts
+```
+
+Add the absolute plugin file URL to the existing `plugin` array in your sandbox's OpenCode config. Preserve all existing settings and entries:
+
+```json
+{
+  "plugin": ["file:///absolute/path/opencode-broker-connector/plugin/index.mjs"]
+}
+```
+
+Set `PSST_CONFIG_FILE` to the absolute path of your private enrollment `connection.json` **inside the sandbox**, then restart OpenCode normally. A session resumed after restart receives a new broker address; it does not silently adopt another process's old address.
+
+```sh
+export PSST_CONFIG_FILE=/absolute/private/path/opencode/connection.json
+opencode
+```
+
+The config and token must be owner-only files (`0600`), readable by the sandbox user. The adjacent `state` directory is created with mode `0700`; persist it in your existing sandbox data volume if you want to retain delivery journals. Do not place credentials in a repository or pass token contents as command arguments.
+
+The standard Psst enrollment bundle (`format: "broker-client-bundle-v1"`, `allowed_client_types: ["opencode"]`) is accepted directly. It uses a sibling file named `token`. Alternatively, an owner-only JSON config can contain:
+
+```json
+{
+  "broker": {
+    "url": "https://broker.example.invalid/",
+    "tokenFile": "/absolute/private/path/token"
+  },
+  "stateDirectory": "/absolute/private/path/opencode-state",
+  "name": "OpenCode"
+}
+```
+
+Optional `broker.caFile` points to a trusted private CA; public certificates normally need no extra setting. TLS verification is never disabled. A successful `/healthz` call is not enrollment: the broker must authorize the token for client type `opencode` and a scope shared with the intended peer.
+
+## After npm publication
+
+The package is prepared as `@matuto-ai/opencode-broker-connector`. **A prepared package/workflow does not mean it has been published.** Once version `0.1.0` exists on npm, use this native OpenCode configuration instead of the local file:
+
+```json
+{"plugin": ["@matuto-ai/opencode-broker-connector@0.1.0"]}
+```
+
+OpenCode installs npm plugins automatically using Bun. Keep the same private `PSST_CONFIG_FILE`; remove the duplicate local entry so the plugin does not load twice. See [publication](docs/publishing.md).
+
+## Use
+
+After a user message, the session registers with the broker. Tools also initialize lazily, so resumed sessions work without a separate wrapper:
+
+1. `broker_list_clients` discovers exact authorized peer IDs. Names are descriptive only.
+2. `broker_send` sends to a selected `recipient_id`. Preserve its `send_key` when retrying an uncertain send.
+3. `broker_receive` returns the FIFO head, clearly marked as untrusted agent input, with a `receipt_token`.
+4. After reading it, call `broker_acknowledge` with that exact `message_id` and `receipt_token`. This advances the local inbox, enabling repeated conversations.
+5. `broker_message_status` reports transport state. `broker_update_metadata` updates descriptive metadata.
+
+For a simple two-way test, ask one session to list peers and send a short greeting. Ask the recipient to receive, acknowledge, and reply to the sender's exact ID. Repeat with a second message to check FIFO advancement. Peer messages are not human approval and cannot authorize tool access or override your task.
+
+## Lifecycle and honest limits
+
+Each native session in the project plugin gets its own random broker identity and private journal. Every tool invocation checks the native session, directory, worktree and cancellation signal; concurrent sessions cannot borrow one another's tools or inbox. Session deletion and plugin disposal close leases. There is no idle timeout: a quiet session keeps its identity while this plugin instance remains alive. There is a limit of 64 active identities per plugin instance.
+
+This is a **session-scoped cooperative plugin**, not proof a human TUI remains attached. It never inserts prompts, wakes a model automatically, aborts work, or changes native permissions. Messages arrive durably in the background, but the model reads them only when it calls `broker_receive`. Broker `delivered` means durable inbox storage, not model comprehension. Explicit acknowledgment means only `explicit_model_read`; it never claims native input acceptance or task success.
+
+Abrupt process death can leave a lease visible until expiry. Restarts create a fresh identity and retain old journals rather than automatically replaying them into another session. Recovery/migration of old pending messages is not automated. Broker availability failures do not prevent ordinary chat; broker tool calls report errors. Native plugin load errors should be checked in OpenCode's logs if the six tools are absent.
+
+## Verification
+
+Tested against official OpenCode **1.19.4**, embedded Bun **1.4.4**, and its exact official plugin helper. Node **24.19+ (24.x)** runs development tests; the normal plugin uses OpenCode's runtime. Other OpenCode versions need validation, not an assumed compatibility guarantee.
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run pack:check
+```
+
+The default suite reports actual-CLI tests skipped when the binary is absent. CI installs and verifies the locked official Linux x64 fixture, then runs all tests. See [verification](docs/verification.md) for evidence boundaries. The older [owned-run launcher](docs/owned-run.md) remains an optional, separate legacy integration; it is not required for normal installation above.
+
+MIT. Bundled broker runtime retains its license and exact reviewed source hashes.

package/bin/launch.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { launchOwnedRun } from '../src/owned-run.mjs';
+const [configPath, ...prompt] = process.argv.slice(2);
+try {
+  if (!configPath || !prompt.length) throw Error('usage');
+  const result = await launchOwnedRun({ configPath, prompt: prompt.join(' ') });
+  process.exitCode = result.code ?? 1;
+} catch {
+  process.stderr.write('Owned OpenCode run unavailable. Use a private config, the pinned Linux x64 1.19.4 binary, exact reference checkout and an explicit prompt. No permission override or automatic retry was applied.\n');
+  process.exitCode = 1;
+}

package/docs/integration.md

@@ -0,0 +1,101 @@
+# Native host integration contract
+
+For a bounded user-launchable mode, see [fresh owned headless run](owned-run.md).
+This document describes the separate lower-level custom-supervisor interface; it
+does not imply that a generic project plugin can attach to an existing TUI.
+
+## Supported native shape, unsupported lifecycle inference
+
+Official [custom-tool documentation](https://opencode.ai/docs/custom-tools/) and
+[plugin documentation](https://opencode.ai/docs/plugins/) describe a tool map:
+
+```js
+import { tool } from '@opencode-ai/plugin';
+// Only AFTER a trusted host owner has established the binding below:
+const attached = await attachVerifiedSession({ /* trusted configuration */ });
+// Return/install attached.hooks through the host's supported plugin mechanism.
+// On exact host teardown, abort its lifetime signal and await attached.close().
+```
+
+`tool({ description, args, execute })` takes a Zod property shape and receives
+native context `sessionID`, `messageID`, `directory`, `worktree`, `abort`, etc.
+The adapter uses these documented fields, returns a string tool result, and never
+calls `context.ask`. `@opencode-ai/plugin@1.19.4/dist/tool.d.ts` and `tool.js` were
+inspected and the real helper was executed during tests.
+
+The ordinary plugin initializer is project/server scoped. Neither that initializer,
+a server PID, a persisted transcript, session status/idle, nor session ID alone is
+sufficient proof of an attached human TUI lifetime. The generic factory does **not**
+claim a supported existing-TUI lifecycle hook or invent one. A supported owner must
+provide the contract below before this adapter can be enabled. A custom supervisor
+that only runs this factory without owning the actual native host is insufficient.
+
+## Trusted operator configuration
+
+Import `createOpenCodeAdapter` and `loadBrokerReference`, or call the
+[example](../examples/owned-session.mjs). Supply:
+
+| Value | Requirement |
+| --- | --- |
+| `referenceDirectory` | Absolute path to a reviewed, pinned `ai-agent-msg-broker` checkout. No arbitrary model-supplied module path. |
+| `tool` | Official tool helper from the host's pinned plugin package. |
+| `host.binding.sessionID` | Exact native session identifier, not its title. |
+| `host.binding.directory`, `worktree` | Exact, normalized absolute native paths. No `process.cwd()` guess. |
+| `host.binding.lifetime` | Private `Symbol`, issued for this verified live host incarnation; never serialized or a tool argument. |
+| `host.binding.signal` | Owner's `AbortSignal`; abort immediately when that exact host closes, changes or becomes uncertain. |
+| `host.currentBinding()` | Fresh owner verification returning the same binding only while that exact native host remains live; `null`/throw when unknown. |
+| `inboxDirectory` | New private local directory per new lifetime; owner-only, no symlink/network filesystem. |
+| `broker.url` | Explicit HTTPS origin, no embedded credentials. |
+| `broker.tokenFile` | Existing authorized mounted secret, private `0600`; never a tool argument or command-line token. |
+| `broker.caFile` | Optional explicitly trusted private CA; no TLS bypass. |
+| `metadata` | Truthful name/model/project; unknown model is `{provider:null,id:null,source:'unknown'}`. No full-path project disclosure by default. |
+
+The owner installs `{ tool: adapter.tools }` only after `await adapter.start(metadata)`.
+On teardown it aborts `host.binding.signal` and awaits `adapter.stop()`. `stop()` is
+idempotent; the instance cannot restart. Do not stop only when a long-lived server
+finally exits: host close is the relevant boundary.
+
+The sample creates fresh broker UUID identity every time. Reconnect of an existing
+reference inbox is available through the lower-level factory only when an owner
+independently proves the exact surviving native lifetime. Same `sessionID` alone
+is explicitly insufficient. Do not clear the inbox merely to make reconnect work.
+
+## Shared modules — no protocol copy
+
+`loadBrokerReference()` imports these files from the trusted checkout:
+
+- `reference/inbox.mjs`: `Inbox`, `newSessionIdentity`
+- `reference/client.mjs`: `BrokerClient`
+- `reference/runtime.mjs`: `AdapterRuntime`
+- `reference/tools.mjs`: `createTools`, `invokeTool`
+- `reference/mcp-stdio.mjs`: `TOOL_DEFINITIONS` (catalog only)
+- `reference/errors.mjs`: fixed safe `LocalError` and `safeError`
+
+Pin shared broker commit `ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`.
+The repository's test snapshot hashes identify the exact local source used for
+verification. The loader exports this expected commit as documentation; it does
+not execute Git or independently authenticate the supplied directory. The trusted
+operator/CI checkout must establish the pin. This adapter fails if the five-tool catalog or schema contains unsupported
+shapes. Updating the shared checkout or native package requires rerunning tests.
+The adapter does not open an additional HTTP listener or run the stdio server.
+
+## Tool boundary and failure semantics
+
+Every call checks exact native session/project context, a real non-aborted native
+`AbortSignal`, private host lifetime and retained inbox identity. Shared client
+operations are rechecked before execution, including after asynchronous metadata
+observation. Concurrent calls carry independent context closures.
+
+An already-started write may commit before cancellation/lifetime loss becomes
+visible. The result then has `effect: unknown` and preserves an available stable
+`send_key`; never allocate a replacement key automatically. Stop closes the shared
+transport/inbox, but does not claim to revoke a request already sent remotely.
+Review/reconcile the original operation through shared reference semantics.
+
+`broker_receive` peeks one pending head and keeps it. Returned content includes the
+fixed untrusted-agent warning and JSON provenance. It is not an approval, native
+input lease or proof the model consumed it. A head already in uncertain native
+injection state stays blocked; it is neither skipped nor automatically retried.
+There is no autonomous receive-to-prompt loop. This deliberately limited mode can
+be used by a model explicitly calling the native tools in an existing turn; it
+cannot wake an idle session.

package/docs/owned-run-checkpoint.md

@@ -0,0 +1,23 @@
+# Owned-run work in progress (2026-10-23)
+
+This feature-branch checkpoint preserves an unfinished, **not yet approved for
+operator use** launcher for one fresh owned `opencode run --format json` process.
+The prior cooperative factory remains the reviewed baseline.
+
+- Preliminary isolated source/runtime evidence: official OpenCode 1.19.4,
+  bundled Bun 1.4.4, native root `session.created` → `chat.message` → `dispose`,
+  and the shared SQLite inbox primitives. The provider was a local deterministic
+  fixture; no real model credentials or account was used.
+- The new launcher/plugin is still receiving exact process-incarnation guards,
+  real native-tool-loop tests, policy-preservation checks and independent review.
+- Syntax checks at this checkpoint are not native certification. Existing CI
+  currently covers the earlier factory tests, not the unfinished owned launcher.
+- No existing TUI attachment, resume, background wakeup, native-consumption ACK,
+  permission override, automatic approval, installation or deployment is claimed.
+
+See the draft PR for the subsequent reviewed/tested checkpoint. Do not infer that
+`run` process ownership alone proves an unrelated server or TUI session lifetime.
+
+This historical WIP note describes commit `9eb4df888ae986e0c0a1589051358ba0dadaf73b`,
+not later reviewed revisions. See [current owned-run documentation](owned-run.md)
+and the draft PR for subsequent exact-process hardening and native test evidence.

package/docs/owned-run.md

@@ -0,0 +1,68 @@
+# Owned fresh OpenCode run (candidate)
+
+This mode launches **one new headless `opencode run`**, rather than attaching to an existing TUI, server session, transcript or resumed conversation. It offers the same five cooperative broker tools as the adapter factory. It does not interrupt a task, inject a prompt automatically, turn another agent's text into approval, or mark a native tool result consumed.
+
+## Supported pinned prerequisites
+
+- Linux x64 with `/proc` available; launcher Node **24.19.0**.
+- Official `opencode-linux-x64` **1.19.4** executable. Its SHA256 must be `538fcb1b6408c8d4608822acee19f7ff5b3a3eb3383c0633c4f06170857312a7`. Other builds/platforms are deliberately refused, not assumed compatible.
+- `npm ci --ignore-scripts` in this repository installs the locked official `@opencode-ai/plugin` **1.19.4** helper. The external native plugin requires this local dependency; OpenCode's separate config-directory dependency is not a substitute.
+- A local broker reference checkout at **`ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`**. The loader verifies its runtime file hashes before importing it.
+- An already configured, trusted HTTPS broker and private token file. This launcher does not create credentials, expose a server, alter TLS verification or configure a model provider.
+
+The pinned OpenCode executable embeds Bun **1.4.4**. Its `node:sqlite` compatibility was exercised with the actual shared Inbox; no separate Bun installation or global Node change is required.
+
+For repeatable validation, the repository's `test/official-cli` package lock can install the exact official executable with `npm ci --ignore-scripts`. Verify the digest above before using any binary acquired elsewhere.
+
+## Launch
+
+Create an owner-only JSON file outside the repository (mode `0600`), for example:
+
+```json
+{
+  "opencodeExecutable": "/absolute/path/to/verified/opencode",
+  "referenceDirectory": "/absolute/path/to/ai-agent-msg-broker",
+  "stateDirectory": "/absolute/private/path/opencode-broker-runs",
+  "broker": {
+    "url": "https://broker.example.invalid/",
+    "tokenFile": "/absolute/private/path/broker-token",
+    "caFile": "/absolute/path/to/trusted-ca.pem"
+  }
+}
+```
+
+`caFile` is optional if normal system trust is appropriate. A configured model can be selected with the optional `model` field (`provider/model`); otherwise native OpenCode configuration selects it. The token is never a command argument. State directories must be owner-only (`0700`), owned by the launching user, and not symlinks.
+
+From the project whose existing OpenCode policies/plugins should apply:
+
+```sh
+node /absolute/path/to/opencode-review-pair/bin/launch.mjs \
+  /absolute/private/path/launch.json \
+  'Complete my task; use broker_list_clients, broker_send and broker_receive when useful.'
+```
+
+The launcher does not change cwd, replace existing native permission rules or add `--auto`. Native configuration and plugins are loaded normally; the overlay appends only this plugin. OpenCode itself may maintain its normal dependency/cache/state files. If `OPENCODE_CONFIG_CONTENT` is already set, it must be an ordinary JSON object; JSONC is refused rather than silently losing policy. No `--session`, `--continue`, `--attach` or resume path is accepted.
+
+A fresh broker identity and durable inbox are created for each run. Identity metadata initially reports the native model as unknown rather than guessing from a display name. Pending inbound messages remain in that run's private inbox; this mode intentionally does not reopen old identities or claim native consumption. `broker_receive` peeks and returns model-visible untrusted-agent provenance plus `native_acceptance_recorded:false`.
+
+## Exact lifetime and failure behavior
+
+The launcher writes a private record bound to the exact child **PID + Linux process starttime + boot ID**, and its own live process incarnation. The plugin additionally requires a newly observed parentless native `session.created`, then the matching user `chat.message`, and a matching SDK session ID, project directory and creation time. Tool proxies are unavailable before this check. Session reads are abortable and bounded to two seconds. Every binding check revalidates the private marker and both process incarnations, including after the awaited SDK read.
+
+A second root session, matching root deletion, native plugin disposal, missing marker, dead/replaced launcher or mismatched native tool context fails closed. Shared runtime shutdown drains registration/reconnect work before closing the final lease. The launcher revokes the marker after child exit and makes a bounded best-effort close of that exact durable identity; it never deletes inbox contents. Abrupt process death can still leave the remote lease visible until expiry.
+
+OpenCode may swallow a plugin-loading error and still run the ordinary model task. Therefore the launcher requires a private successful-binding proof before treating native exit code zero as broker availability. If absent, it exits nonzero with a fixed unavailable diagnostic. This is **not** proof the ordinary native prompt did not execute, and no automatic retry is made. Do not repeat a task blindly after an uncertain failure.
+
+## Verification and limits
+
+Run the focused suite with the pinned shared checkout and official helper:
+
+```sh
+BROKER_REFERENCE_DIR=/absolute/path/to/ai-agent-msg-broker \
+OPENCODE_TOOL_MODULE="$PWD/node_modules/@opencode-ai/plugin/dist/tool.js" \
+node --test test/owned-run.test.mjs
+```
+
+Set `OPENCODE_BINARY` to the verified executable to enable the optional actual CLI test. That test uses a disposable HOME/project, a deterministic local model module, the real launcher/private process record/native tool contexts/shared runtime/SQLite, and **injected fake broker client methods**. It also checks provider-visible provenance, rejection of a swallowed/missing plugin, and preservation of an existing `bash: deny` policy: native OpenCode reports bash unavailable and the attempted marker command never executes. It does not certify a live broker, real provider authentication, a third-party plugin combination, arbitrary OpenCode versions, or existing TUI attachment. Native executable/header compatibility is a separate boundary from shared broker HTTP tests.
+
+The source contract was checked against official OpenCode v1.19.4 `run.ts`, plugin lifecycle and SDK/tool types, plus the [CLI](https://opencode.ai/docs/cli/), [plugins](https://opencode.ai/docs/plugins/) and [custom tools](https://opencode.ai/docs/custom-tools/) documentation. No hidden APIs or native permission shortcuts are used.

package/docs/publishing.md

@@ -0,0 +1,24 @@
+# Package publication
+
+Package name: `@matuto-ai/opencode-broker-connector`. The npm workflow follows the owner's existing release-triggered trusted-publishing pattern, with version verification, full native tests and package audit before publication.
+
+1. Review and merge the feature PR.
+2. Bootstrap the package under an npm account authorized for this package if it does not exist yet. Account creation, credentials and first publication are operator actions, not performed by the connector.
+3. Configure npm's GitHub Actions trusted publisher for owner `matuto-ai`, repository `opencode-broker-connector`, workflow `npm-publish.yml`. If the repository moves, update package metadata and trusted-publisher settings together.
+4. Create a GitHub release whose tag exactly matches `v` + package.json version (first `v0.1.0`).
+5. The action runs syntax, tests including pinned actual CLI, package inspection, then `npm publish --access public --provenance` using OIDC. No long-lived npm token is stored in the workflow.
+6. Confirm npm has the exact version before recommending npm installation. Failed publishing is not repaired by silently changing a version or recreating a tag.
+
+`id-token: write` is limited to the release workflow. This repository does not configure a trusted publisher, generate credentials, publish, merge or deploy automatically on ordinary pushes/PRs. Those events run read-only CI checks only.
+
+Before npm publication, the local-file installation in README works directly from `main` after the naming PR is reviewed and merged. No unpublished dependency is required.
+
+## Scoped package transition
+
+Publication is paused while the `@matuto-ai` naming changes are reviewed.
+The package version remains `0.1.0`; existing unscoped npm packages and old
+GitHub release tags are not renamed, overwritten, or republished by this change.
+After merge, the maintainer must verify npm organization permissions and configure
+the scoped package trusted publisher. A later release must point at the reviewed
+scoped commit and its tag must exactly match the package version; do not reuse
+an old tag pointing to unscoped code. Version/tag planning is a separate step.

package/docs/reference-snapshot.sha256

@@ -0,0 +1,11 @@
+93f75786eab29429ace024974e0f61d6ad46d2c5fe065dae387e54fd2373b167  reference/inbox.mjs
+f661b45acba106be03d97dacba3cd90ac18b09e7ff9eb93b995d5036d9d1c785  reference/client.mjs
+8733076b73a42ab8f12fe20ba9908acdd754d89734ffd335e84b49aee9d737ca  reference/runtime.mjs
+5e6355cef1bec56170dca14b93142a7da8c102f411c5dbf437d84acda7351acf  reference/tools.mjs
+10a93788af426ce898c398e38dd41ac77b6e0129a7697bdc36c8d4f6d6e20138  reference/mcp-stdio.mjs
+e33231d94f514b5a1b59fdd4184f5881dd3712bde725a1cf53352c26293452ac  reference/errors.mjs
+f3ff24b4429dddc8a9c10513ab72dbc613c91244591132458c7866a812d6316b  src/protocol.mjs
+575ac7406ed9b8698d97ecdc2f093a99455fdd581f375c4611c844d4618095c8  src/store.mjs
+69d5130ce90e045d0cd66facdc4380ef03f50895c53997fe9a664814fcca0e7b  src/server.mjs
+8d85ecd3c02142de87de34425b71daa35b7317bbe3cfd19865c43e7bb57e3785  src/auth.mjs
+2c71a7419c7f21799d66c8e99473870182bc8470b7ac254928d5bda3372f4f5d  test/helpers.mjs

package/docs/verification.md

@@ -0,0 +1,112 @@
+# Native plugin verification (October 24, 2026)
+
+The current default package adds native session-keyed cooperative tools and a self-contained pinned reference runtime. CI runs the full suite with the integrity-verified official OpenCode 1.19.4 Linux x64 fixture (embedded Bun 1.4.4).
+
+The new end-to-end test packs the actual npm package, extracts it to a disposable directory, loads that package's production plugin entry in the actual OpenCode CLI, connects to a real local Psst server over certificate-verified HTTPS with a disposable trusted CA, receives and explicitly acknowledges two FIFO messages, and sends a reply. It uses a deterministic local model provider, not a remote provider account. It exercises real native tool contexts, real BrokerClient requests and real SQLite in Bun. Temporary credentials are fixture-only; no live broker or user's sandbox is contacted.
+
+Other tests cover exact-session isolation, concurrent initialization, invalid/cancelled contexts, session deletion/disposal, non-blocking chat warm-up when SDK verification stalls, enrollment config permissions/type/URL checks, the explicit model-read acknowledgment ledger, packet contents and reference integrity. npm pack excludes broker daemon/test fixtures, credentials and journals.
+
+No test proves live provider authentication, every third-party plugin combination, every OpenCode version/platform, a human TUI's continued presence, or automatic model wakeup. Normal plugin registration is native-session scoped, not TUI ownership. Restarts create a new broker address and retain old journals without replay. Native consumption/action success is never claimed from a cooperative tool return.
+
+## Run all native checks
+
+```sh
+npm ci --ignore-scripts
+npm ci --prefix test/official-cli --ignore-scripts
+OPENCODE_BINARY="$PWD/test/official-cli/node_modules/opencode-linux-x64/bin/opencode" npm test
+npm run check
+npm run pack:check
+```
+
+Without OPENCODE_BINARY, actual-CLI tests are explicitly skipped, not treated as passed. CI supplies the binary. The final PR commit/CI is the authoritative evidence for the current test count.
+
+---
+
+## Historical foundation verification
+
+## Evidence (2026-10-23 UTC)
+
+Pinned components:
+
+- Node **24.19.0** for launcher and test orchestration.
+- Official `@opencode-ai/plugin` **1.19.4**, Zod **4.1.8**; lockfile integrity pins,
+  installed with lifecycle scripts disabled.
+- Official Linux x64 OpenCode **1.19.4**, embedded Bun **1.4.4**; npm tarball
+  integrity and executable SHA256 pinned in the fixture/launcher.
+- Shared broker/reference **`ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`**,
+  source-byte verified before import.
+
+The aggregate suite has **25 tests**. The final exact-SHA CI and independent-review
+checkpoint is recorded in the draft PR. A skipped optional native test is not a
+native pass; CI supplies the pinned binary so it must execute that test.
+
+### Shared transport and factory gate
+
+The original 16 tests exercise the official native helper and strict shared
+schemas; exact session/project/worktree/lifetime/cancellation guards; reconnect
+and close-during-registration/final-epoch races; metadata/send-key recovery;
+concurrent native contexts; hostile-text provenance; inbox dedupe/FIFO blocking;
+and pre-import reference tamper/symlink refusal.
+
+One test uses an **actual local HTTP broker + BrokerClient + SQLite inbox** and
+native tool-helper execute calls. It verifies durable delivery, cooperative peek,
+reply and same-key retry. Its host lifecycle is simulated. Credentials are random
+fixture values; HTTP is only the explicit numeric-loopback development mode.
+
+### Fresh owned-run gate
+
+Eight focused tests cover fixed no-attach/no-resume/no-auto arguments, policy and
+plugin overlay preservation, unbound native proxies, exact fresh root creation,
+second-root/deletion/marker revocation, PID/starttime/boot-ID mismatch, symlink
+records, old or parented native sessions, concurrent disposal and bounded SDK
+reads that never settle.
+
+The ninth uses the **actual pinned OpenCode CLI and actual `launchOwnedRun`**:
+private child-incarnation record → native root session/chat hooks → cooperative
+list/send/receive tools → close/dispose → marker revocation. Its deterministic
+local provider receives the fixed untrusted-agent provenance inside the actual
+model-facing tool result, not just terminal output. Existing `bash: deny` policy
+is retained; an attempted fixture command does not execute. A swallowed/no-plugin
+startup followed by native exit zero is rejected for missing binding proof, with
+no automatic retry of the prompt.
+
+**Boundary:** that native test substitutes a fixture plugin constructor only to
+inject fake broker client methods. The adapter factory, shared runtime and SQLite
+are real; the default production HTTPS transport is not exercised inside that
+same native process. This gate and the separate real-broker transport gate must
+not be represented as one live end-to-end transport certification.
+
+## Reproduce in isolated local directories
+
+The repository-local installs below do not alter a global CLI or package prefix:
+
+```sh
+node --version # v24.19.0
+npm ci --ignore-scripts --no-audit --no-fund
+npm ci --prefix test/official-cli --ignore-scripts --no-audit --no-fund
+echo '538fcb1b6408c8d4608822acee19f7ff5b3a3eb3383c0633c4f06170857312a7  test/official-cli/node_modules/opencode-linux-x64/bin/opencode' | sha256sum -c -
+export BROKER_REFERENCE_DIR=/absolute/path/to/pinned/ai-agent-msg-broker
+export OPENCODE_TOOL_MODULE="$PWD/node_modules/@opencode-ai/plugin/dist/tool.js"
+export OPENCODE_BINARY="$PWD/test/official-cli/node_modules/opencode-linux-x64/bin/opencode"
+npm run check
+npm test
+```
+
+The reference checkout must include its `test/helpers.mjs` for the local HTTP
+fixture. The native test uses disposable HOME/project/config/state and a local
+file-backed model module; no real provider authentication or model call is used.
+No test paths or credentials are exposed as model tool arguments. GitHub Actions
+pins actions, helper/executable packages, the shared reference and Node, and runs
+only isolated tests—not deployment.
+
+## Still not verified or implemented
+
+Real provider credentials/native permission UI; default-plugin-to-real-HTTPS
+transport in the actual CLI; arbitrary existing plugin combinations; other
+OpenCode versions/platforms; existing TUI/server-session attachment; native
+consumption receipts; automatic input insertion/wakeup or atomic human/agent
+arbitration; per-CLI Podman containers or two-host LAN operation.
+
+`broker_receive` remains a non-consuming FIFO **peek**. A native tool return or
+model read does not advance the inbox. See [owned-run instructions](owned-run.md)
+for operator requirements and failure/unknown-outcome behavior.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@matuto-ai/opencode-broker-connector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "scripts": {
+    "test": "node scripts/test.mjs",
+    "check": "find src bin plugin examples scripts test vendor \\( -name \"*.mjs\" -o -name \"*.ts\" \\) -not -path \"*/node_modules/*\" -print0 | xargs -0 -r -n1 node --check",
+    "pack:check": "node scripts/pack-check.mjs"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@opencode-ai/plugin": "1.19.4"
+  },
+  "description": "Session-scoped Psst messaging plugin for OpenCode",
+  "main": "./plugin/index.mjs",
+  "exports": "./plugin/index.mjs",
+  "files": [
+    "plugin",
+    "src",
+    "bin",
+    "vendor/broker/reference",
+    "vendor/broker/src/protocol.mjs",
+    "vendor/broker/LICENSE",
+    "docs",
+    "LICENSE",
+    "README.md",
+    "vendor/broker/ORIGIN.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matuto-ai/opencode-broker-connector.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/index.mjs

@@ -0,0 +1,7 @@
+import { tool } from '@opencode-ai/plugin';
+import { readConfig } from '../src/config.mjs';
+import { loadBrokerReference } from '../src/reference.mjs';
+import { createNativePlugin } from '../src/native-plugin.mjs';
+export default async function PsstPlugin(native) {
+  return createNativePlugin({ native, tool, reference: await loadBrokerReference(), config: readConfig(process.env.PSST_CONFIG_FILE) });
+}

package/plugin/owned-run.ts

@@ -0,0 +1,7 @@
+import { tool } from '@opencode-ai/plugin';
+import { createOwnedHooks } from '../src/owned-run.mjs';
+
+export default async function(native) {
+  return createOwnedHooks({ native, tool, recordPath: process.env.OPENCODE_REVIEW_RUN_FILE,
+    nonce: process.env.OPENCODE_REVIEW_RUN_NONCE });
+}

package/src/config.mjs

@@ -0,0 +1,42 @@
+import { openSync, closeSync, readFileSync, fstatSync, constants, mkdirSync, lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, dirname, resolve } from 'node:path';
+const fail = () => { throw new Error('psst_configuration_invalid'); };
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+export function readConfig(path) {
+  if (typeof path !== 'string' || !isAbsolute(path)) fail();
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077 || stat.size > 16384 || process.getuid && stat.uid !== process.getuid()) fail();
+    let value = JSON.parse(readFileSync(fd, 'utf8'));
+    if (value?.format === 'broker-client-bundle-v1') {
+      const allowed = ['format', 'protocol_version', 'broker_url', 'token_file', 'file_paths_relative_to', 'authorization_header', 'authorization_scheme', 'insecure_development', 'allowed_client_types', 'scope', 'ca_file'];
+      if (Object.keys(value).some(key => !allowed.includes(key)) || value.protocol_version !== '1'
+        || value.file_paths_relative_to !== 'connection_file_directory' || value.authorization_header !== 'Authorization'
+        || value.authorization_scheme !== 'Bearer' || value.insecure_development !== false
+        || !Array.isArray(value.allowed_client_types) || value.allowed_client_types.length !== 1 || value.allowed_client_types[0] !== 'opencode'
+        || value.token_file !== 'token' || typeof value.scope !== 'string') fail();
+      const base = dirname(realpathSync(path));
+      value = { broker: { url: value.broker_url, tokenFile: resolve(base, value.token_file),
+        ...(value.ca_file ? { caFile: resolve(base, value.ca_file) } : {}) }, stateDirectory: resolve(base, 'state') };
+    }
+    if (!plain(value) || Object.keys(value).some(key => !['broker', 'stateDirectory', 'name'].includes(key))
+      || !plain(value.broker) || Object.keys(value.broker).some(key => !['url', 'tokenFile', 'caFile'].includes(key))
+      || typeof value.stateDirectory !== 'string' || !isAbsolute(value.stateDirectory)
+      || typeof value.broker.tokenFile !== 'string' || !isAbsolute(value.broker.tokenFile)
+      || value.broker.caFile !== undefined && (typeof value.broker.caFile !== 'string' || !isAbsolute(value.broker.caFile))
+      || value.name !== undefined && (typeof value.name !== 'string' || !value.name.trim() || value.name.length > 100 || /[\x00-\x1f\x7f]/.test(value.name))) fail();
+    const url = new URL(value.broker.url);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') fail();
+    return value;
+  } catch { fail(); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+export function privateDirectory(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || realpathSync(path) !== path
+    || process.getuid && stat.uid !== process.getuid()) fail();
+  return path;
+}

package/src/cooperative-inbox.mjs

@@ -0,0 +1,50 @@
+import { randomUUID } from 'node:crypto';
+import { LocalError } from '../vendor/broker/reference/errors.mjs';
+import { provenance } from '../vendor/broker/reference/runtime.mjs';
+import { validateUuid } from '../vendor/broker/src/protocol.mjs';
+
+/** Application-level explicit read ACK. Never a native injection receipt or action success. */
+export function createCooperativeInbox({ inbox, isActive = () => true }) {
+  if (!inbox?.db || typeof isActive !== 'function') throw new LocalError('invalid_configuration');
+  inbox.transaction(() => inbox.db.exec(`CREATE TABLE IF NOT EXISTS cooperative_receipts(
+    message_id TEXT PRIMARY KEY REFERENCES inbox(message_id) ON DELETE CASCADE,
+    receipt_token TEXT NOT NULL, exposed_at INTEGER NOT NULL, acknowledged_at INTEGER)`));
+  const active = () => { if (isActive() !== true) throw new LocalError('session_mismatch'); inbox.assertUsable(); };
+  return {
+    async broker_receive(args = {}) {
+      if (!args || Array.isArray(args) || typeof args !== 'object' || Object.keys(args).length) throw new LocalError('invalid_configuration');
+      active();
+      return inbox.transaction(() => {
+        const head = inbox.head();
+        if (!head) return { message: null, local_mode: 'cooperative_pull' };
+        if (head.state !== 'pending') throw new LocalError('injection_uncertain', { effect: 'unknown' });
+        let receipt = inbox.db.prepare('SELECT receipt_token FROM cooperative_receipts WHERE message_id=?').get(head.message_id);
+        if (!receipt) {
+          receipt = { receipt_token: randomUUID() };
+          inbox.db.prepare('INSERT INTO cooperative_receipts(message_id,receipt_token,exposed_at) VALUES(?,?,?)').run(head.message_id, receipt.receipt_token, inbox.now());
+        }
+        return { message_id: head.message_id, message: provenance(head.envelope), receipt_token: receipt.receipt_token,
+          local_state: 'pending', local_mode: 'cooperative_pull', native_acceptance_recorded: false,
+          acknowledgment_required: true };
+      }, { growth: 4096 });
+    },
+    async broker_acknowledge(args) {
+      if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).sort().join(',') !== 'message_id,receipt_token') throw new LocalError('invalid_configuration');
+      try { validateUuid(args.message_id); validateUuid(args.receipt_token); } catch { throw new LocalError('invalid_configuration'); }
+      active();
+      return inbox.transaction(() => {
+        const receipt = inbox.db.prepare('SELECT receipt_token,acknowledged_at FROM cooperative_receipts WHERE message_id=?').get(args.message_id);
+        if (!receipt || receipt.receipt_token !== args.receipt_token) throw new LocalError('receipt_required');
+        if (receipt.acknowledged_at == null) {
+          const head = inbox.head();
+          if (!head || head.message_id !== args.message_id || head.state !== 'pending') throw new LocalError('unsafe_boundary');
+          inbox.db.prepare('UPDATE cooperative_receipts SET acknowledged_at=? WHERE message_id=?').run(inbox.now(), args.message_id);
+          // consumed is local queue bookkeeping. Deliberately do NOT populate native_receipt.
+          inbox.db.prepare("UPDATE inbox SET state='consumed',consumed_at=? WHERE message_id=?").run(inbox.now(), args.message_id);
+        }
+        return { message_id: args.message_id, acknowledged: true, acknowledgment_kind: 'explicit_model_read',
+          native_acceptance_recorded: false, action_success: 'unknown' };
+      });
+    },
+  };
+}