@matuto-ai/opencode-broker-connector 0.1.1 → 0.4.0

package/docs/native-v2.md

@@ -0,0 +1,121 @@
+# Native OpenCode V2 candidate (2.2.5 only)
+
+This is an **isolated candidate**, not an upgrade/migration of classic OpenCode
+1.19.x, a release, or a claim that classic automatic delivery is fixed. The
+existing default export and classic capability guard are unchanged.
+
+## Native package installation
+
+On an already installed **OpenCode V2 2.2.5**, install the server-only candidate
+with the native plugin manager (the official CLI package names its executable
+`opencode2`):
+
+```sh
+opencode2 plugin add 'github:matuto-ai/opencode-broker-connector#feat/v2-native-automatic::path:v2'
+```
+
+The candidate branch can change; use the full published commit from the PR
+handoff instead of `feat/v2-native-automatic` when pinning the installer itself.
+OpenCode 2.2.5 supports full-commit Git `::path:` package selectors. Its plugin
+manager persists installation; no hand-written host config or connection file is
+needed. This command installs only the plugin, not OpenCode or a model provider.
+
+The nested package is self-contained: it declares the exact public runtime
+`81bab6924d0f7193b8b3f32318ea4cbc1d23a17f` as its dependency and imports that
+package's explicit `./v2` export. It does not reach outside its package, load the
+classic root export/TUI, or create a dependency cycle. The runtime SHA includes
+all reviewed delivery, cancellation, approval-lifetime and archived-owner fixes.
+No release or host upgrade is implied by installing this draft candidate.
+
+After installation, ask the native agent to use `broker_setup` with only
+`broker_url: "https://your-broker.example"`. It returns the exact public request ID
+and broker admin URL. Human admin approval remains required; the plugin polls the
+same durable request with GET-only continuation and connects automatically after
+approval. `broker_setup_status` is read-only; `broker_cancel_setup` pauses only the
+local pending flow. Startup never creates enrollment requests. No token or private
+file handoff is required. Existing approved installation selection is reused.
+
+An explicit private `connectionFile` option or `PSST_CONFIG_FILE` override remains
+available for compatibility/fixtures; it disables URL setup to avoid secretly
+switching an explicitly configured connection. It does not rewrite host config, change permissions, select
+an agent/model, install/upgrade OpenCode, or migrate classic sessions. The `./v2`
+JavaScript export is also available. A local development `plugins` entry must be
+a **directory**, not a single file; normal installation uses the command above. New native root sessions connect automatically;
+known exact session bindings restore after plugin reload. Subagents do not share
+the root's inbox.
+
+**Evidence boundary:** isolated package installation resolves the pinned public
+runtime and imports the native plugin with no repository sibling files, without
+executing lifecycle scripts. Exact 2.2.5 source tests cover full-SHA Git subdirectory
+installation with dependencies. The earlier real-host fixture loaded the same
+runtime through local-directory configuration. The new plugin-manager command
+has **not yet been executed against the owner's installed V2 host** because that
+sandbox is not accessible from this executor. Do not equate dependency-resolution
+proof with a fresh native-host or authenticated-model acceptance test.
+
+## Delivery and recovery contract
+
+- Public V2 APIs only: `session.get`, `synthetic`, `context`, session prompt hook,
+  event subscription, storage, tool transform. Host version is explicitly gated.
+- Stable private binding: server plugin-storage anchor, native session ID,
+  creation time, project, location/workspace, broker installation; exclusive
+  SQLite ownership; persisted random broker identity. Partial/foreign state is
+  never automatically discarded, migrated or taken over.
+- Compact sender/message envelope; native `synthetic` role and machine-source
+  metadata. No human prompt, repeated policy paragraph, visible authority field,
+  current agent/model override, user draft edit or steering injection.
+- Commit exact payload, native ID and local injection ID before the single
+  `synthetic({delivery:"queue",resume:true})` call. Require exact native session,
+  ID, type, delivery and payload, not merely HTTP success.
+- A receipt proves **durable native admission**, not model reading, task success,
+  or authorization. At most one pending native item; the next waits for exact
+  prior promotion in native context.
+- Native cancellation removes the host's pending idempotency lookup entry.
+  Therefore **no automatic synthetic retry**, even with the same ID. Lost
+  responses reconcile read-only against exact promoted synthetic context.
+  Pending-but-unproven, cancelled, compacted-away or mismatched receipts remain
+  pinned/blocked, never guessed, deleted or reinjected.
+- Interrupted/failed host sessions and cancel/revert events pause delivery.
+  Only subsequent native execution can reopen the event pause. Session move,
+  archive, delete or plugin unload fences the owner. Unload is resumable and does
+  not terminally close a surviving broker identity; native disappearance is not
+  treated as permission to silently allocate a replacement. A queued item cancelled by
+  the user is not recreated.
+- No cooperative receive/ack tools are registered in V2. The eight outgoing/
+  status/metadata lifecycle tools use the shared reviewed SDK. Native tool-call
+  identity scopes private durable send/retry keys. Send/resend additionally require
+  the actual matching native assistant tool block creation time, so an aged replay
+  cannot mint a new operation after journal GC. Missing/compacted proof fails closed.
+
+## Verification
+
+```sh
+node --test test/v2-delivery.test.mjs test/v2-plugin.test.mjs test/v2-setup.test.mjs
+OPENCODE_V2_BINARY=/path/to/official/opencode2 node --test test/v2-host.test.mjs
+# Optional native installer proof: existing CLI, disposable HOME/XDG only.
+OPENCODE_V2_BINARY=/path/to/official/opencode2 \
+PSST_V2_PACKAGE_SPEC='github:matuto-ai/opencode-broker-connector#FULL_COMMIT::path:v2' \
+node --test test/v2-installer.test.mjs
+npm test
+npm run check
+npm run pack:check
+```
+
+The real-host test packs/extracts the candidate, loads its nested V2 directory
+through the native plugin manager in an isolated HOME/XDG tree with random local
+HTTP Basic credentials, connects a real local TLS broker, sends a real envelope,
+and verifies automatic native synthetic admission and Plan→Build preservation.
+With `PSST_APPROVAL_BROKER_DIR` pointing to the approval-enabled broker checkout,
+a second real-host test invokes the registered native setup executor through a
+fixture command/public tool API, approves the real TLS request in the disposable
+admin fixture, and verifies automatic connection/delivery. This is actual native
+plugin/tool integration, not a model-issued tool-call proof.
+The selected fixture provider deliberately does not exist: **no user credentials,
+model API or authenticated LLM response is used or proved**. Unit mocks separately
+exercise uncertain writes, exact receipts, cancellation, restart, owner isolation,
+selection changes, FIFO bounds and stalled requests.
+
+Official contracts: [plugin loading](https://opencode.ai/v2/docs/plugins/),
+[server plugins](https://opencode.ai/v2/docs/build/plugins/server),
+[native synthetic admission](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/core/src/session/session.ts#L280-L320),
+[pending/reconciliation semantics](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/core/src/session/inbox.ts).

package/docs/owned-run.md

@@ -1,13 +1,15 @@
+> Candidate update: production requires automatic delivery and is currently blocked on the classic host. Manual pull/owned-run flows below are diagnostic/test-only. See [current lifecycle contract](message-lifecycle.md) for hidden operation keys and new APIs. Historical fixture pins are separate from the runtime candidate.
+
 # 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.
+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 nine diagnostic 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.
+- A local broker reference checkout at **`2de9cc3758b9fc593f5afca4fc501fd013d416ec`**. 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.

package/docs/publishing.md

@@ -5,21 +5,21 @@ Package name: `@matuto-ai/opencode-broker-connector`. The npm workflow follows t
 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 (next `v0.1.1`).
+4. Create a GitHub release whose tag exactly matches `v` + package.json version (next `v0.4.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.
+Before npm publication, the local-file installation in README works directly from `main` after the release PR is reviewed and merged. No unpublished dependency is required.
 
-## Patch release
+## Minor release
 
-This PR prepares `0.1.1`; the intended GitHub release tag is `v0.1.1`.
+This PR prepares `0.4.0`; the intended GitHub release tag is `v0.4.0`.
 After review and merge, the maintainer can publish that release from the merged
 commit to exercise npm Trusted Publishing. This code change does not itself
 create a tag, release, or npm publication. Verify the workflow succeeds and the
 scoped npm version exists before recommending it for installation.
 
-Existing `0.1.0` npm packages and old GitHub tags remain untouched. Do not reuse
+Existing `0.1.x` npm packages and old GitHub tags remain untouched. Do not reuse
 or move an old release tag; the new tag must exactly match the package version.

package/docs/reference-snapshot.sha256

@@ -1,10 +1,10 @@
-93f75786eab29429ace024974e0f61d6ad46d2c5fe065dae387e54fd2373b167  reference/inbox.mjs
-f661b45acba106be03d97dacba3cd90ac18b09e7ff9eb93b995d5036d9d1c785  reference/client.mjs
+fbf0fa6096996cb9bc3f928e55f3eca496420880a03460e993dda3417b32ad88  reference/inbox.mjs
+c4c313e937d1003f28928a672072b926022aa0e9fd65825bc5db1078eb90afa9  reference/client.mjs
 8733076b73a42ab8f12fe20ba9908acdd754d89734ffd335e84b49aee9d737ca  reference/runtime.mjs
-5e6355cef1bec56170dca14b93142a7da8c102f411c5dbf437d84acda7351acf  reference/tools.mjs
-10a93788af426ce898c398e38dd41ac77b6e0129a7697bdc36c8d4f6d6e20138  reference/mcp-stdio.mjs
+5d3b16212a048912395d74b95a8b590d278b8b0915bb0bd7a0c3d80daf353839  reference/tools.mjs
+f34b0cdcda9c2d607815e4ef99f1ba80fbd8936ef8c2893a858b6d408bc0ff09  reference/mcp-stdio.mjs
 e33231d94f514b5a1b59fdd4184f5881dd3712bde725a1cf53352c26293452ac  reference/errors.mjs
-f3ff24b4429dddc8a9c10513ab72dbc613c91244591132458c7866a812d6316b  src/protocol.mjs
+2d88829971643d47430d6696d0a6ac61589ea4f9001c860c5c196ecc5ac21a6f  src/protocol.mjs
 575ac7406ed9b8698d97ecdc2f093a99455fdd581f375c4611c844d4618095c8  src/store.mjs
 69d5130ce90e045d0cd66facdc4380ef03f50895c53997fe9a664814fcca0e7b  src/server.mjs
 8d85ecd3c02142de87de34425b71daa35b7317bbe3cfd19865c43e7bb57e3785  src/auth.mjs

package/docs/sandbox-persistence.md

@@ -0,0 +1,43 @@
+# Sandbox bootstrap contract
+
+Historical source inspected: `ai-agents-sandbox` snapshot
+`a7f63e8b98d37c030df6ca095d2e75960111e37c`,
+`agents/opencode-native/config.sh:get_project_mounts/get_project_env`.
+This is design evidence, **not verification of current live mounts**.
+
+The existing launcher maps `<project>/opencode-zen/{config,data,cache,state}`
+(or the separate `opencode-go` profile) to:
+
+| Leaf | Container path |
+| --- | --- |
+| config | `/home/node/.config/opencode` |
+| data | `/home/node/.local/share/opencode` |
+| cache | `/home/node/.cache/opencode` |
+| state | `/home/node/.local/state/opencode` |
+
+Use `PSST_OPENCODE_CONFIG_DIR=/home/node/.config/opencode/psst` in that bootstrap
+so the whole installation uses the **existing config mount**, including Go's
+managed `XDG_CONFIG_HOME=/etc` override. The `psst` subdirectory must be owned by
+the sandbox user, mode 0700; config/key files are 0600. Recreated containers must
+mount it at the same absolute path. Different project/profile mounts intentionally
+remain separate authorizations unless bootstrap explicitly shares this private
+installation directory. Sharing it never means sharing native session IDs/inboxes.
+Do not mount the ephemeral `/tmp/psst-opencode-<uid>` directory across containers.
+
+The archived launcher also sets `OPENCODE_PURE=1` and disables project config.
+Official 1.19.4 explicitly skips external TUI plugins in pure mode. Therefore
+that historical bootstrap needs an intentional native plugin allowlist/install
+integration before this connector can load; merely saving files cannot override
+that policy. Preserve managed model/provider, permission and credential policy.
+This connector does not remove pure mode or edit the sandbox launcher itself.
+The current owner environment remains an acceptance gate until its effective
+bootstrap is inspected and the intended plugin installation is permitted.
+
+## Read-only capability diagnosis
+
+The packaged `psst-opencode` doctor reports `OPENCODE_PURE` only as observed in
+its own process environment; it never disables it or claims to inspect every
+managed source. A host that skips the plugin cannot run the plugin's diagnostic
+hook. Ask the administrator to review the actual approved launcher source.
+Even with plugins enabled, the pinned classic host remains `automatic_blocked`;
+transport presence/manual receive must not be reported as production readiness.

package/docs/verification.md

@@ -1,3 +1,5 @@
+> Candidate update: production requires automatic delivery and is currently blocked on the classic host. Manual pull/owned-run flows below are diagnostic/test-only. See [current lifecycle contract](message-lifecycle.md) for hidden operation keys and new APIs. Historical fixture pins are separate from the runtime candidate.
+
 # 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).
@@ -110,3 +112,63 @@ 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.
+
+## Explicit connection regression coverage
+
+The packed production plugin is loaded by official OpenCode 1.19.4 with no `PSST_CONFIG_FILE`. A native session command connects using a private file, discovery sees the exact new session, and native disconnect prevents subsequent message injection while the host remains available. The fixture uses a deterministic local model provider and a trusted loopback TLS broker; no paid provider, user credential, desktop/TUI automation, or production installation is exercised. Unit tests cover disconnected startup, session-isolated status, disconnect/no re-registration, and deleted-session fencing. Automatic model delivery and pairing issuance are separate changes, not claims of this connection-only step.
+
+## Experimental native delivery (explicit opt-in only)
+
+The second actual-host regression loads the npm-packed production plugin into official OpenCode 1.19.4/Bun, connects with no startup broker environment, sends two FIFO messages through verified TLS, with the fixed-session-snapshot experimental opt-in, preserves Plan mode and the selected model, and observes both exact synthetic native messages and the second payload in the deterministic local model's input. It never calls `broker_receive`, never accesses paid providers, and verifies disconnect prevents later injection. This proves real native integration, not a desktop/TUI end-to-end installation or production-broker test. Unit regressions cover missing/wrong readback, single in-flight FIFO, busy/reverted/human boundaries, compaction during submit, abort during receipt lookup, lost submit responses, delayed readback reconciliation and same-session journal reopen without another native submission. Native source basis: `packages/opencode/src/session/prompt.ts`, `effect/runner.ts`, and `server/routes/instance/httpapi/handlers/session.ts` at official tag v1.19.4.
+
+## Scoped pairing boundary
+
+A further actual OpenCode smoke loads the packed plugin, passes only a private pairing-file path to the native command, and exercises the unmodified shared enrollment helper over system-trusted HTTPS. A synthetic endpoint implementing the frozen broker contract records a hash-only credential and authorizes it in the real transport fixture; automatic peer messages then reach the deterministic local model. This checks native/helper/credential integration, not the production broker's operator issuance implementation (covered by upstream broker tests). Unit tests additionally cover marked bundle receipt deletion/type/origin/token mismatches, private permissions, per-native-session attempt separation, expiry shutdown, revoked authorization shutdown and no late connect after disconnect.
+
+The default connector reports automatic readiness blocked; manual receive requires an explicit diagnostic request. Additional pinned-host coverage proves that the official v2 session identity is visible while its context/history remain empty for a classic CLI conversation with real messages. The connector does not mix these engines. Unknown agent/model state blocks the experiment and observed changes disconnect it. No test establishes atomic admission against simultaneous external native selection edits.
+
+## URL-only approval and persistent native configuration (0.3.0 candidate)
+
+The new gates use official **OpenCode 1.19.4**, not a mocked host API:
+
+- `native-tui.test.mjs`: loads the production TUI entrypoint and sends real PTY
+  keyboard input through the supported Ctrl+Alt+P setup binding. Invalid URLs
+  remain unselected; the single-field URL form durably saves its request before
+  attempted HTTPS transport. This is a disposable test terminal, not a user's TUI.
+- `native-tui-approval.test.mjs`: loads the production TUI and server entrypoints;
+  a transparent fixture creates/navigates to an empty existing classic session
+  using the supported SDK. Real keyboard setup requests actual broker enrollment;
+  authenticated admin form/CSRF approval commits config; the private native-context
+  hint connects that already-idle session. Its native message history remains
+  empty, proving setup/attachment did not manufacture a model turn.
+- `native-approval-integration.test.mjs`: real broker approval, 30 distinct native
+  sessions in the packed production plugin, process restart with unchanged
+  installation authorization and new session addresses, then real admin revocation.
+- `native-installation.test.mjs`: preserves legacy installation compatibility
+  across the same native 30-session/restart path.
+- `installation.test.mjs`, `setup-ui.test.mjs`, and `native-context.test.mjs` cover
+  selection CAS, cancellation/late results, exact request binding, replacement,
+  transient backoff, GET-only startup resume, terminal denial/revocation/expiry,
+  corrupt/private files, distinct container runtime roots, stale incarnation/owner
+  hints and route changes. These unit fixtures are not real container orchestration.
+
+CI checks out the immutable broker dependency specified in `.github/workflows/ci.yml`
+and supplies `PSST_APPROVAL_BROKER_DIR`; without it the real-broker native gates
+explicitly skip. Locally point that variable at that exact reviewed broker tree.
+No provider credentials, live broker, real user installation or release is used.
+The helper hash/source anchor is recorded in `vendor/enrollment/ORIGIN.md`.
+
+**Not established by these gates:** paid/authenticated model provider behavior,
+classic atomic automatic model receive (the fresh native regression demonstrates
+why it is unsafe), or unchanged historical sandbox pure-mode policy permitting
+plugins. Native process recreation is not itself Docker/Podman mount evidence;
+real orchestration gates are reported separately rather than inferred from unit
+fixtures. See `docs/sandbox-persistence.md` for the exact audited bootstrap boundary.
+
+The separate `native-containers` CI matrix runs the approved 30-session/revocation
+native test with each official OpenCode server inside a fresh Docker or rootless
+Podman container, using the pinned Node image and integrity-checked official CLI.
+On recreation the test uses a new HOME/data/cache/state; only the private selected
+installation plus read-only installed code/bootstrap fixtures remain available.
+The runtime `/tmp` hints are not mounted. A submitted workflow is not a pass:
+the exact PR head's Docker and Podman jobs are the authoritative execution evidence.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@matuto-ai/opencode-broker-connector",
-  "version": "0.1.1",
+  "version": "0.4.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",
+    "check": "find src bin plugin v2 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",
@@ -16,7 +16,12 @@
   },
   "description": "Session-scoped Psst messaging plugin for OpenCode",
   "main": "./plugin/index.mjs",
-  "exports": "./plugin/index.mjs",
+  "exports": {
+    ".": "./plugin/index.mjs",
+    "./server": "./plugin/index.mjs",
+    "./tui": "./plugin/tui.mjs",
+    "./v2": "./plugin/v2.mjs"
+  },
   "files": [
     "plugin",
     "src",
@@ -27,7 +32,10 @@
     "docs",
     "LICENSE",
     "README.md",
-    "vendor/broker/ORIGIN.md"
+    "vendor/broker/ORIGIN.md",
+    "vendor/enrollment",
+    "CHANGELOG.md",
+    "v2"
   ],
   "repository": {
     "type": "git",
@@ -35,5 +43,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "psst-opencode": "bin/doctor.mjs"
   }
 }

package/plugin/index.mjs

@@ -1,7 +1,19 @@
 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';
+import { createConnectionLoader, readExistingConnection } from '../src/enrollment.mjs';
+import { readInstallation } from '../src/installation.mjs';
+import { startPendingResume } from '../src/pending-resume.mjs';
+import { createContextReceiver } from '../src/native-context.mjs';
 export default async function PsstPlugin(native) {
-  return createNativePlugin({ native, tool, reference: await loadBrokerReference(), config: readConfig(process.env.PSST_CONFIG_FILE) });
+  const reference = await loadBrokerReference();
+  const config = process.env.PSST_CONFIG_FILE ? await readExistingConnection(process.env.PSST_CONFIG_FILE) : undefined;
+  const contextReceiver = createContextReceiver({ directory: native.directory });
+  const resume = startPendingResume();
+  try {
+    return await createNativePlugin({ native, tool, reference, config, contextReceiver,
+      connectFile: createConnectionLoader({ directory: native.directory }),
+      loadInstallation: readInstallation, onDispose: resume.stop,
+      experimentalNativeDelivery: process.env.PSST_EXPERIMENTAL_NATIVE_DELIVERY === 'fixed-session-snapshot' });
+  } catch (error) { resume.stop(); contextReceiver.close(); throw error; }
 }

package/plugin/tui.mjs

@@ -0,0 +1,17 @@
+import { deliveryCapability } from '../src/capabilities.mjs';
+import { installSetupUI } from '../src/setup-ui.mjs';
+import { readSelection, readPending } from '../src/installation.mjs';
+import { startContextPublisher } from '../src/native-context.mjs';
+export default { id: 'matuto.psst', tui: async api => {
+  startContextPublisher(api);
+  await installSetupUI(api);
+  const capability = deliveryCapability();
+  api.ui.toast({ title: 'Psst: automatic delivery blocked', variant: 'warning', duration: 10000, message: capability.next_action });
+  try {
+    if (!process.env.PSST_CONFIG_FILE && !readSelection()) {
+      const pending = readPending();
+      api.ui.toast({ title: 'Psst', variant: 'info', duration: 6000,
+        message: pending && !pending.paused ? 'Approval pending. Your saved request resumes without new enrollment.' : 'Setup needed: press Ctrl+Alt+P and enter the broker URL.' });
+    }
+  } catch { api.ui.toast({ title: 'Psst', variant: 'warning', message: 'Private configuration is invalid; no enrollment or credential reset was attempted.', duration: 6000 }); }
+} };

package/plugin/v2.mjs

@@ -0,0 +1,18 @@
+import { tool } from '@opencode-ai/plugin';
+import { loadBrokerReference } from '../src/reference.mjs';
+import { readExistingConnection } from '../src/enrollment.mjs';
+import { readInstallation } from '../src/installation.mjs';
+import { setupV2Plugin } from '../src/v2-plugin.mjs';
+
+// Structurally the public @opencode/plugin Plugin.define({ id, setup }) contract.
+// define is identity-only; no V2 host, runtime or CLI is installed by this package.
+export default {
+  id: 'matuto.psst.v2',
+  async setup(ctx) {
+    const reference = await loadBrokerReference();
+    const connectionFile = ctx.options?.connectionFile ?? process.env.PSST_CONFIG_FILE;
+    const runtime = await setupV2Plugin({ ctx, reference, tool, setupEnabled: !connectionFile,
+      loadSettings: () => connectionFile ? readExistingConnection(connectionFile) : readInstallation() });
+    return runtime.dispose;
+  },
+};

package/src/approval-helper.mjs

@@ -0,0 +1,11 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const APPROVAL_SHA256 = 'a60c3a0ccd7deb50556586cd67841bb89a300ea3c7f1af3a91d437f856b7a2d5';
+export async function loadApprovalHelper() {
+  const path = fileURLToPath(new URL('../vendor/enrollment/approval.mjs', import.meta.url));
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536
+    || createHash('sha256').update(readFileSync(path)).digest('hex') !== APPROVAL_SHA256) throw new Error('approval_snapshot_mismatch');
+  return import('../vendor/enrollment/approval.mjs');
+}

package/src/capabilities.mjs

@@ -0,0 +1,13 @@
+/** Capability statements are not broker presence and never change host policy. */
+export function deliveryCapability(env = process.env, { experimental = false } = {}) {
+  const pure = ['1', 'true'].includes(String(env.OPENCODE_PURE).toLowerCase());
+  return {
+    mode: 'automatic_required', ready: false,
+    delivery: experimental ? 'experimental_test_only' : 'automatic_blocked',
+    automatic_receive: false,
+    blocker: pure ? 'opencode_pure_mode' : 'classic_atomic_admission_unavailable',
+    next_action: pure
+      ? 'OPENCODE_PURE is enabled in this process. Ask the sandbox administrator to review the approved launcher source; the connector does not disable policy. No loaded plugin can diagnose itself when the host skips it entirely.'
+      : 'This classic OpenCode integration lacks safe automatic admission preserving the current agent/model and conversation. Transport may connect, but production messaging is not ready. Manual receive is diagnostic/test-only; do not enable a snapshot override as a fix.',
+  };
+}

package/src/config.mjs

@@ -4,19 +4,21 @@ 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;
+  let fd, marked = false;
   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'];
+      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', 'enrollment_receipt_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.enrollment_receipt_file !== undefined && value.enrollment_receipt_file !== 'enrollment.json'
         || value.token_file !== 'token' || typeof value.scope !== 'string') fail();
+      marked = value.enrollment_receipt_file === 'enrollment.json';
       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') };
@@ -29,6 +31,7 @@ export function readConfig(path) {
       || 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();
+    if (marked) Object.defineProperty(value, 'enrollmentReceiptRequired', { value: true });
     return value;
   } catch { fail(); }
   finally { if (fd !== undefined) closeSync(fd); }

package/src/cooperative-inbox.mjs

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { LocalError } from '../vendor/broker/reference/errors.mjs';
-import { provenance } from '../vendor/broker/reference/runtime.mjs';
+import { nativeMessage } from './message-format.mjs';
 import { validateUuid } from '../vendor/broker/src/protocol.mjs';
 
 /** Application-level explicit read ACK. Never a native injection receipt or action success. */
@@ -12,29 +12,34 @@ export function createCooperativeInbox({ inbox, isActive = () => true }) {
   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');
+      if (!args || Array.isArray(args) || typeof args !== 'object' || Object.keys(args).some(key => key !== 'diagnostic')) throw new LocalError('invalid_configuration');
+      if (args.diagnostic !== true) { const error = new LocalError('unsafe_boundary', {field:'automatic_delivery_required'}); error.message = 'Automatic delivery is required. Manual receive is available only for an explicitly requested diagnostic test with diagnostic:true; nothing was consumed.'; throw error; }
       active();
       return inbox.transaction(() => {
         const head = inbox.head();
-        if (!head) return { message: null, local_mode: 'cooperative_pull' };
+        if (!head) return { message: null, local_mode: 'diagnostic_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,
+        return { message_id: head.message_id, message: nativeMessage(head.envelope),
+          local_state: 'pending', local_mode: 'diagnostic_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'); }
+      if (!args || typeof args !== 'object' || Array.isArray(args) || !['message_id','message_id,receipt_token'].includes(Object.keys(args).sort().join(','))) throw new LocalError('invalid_configuration');
+      try { validateUuid(args.message_id); if (args.receipt_token !== undefined) 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 || args.receipt_token !== undefined && receipt.receipt_token !== args.receipt_token) {
+          const error = new LocalError('receipt_required', {field: receipt ? 'receipt_token' : 'message_id'});
+          error.message = receipt ? 'The supplied legacy read receipt does not match. Nothing was acknowledged; this is not a transient network error. Omit the token and use the exact previously read message_id.' : 'Read this exact message in this inbox before acknowledging it. Nothing was acknowledged; this is not a transient network error.';
+          throw error;
+        }
         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');

package/src/enrollment.mjs

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readConfig } from './config.mjs';
+
+export const ENROLLMENT_SHA256 = 'afeab00d7c2d6768d3537bd7c350e249768897bf81eff9b4ae9796f7c3f9dbe9';
+async function helper() {
+  const path = fileURLToPath(new URL('../vendor/enrollment/enrollment.mjs', import.meta.url));
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536
+    || createHash('sha256').update(readFileSync(path)).digest('hex') !== ENROLLMENT_SHA256) throw new Error('enrollment_snapshot_mismatch');
+  return import('../vendor/enrollment/enrollment.mjs');
+}
+
+/** Legacy environment mode may load an existing bundle, never issue credentials. */
+export async function readExistingConnection(path) {
+  const settings = readConfig(path);
+  if (settings.enrollmentReceiptRequired) {
+    settings.enrollment = (await helper()).readEnrollmentReceipt({ connectionFile: path, clientType: 'opencode' });
+  }
+  return settings;
+}
+
+/** Only the native explicit-connect command calls this. No model tool accepts a secret. */
+export function createConnectionLoader({ directory, stateHome = process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state'),
+  loadHelper = helper } = {}) {
+  if (!isAbsolute(directory) || !isAbsolute(stateHome)) throw new Error('private_directory_required');
+  return async function connectFile(path, { clientType, sessionID }) {
+    if (clientType !== 'opencode' || typeof path !== 'string' || !isAbsolute(path)
+      || /[\x00-\x1f\x7f]/.test(path) || typeof sessionID !== 'string' || !sessionID) throw new Error('private_file_required');
+    let settings;
+    try { settings = readConfig(path); } catch { /* The shared helper independently validates pairing files. */ }
+    if (settings) {
+      // The explicit bundle marker makes missing/corrupt receipts fatal.
+      if (settings.enrollmentReceiptRequired) {
+        const api = await loadHelper();
+        settings.enrollment = api.readEnrollmentReceipt({ connectionFile: path, clientType });
+      }
+    } else {
+      const api = await loadHelper();
+      const key = createHash('sha256').update(JSON.stringify([resolve(directory), sessionID])).digest('hex');
+      const result = await api.connectPairingFile({ pairingFile: path,
+        directory: join(stateHome, 'psst', 'opencode', key), clientType });
+      settings = readConfig(result.connectionFile);
+      settings.enrollment = api.readEnrollmentReceipt({ connectionFile: result.connectionFile, clientType });
+    }
+    if (settings.enrollment && Date.parse(settings.enrollment.expiresAt) <= Date.now()) throw new Error('credential_expired');
+    return settings;
+  };
+}