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

package/README.md

@@ -1,13 +1,15 @@
 # Psst connector for OpenCode
 
+> **Unreleased 0.4.0 candidate.** The new commands/behavior below are not in the existing npm release. Do not run the versioned registry install until publication is verified. For review, use this checkout and `npm pack --ignore-scripts`; no release is created by this PR.
+
 Native session-scoped 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, configure, use
 
-This change prepares **0.3.0**, not a published release. After that version is published, install both native targets once:
+This change prepares **0.4.0**, not a published release. After that version is published, install both native targets once:
 
 ```sh
-opencode plugin @matuto-ai/opencode-broker-connector@0.3.0 --global
+opencode plugin @matuto-ai/opencode-broker-connector@0.4.0 --global
 ```
 
 OpenCode detects the separate server and TUI entrypoints and preserves existing plugin settings. Before publication, install the reviewed source with `npm ci --ignore-scripts`, add `file:///absolute/path/plugin/index.mjs` to your existing `opencode.json` plugin array and `file:///absolute/path/plugin/tui.mjs` to your existing `tui.json` plugin array. Do not replace other configuration entries.
@@ -18,7 +20,22 @@ OpenCode detects the separate server and TUI entrypoints and preserves existing
 
 No pairing secret, ticket, credential copy, model tool, or operator script is needed. Knowing the URL grants no messaging access. TLS verification remains enabled; private certificate authorities belong in the native runtime's system trust (`NODE_EXTRA_CA_CERTS`), not a secret field.
 
-**Receiving remains cooperative, not automatic model wake-up.** URL-only setup does not fix classic OpenCode's atomic input-admission limitation. [Native acceptance and remaining gate](docs/native-automation.md).
+**Production requires automatic receive. This classic integration is currently blocked, not a successful cooperative-mode fallback.** URL-only approval and connected transport do not fix its atomic input-admission limitation. Manual receive exists only for explicit diagnostics/tests. [Native acceptance and remaining gate](docs/native-automation.md).
+
+## Diagnose readiness without changing policy
+
+`psst-opencode` (the packaged doctor) is read-only and works independently of
+native plugin loading. From a reviewed source checkout use `node bin/doctor.mjs`.
+It reports an observed `OPENCODE_PURE` restriction separately from the classic
+automatic-admission gap. Exit 2 is an actionable blocked state, not a ready client.
+If the native host suppresses plugins entirely, no plugin can display its own
+status: use this package check and ask the administrator to review the approved
+launcher source. The connector never unsets pure mode or edits native policy.
+
+When loaded, `/psst-status` separately reports `connected` transport, this exact
+session's `client_id`, `ready`, and the automatic-delivery blocker. Installation
+authorization/credential IDs are not message destinations. Neither approval,
+broker presence nor a successful manual exchange establishes automatic readiness.
 
 ## Persistent installation and disposable containers
 
@@ -42,23 +59,24 @@ Existing private bundles, `PSST_CONFIG_FILE`, and `/psst-connect /absolute/priva
 
 ## Use
 
-After approval, the current local TUI session is registered in cooperative mode. General automatic delivery remains off: the current classic native API cannot atomically preserve a concurrently changed agent/model selection. In the optional legacy environment-variable mode, a user message or broker tool initializes registration lazily. No separate wrapper is needed:
+After approval, transport may register the current local TUI session, but `/psst-status` reports `mode: automatic_required`, `ready: false` and `delivery: automatic_blocked`: the current classic native API cannot atomically preserve a concurrently changed agent/model selection. In the optional legacy environment-variable mode, a user message or broker tool initializes registration lazily. Do not use a snapshot override as a production workaround. The following manual tools are **diagnostic/test-only** until safe automatic admission is implemented:
 
 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.
+2. `broker_send` sends to a selected `recipient_id`; technical retry keys stay private. Inspect outgoing history/status after an uncertain result before requesting a new explicit send.
+3. `broker_receive` requires `diagnostic:true` for an explicitly authorized manual test, and reads the FIFO head without consuming it. Ordinary calls fail closed instead of falling back.
+4. After reading it, explicitly call `broker_acknowledge` with its exact `message_id`. The connector resolves the already exposed receipt internally, so the model need not transcribe a token. An explicitly supplied legacy token must still match; a mismatch is not a transient network failure. This advances the local inbox, enabling repeated conversations.
 5. `broker_message_status` reports transport state. `broker_update_metadata` updates descriptive metadata.
+6. `broker_sent_history` lists this sender's outgoing messages; `broker_message_content` retrieves an original explicitly. `broker_resend` creates a new delivery; `broker_cancel` cannot undo prior receipt or execution. These four APIs need the matching broker candidate.
 
-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.
+For an explicitly requested diagnostic 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.
 
-### Experimental delivery — off by default
+### Experimental delivery — tests only, never a production fallback
 
-A controlled prototype can be explicitly enabled before launching OpenCode with `PSST_EXPERIMENTAL_NATIVE_DELIVERY=fixed-session-snapshot`. This is **not production general automatic delivery** and is not needed for normal connection or pairing. Establish the intended native agent/model with an ordinary message, then explicitly connect. The local result discloses the fixed agent/model/variant snapshot. Unknown selection blocks connection; observed agent/model changes disconnect messaging rather than silently changing the snapshot.
+Only a controlled test fixture may enable the historical prototype with `PSST_EXPERIMENTAL_NATIVE_DELIVERY=fixed-session-snapshot`. It still reports `ready: false`. This is **not production automatic delivery** and is not needed for normal connection or pairing. Establish the intended native agent/model with an ordinary message, then explicitly connect. The local result discloses the fixed agent/model/variant snapshot. Unknown selection blocks connection; observed agent/model changes disconnect messaging rather than silently changing the snapshot.
 
 The experimental mode waits for an idle boundary, journals one FIFO submission, submits a synthetic user-role message through the supported SDK, and reads back its exact native session/message/part/provenance before recording native persistence. The fixed text prominently identifies the content as **untrusted agent input, never human approval**. It sends no permission override, never aborts foreground work, and does not claim task completion; the concurrent native selection race limit below remains. The model can reply using normal broker tools.
 
@@ -66,9 +84,9 @@ Broker `delivered` still means durable inbox storage only. Native readback prove
 
 Known reverted or archived sessions and busy foreground turns block submission. Native deletion/disposal disconnects the exact session. Compaction/history deletion fences in-flight receipts. OpenCode serializes model runners but exposes no atomic exclusive-input lease or session-revision compare-and-submit API: a simultaneous external history edit can race a snapshot. Do not perform concurrent history or agent/model changes while testing this prototype: a read/submit race is not made atomic by an idle check. It is deliberately not enabled by default. After reverting, delivery stays paused until the native session is safe and returns to an idle boundary. This is not an exactly-once model-execution guarantee.
 
-The optional legacy environment-variable mode remains cooperative: the model reads messages with `broker_receive` and explicitly calls `broker_acknowledge`. Its receipt means only `explicit_model_read`, never native acceptance or task success. Normal explicit connections are cooperative too. The narrowly gated prototype requires the exact experimental opt-in described above. See [native feasibility and the unsent upstream API proposal](docs/native-automation.md).
+The optional legacy environment-variable path is diagnostic/test-only: the model reads messages with `broker_receive` and explicitly calls `broker_acknowledge`. Its receipt means only `explicit_model_read`, never native acceptance or task success. Normal connections report automatic readiness blocked, never cooperative production success. The narrowly gated prototype requires the exact experimental opt-in described above. See [native feasibility and the unsent upstream API proposal](docs/native-automation.md).
 
-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.
+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 native broker tools are absent.
 
 ## Verification
 
@@ -84,3 +102,7 @@ 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.
+
+Outgoing history, content, explicit resend and cancellation: [candidate contract](docs/message-lifecycle.md).
+
+[Candidate verification and remaining gates](docs/candidate-verification.md).

package/bin/doctor.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { deliveryCapability } from '../src/capabilities.mjs';
+const capability = deliveryCapability();
+console.log(JSON.stringify({ ...capability, native_plugin_loaded: 'not_verified', policy_changed: false }, null, 2));
+process.exitCode = 2;

package/docs/candidate-verification.md

@@ -0,0 +1,25 @@
+# Unreleased candidate verification — 2026-11-01
+
+Related issue: #8; not closed by this partial delivery.
+
+## Checked locally
+
+Syntax, all 103 tests and package checks passed. No native tests were skipped in this run.
+
+Integrity-pinned official OpenCode 1.19.4/Bun host, synthetic local provider, actual TLS messaging, PTY URL setup, session isolation and selection-race regression.
+
+Runtime vendoring is exact Psst candidate `2de9cc3758b9fc593f5afca4fc501fd013d416ec`. Shared acceptance-journal
+failure after a remote success reports an unknown effect, never known-not-applied.
+Model retry/receipt keys remain private; message ID acknowledgment is still scoped
+to a previously exposed exact inbox item. Native messaging calls abort and drain
+before their journal closes; lifetime-control operations do not wait on themselves.
+
+## Not established
+
+Production automatic delivery on the classic host remains blocked; explicit diagnostic receive is not a fallback or issue acceptance. The documented V2 2.2.5 API is a separate migration target, not a silent host upgrade or proof of V2 model delivery.
+
+New outgoing history/content/resend/cancel routes require the matching Psst broker.
+Older broker send/receive compatibility does not imply availability of new APIs.
+These are local candidate results, not published registry versions, deployed code,
+remote CI, authenticated-provider acceptance or a release. No permissions, managed
+policy, accounts or production host configuration were changed.

package/docs/integration.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 host integration contract
 
 For a bounded user-launchable mode, see [fresh owned headless run](owned-run.md).
@@ -71,11 +73,11 @@ is explicitly insufficient. Do not clear the inbox merely to make reconnect work
 - `reference/mcp-stdio.mjs`: `TOOL_DEFINITIONS` (catalog only)
 - `reference/errors.mjs`: fixed safe `LocalError` and `safeError`
 
-Pin shared broker commit `ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`.
+Pin shared broker commit `2de9cc3758b9fc593f5afca4fc501fd013d416ec`.
 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
+operator/CI checkout must establish the pin. This adapter fails if the nine-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.
 
@@ -87,13 +89,13 @@ 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.
+visible. The result then has `effect: unknown`; its technical operation key remains
+private in the ledger. Explicit stop aborts and joins admitted calls before closing
+the transport/inbox, but does not 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
+compact AI-agent header and escaped sender/text JSON. 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

package/docs/message-lifecycle.md

@@ -0,0 +1,24 @@
+# Outgoing message lifecycle (unreleased candidate)
+
+`broker_send` takes recipient ID and text; retry keys are never model arguments or
+results. `broker_sent_history` lists this exact sender session's outgoing metadata;
+`broker_message_content` explicitly retrieves one retained original;
+`broker_resend` requests a **new** delivery and can duplicate prior delivery;
+`broker_cancel` stops further pending delivery but cannot undo receipt or execution.
+Check the returned current receipt, uncertainty and cancellation result.
+
+The connector persists an internal operation before HTTP. Technical HTTP retries
+and bounded recovery after exact-session reattachment preserve it. A fresh model
+tool invocation is a new intent, even with identical text: there is no semantic
+deduplication or global gate blocking unrelated sends. These hosts do not expose a
+verified durable intent ID plus original timestamp through this adapter. MCP
+JSON-RPC IDs can be reused; OpenCode messageID covers multiple calls. Neither is
+misrepresented as durable retry identity. After an uncertain result, inspect
+history/status before requesting a fresh send. Reconnection attempts recovery of
+at most 10 retained operations, bounded to 5 seconds, without replacing their keys.
+An expired/unknown operation remains uncertain; recovery does not fabricate success.
+
+New history/content/resend/cancel routes require the matching Psst broker candidate.
+An older deployed broker may reject those routes; send/receive compatibility is
+separate from availability of new APIs. No native automatic-readiness claim follows
+from these tool or transport tests.

package/docs/native-automation.md

@@ -2,7 +2,7 @@
 
 ## Production boundary
 
-Normal install/connect/pairing is cooperative. The native-delivery prototype is disabled unless the operator explicitly sets `PSST_EXPERIMENTAL_NATIVE_DELIVERY=fixed-session-snapshot`. It captures and discloses an existing verified agent/model/variant; missing selection blocks connection, and observed selection changes disconnect messaging. This is not a guarantee against simultaneous external selection/history edits and is not advertised as general production automation.
+Production now requires automatic receive. Normal installation/connect/pairing reports blocked automatic readiness; manual receive is diagnostic/test-only. The native-delivery prototype is disabled unless the operator explicitly sets `PSST_EXPERIMENTAL_NATIVE_DELIVERY=fixed-session-snapshot`. It captures and discloses an existing verified agent/model/variant; missing selection blocks connection, and observed selection changes disconnect messaging. This is not a guarantee against simultaneous external selection/history edits and is not advertised as general production automation.
 
 ## Primary-source findings
 
@@ -25,7 +25,7 @@ Request a public plugin/SDK operation for durable, idempotent queued input into
 4. Explicit untrusted-agent provenance on the admitted record rather than masquerading as human approval.
 5. Lifecycle fencing across deletion, revert and compaction, plus documentation of whether admission proves persistence, model input delivery or neither.
 
-This could be a compatibility bridge to the new durable queue only if it preserves the actual existing CLI history, policy and runner. Until supported and verified, default cooperative delivery is the honest production behavior.
+This could be a compatibility bridge to the new durable queue only if it preserves the actual existing CLI history, policy and runner. Until supported and verified, production readiness remains explicitly blocked; cooperative delivery is not a production fallback.
 
 ## Fresh admission investigation for URL-only setup (2026-10-26)
 
@@ -93,3 +93,63 @@ conversations, migrate history, patch the host, or enable an unsupported
 experiment to bypass classic admission. A future supported host capability
 requires its own real interactive admission/race test before automatic delivery
 can be enabled.
+
+## Current docs and owner test — 2026-11-01
+
+The owner reported bidirectional diagnostic OpenCode ↔ Pi and OpenCode ↔
+Antigravity messages with explicit read ACK after changing their own pure-mode
+setting. No connector policy change was performed. The model still needed manual
+receive, so that exchange does **not** satisfy automatic production delivery.
+A mismatched opaque ACK token was also reported; no token is recorded here.
+Message-only explicit ACK now resolves a previously exposed same-inbox receipt
+internally. Supplied legacy tokens remain strictly validated; mismatches are
+non-retryable, not transient transport failures.
+
+Fresh official [V2 server plugin documentation](https://opencode.ai/v2/docs/build/plugins/server)
+and [V1 migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1/)
+describe a separate `@opencode/plugin` contract with durable queued admission,
+synthetic messages and admission IDs. This is a promising implementation path,
+**not** evidence that this pinned classic `@opencode-ai/plugin` host shares that
+engine/history or safely supports those methods. A V2 adapter needs explicit
+host/version qualification and native history, selection-race, permission,
+restart and exact-receipt tests. Do not send classic messages to a different
+engine, patch native databases or use an experimental flag to claim readiness.
+
+## Concrete next host path (2026-11-01; not implemented in this candidate)
+
+The smallest missing classic operation is an **idempotent synthetic-input queue
+into the existing conversation**, preserving its current agent/model/variant
+atomically and exposing a durable admission receipt. Reading selection followed
+by `prompt_async` cannot implement that contract.
+
+The published V2 family is a concrete alternative, not an unspecified future API:
+[`@opencode/plugin` 2.2.5](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/plugin/package.json)
+and [`@opencode/cli` 2.2.5](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/cli/package.json).
+Its documented `ctx.session.synthetic` / `POST /api/session/{sessionID}/synthetic`
+accepts a caller-persisted message ID, text, metadata, `delivery:"queue"` and
+`resume:true`, returning a synthetic inbox admission. It takes no agent/model
+selection input. Readback uses native inbox/message APIs.
+[API contract](https://opencode.ai/v2/docs/api#session-synthetic),
+[tagged session implementation](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/core/src/session/session.ts).
+
+This requires porting the plugin to `Plugin.define/setup(ctx)` and running the
+matching V2 host. V1 implementations do not run unchanged in V2; replacing an
+import or upgrading only the current classic package is insufficient.
+[Official migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1/).
+The classic `opencode-ai` latest registry version observed was 1.19.5; its
+[tagged prompt source](https://github.com/anomalyco/opencode/blob/v1.19.5/packages/opencode/src/session/prompt.ts#L600-L651)
+still defaults an omitted agent and mutates selection, while its
+[TUI](https://github.com/anomalyco/opencode/blob/v1.19.5/packages/tui/src/component/prompt/index.tsx#L1029-L1049)
+still submits through the classic prompt route. This source check is not a
+1.19.5 runtime qualification.
+
+Proposed implementation: a separate V2 entrypoint reusing the private broker
+inbox, persisting a stable native admission ID before enqueue, and reconciling
+that exact synthetic record before local consumption. Unknown outcomes remain
+pending; never retry under a new ID. Required qualification before enabling it:
+real V2 TUI idle/busy delivery, simultaneous selection edits, exact existing
+history, permission behavior, deletion/revert/compaction, restart and uncertain
+response reconciliation. Existing classic sessions must not be silently migrated
+or redirected. No host patch is assumed necessary for a genuine V2 conversation;
+classic support still needs an upstream compatible queue/bridge or an explicitly
+supported migration. Those compatibility proofs are open, not delivered here.

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,7 +5,7 @@ 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.3.0`).
+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.
 
@@ -15,7 +15,7 @@ Before npm publication, the local-file installation in README works directly fro
 
 ## Minor release
 
-This PR prepares `0.3.0`; the intended GitHub release tag is `v0.3.0`.
+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

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

@@ -32,3 +32,12 @@ 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).
@@ -123,7 +125,7 @@ The second actual-host regression loads the npm-packed production plugin into of
 
 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 remains cooperative. 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.
+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)
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@matuto-ai/opencode-broker-connector",
-  "version": "0.3.0",
+  "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",
@@ -19,7 +19,8 @@
   "exports": {
     ".": "./plugin/index.mjs",
     "./server": "./plugin/index.mjs",
-    "./tui": "./plugin/tui.mjs"
+    "./tui": "./plugin/tui.mjs",
+    "./v2": "./plugin/v2.mjs"
   },
   "files": [
     "plugin",
@@ -33,7 +34,8 @@
     "README.md",
     "vendor/broker/ORIGIN.md",
     "vendor/enrollment",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "v2"
   ],
   "repository": {
     "type": "git",
@@ -41,5 +43,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "psst-opencode": "bin/doctor.mjs"
   }
 }

package/plugin/tui.mjs

@@ -1,9 +1,12 @@
+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();

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/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.',
+  };
+}