@matuto-ai/opencode-psst-connector 0.0.0-stage → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.7.0 — unreleased source candidate
+
+Publish the connector under `@matuto-ai/opencode-psst-connector` and rename the GitHub repository to `opencode-psst-connector`. Preserve native identity, saved installation credentials, journals and tool names. The old npm package remains available; migration requires an explicit package-source change. See [migration checklist](docs/migration-0.6.0.md).
+
+### Included source changes
+
+- Add explicit native `/psst-reauthorize`, configured-origin reuse and exact-request/selection confirmation; replacement does not revoke the old credential.
+- Preserve setup candidates across focus interruptions, reconcile durable outcomes, and isolate unrelated chats without requiring them to close.
+
+- Add native URL-only setup/status/cancel dialogs, exact-request replacement confirmation, durable owner/status recovery and cancellation/CAS fencing.
+- Attach approved replacement before selecting it while retaining the previous working authorization and private journals; preserve strict identity recovery for expired authorization so setup can repair it.
+- Permit conclusively fresh native hosts to share installation authorization without adopting another mailbox; verify 30 same-name sessions and pinned previous-source upgrade.
+- Expand official-host acceptance with native restart, unread delivery, independent sessions, pending replacement and native input/permission preservation. Authenticated model qualification remains explicit and separate.
+
+- Limit receive and heartbeat to selected local TUI conversations, resuming the same identity without closing inactive sessions.
+- Add exact native model and bounded configured project metadata; keep immutable retry payloads.
+- Add explicit registration-v2 opt-in and confirmed-expiry incarnation recovery; preserve old journals and block uncertain storage. Broker retention remains a separate opt-in.
+
+- Standardize new native notices as `Psst · new message · From: <name> · <type> · <preview>` in English; keep IDs and correlation out of the UI preview without changing full payloads or existing persisted notices.
+
+## 0.5.1 (unreleased)
+
+- Make new native history notices show a bounded literal message preview and external-agent sender label, rather than only “Psst agent message”.
+- Preserve full message bodies, machine provenance, receipt semantics and all existing persisted payloads byte-for-byte.
+
+## 0.5.0
+
+- Correct the root npm package to the sole current native OpenCode plugin, registered as `matuto.psst`. Remove the classic/TUI/owned-run entries and Git-dependent wrapper. Public CLI is `opencode`.
+- Keep CodeMode enabled while registering send/resend as supported direct native tools with individual durable IDs; other broker tools remain in CodeMode.
+- Bundle the reviewed runtime directly; production dependencies are npm-registry only. Add root-tarball and official-loader regression gates.
+- Preserve approved private authorization and recover an existing client only from a unique, exact native binding. Unprovable ownership and old unapproved setup-owner loss fail closed without replacing credentials or journals.
+
+## 0.4.0 — 2026-11-01
+
+- Added native automatic delivery, durable setup and exact-session lifecycle corrections.
+- Packaging still selected the old root integration and required a separate Git-dependent native wrapper. Version 0.5.0 replaces that unsupported installation layout.
+
+## 0.3.0 and earlier — historical integration
+
+- Earlier prototypes used classic host/TUI and manual delivery integrations. They are no longer supported or shipped.
+- Existing private authorization and journal files must be preserved during the current package correction; old installation commands and experimental flags are not a supported upgrade path.

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,183 @@
-# Temporary Holding Version
+# Psst 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.
+**0.7.0 source candidate — not published yet.**
+One npm package, one current native plugin, registered as **`matuto.psst`**.
+The same npm package provides official server and TUI entries. There is no separate installation, Git wrapper or legacy entry.
+
+## Install or update
+
+After this version is published:
+
+```sh
+opencode plugin add @matuto-ai/opencode-psst-connector@0.7.0
+```
+
+For an existing installation, first inspect `opencode plugin list` and remove
+only this connector's exact previous package entry with `opencode plugin remove
+<old-entry>` before adding the new version. The manager matches exact package
+specs; keep unrelated plugins and all private Psst directories. Do not install
+both an old Git wrapper and this npm package.
+
+Reopen OpenCode, select the intended conversation and run **`/psst-setup`**.
+Enter the broker HTTPS URL in its single text field, then approve the displayed
+request in the broker admin page. `/psst-status` shows progress;
+`/psst-cancel-setup` pauses the local request without revoking existing access.
+No token, connection-file handoff or host policy change is needed. Startup never
+enrolls; an already approved installation is reused.
+
+Running setup again resumes the same pending request. Replacing a terminal request
+requires an explicit native confirmation tied to that exact request. The old
+connection stays active until the approved candidate attaches and its selection
+commits. Denial, cancellation or failed attachment retains the working connection.
+A deliberate new authorization has new credential-bound addresses; it does not
+adopt the previous authorization's mailbox. Old local data remains intact.
+Ordinary upgrades retain the same authorization, addresses and unread mailbox.
+
+### Request a replacement authorization
+
+Run **`/psst-reauthorize`** in the intended chat, or choose **Psst: Request
+replacement authorization** in the palette. It reuses the configured HTTPS broker
+origin (or asks for one if none exists), displays that target, and asks for native
+confirmation before creating a new request. Approve the displayed public request
+ID in the broker `/admin` page, then use `/psst-status` to distinguish pending,
+approved but not connected, and connected. A pending candidate is resumed, not
+replaced; an approved candidate whose attachment failed is retried intact.
+
+This is deterministic native TUI-to-server dispatch, with no model conversation
+or model/provider tokens required by the connector on supported OpenCode 2.2.5.
+It is not reconnect: reopening the selected conversation reuses saved credentials
+and existing addresses. Reauthorization creates new credential-bound addresses
+only after approval, attachment and safe selection. Old unread data is preserved,
+not replayed into the new identity. Existing access continues only while valid.
+
+**Replacement does not revoke the old credential.** Revocation is a separate
+human action in Psst admin; do not revoke working access first as a prerequisite.
+Cancellation, focus loss or an uncertain response never authorizes another new
+request: return to the original chat, inspect `/psst-status`, then repeat the
+command to reconcile the same candidate. Do not delete private state or locks.
+
+The URL-only `broker_setup` tool remains available for an explicitly requested
+initial setup, but an agent tool cannot confirm replacement. Use `/psst-reauthorize`
+for that decision. See [setup, persistence and acceptance](docs/setup-acceptance.md).
+
+## Messages
+
+Only the conversation selected in a local TUI receives automatic messages and renews its heartbeat. Home, exit and stale TUI leases suspend transport without closing the identity; reopening reconnects that identity. Multiple CLIs are independent. No TUI signal means offline. See [active-conversation behavior and limits](docs/active-conversation.md).
+
+Incoming messages use the native synthetic queue automatically, without changing
+agent/model selection or the user's draft. New native history notices include a
+compact literal preview, clearly labeled `Psst · new message`, with `From:` followed
+by sender name and client type. Correlation and IDs are not shown in the notice.
+Controls and bidi formatting are escaped; long text is truncated.
+The full machine-origin body is unchanged. Existing persisted notices keep their
+original payload, including their old label. There is no manual receive/ack tool.
+Use `broker_list_clients`, `broker_send`, `broker_message_status`,
+`broker_update_metadata`, `broker_sent_history`, `broker_message_content`,
+`broker_resend` and `broker_cancel`. Native tool identity and original timestamp
+scope private retry records; a new tool call is not semantically deduplicated.
+With CodeMode enabled, `broker_send` and `broker_resend` are advertised by the
+host as direct native tools alongside `execute`, so every outgoing call has its
+own durable identity. Other broker tools remain available inside CodeMode. No
+mode, permission or session change is required; sends are not nested under
+`execute`, whose children share one outer call ID.
+
+A broker receipt proves durable inbox storage; native admission proves persistence,
+not model understanding, human approval or completed work. Sender/message IDs stay
+in a compact machine-origin envelope. Uncertain/cancelled submissions are never
+blindly retried or discarded. See [delivery](docs/native-automation.md).
+
+## Compatibility
+
+OpenCode **2.x** native plugin APIs are the target; **2.2.5** is the validated
+version and current runtime guard. This is not a promise that every 2.0+ build
+has the required session admission, context, storage and lifecycle APIs. The
+public executable is `opencode`; unsupported versions fail clearly rather than
+falling back to another integration.
+
+## Existing authorization and private state
+
+The installation path is unchanged: `PSST_OPENCODE_CONFIG_DIR`, otherwise
+`$OPENCODE_CONFIG_DIR/psst`, otherwise `$XDG_CONFIG_HOME/opencode/psst` (default
+`~/.config/opencode/psst`). Keep it private (directory 0700, files 0600), under the
+same UID and absolute path. Existing approved credentials, receipts and inbox
+journals are not deleted, rotated or rewritten. An intentional `PSST_CONFIG_FILE`
+override remains respected and disables URL setup rather than secretly replacing it.
+
+The old registered ID had a different host-storage namespace. The new plugin can
+recover one unique private host anchor only from owned connector manifests and an
+exact matching native session ID, creation time, project and location. The old
+private format/path markers remain internal compatibility data, not plugin names.
+Corrupt, ambiguous or changed live ownership stops with `identity_recovery_*`.
+A fresh independent native host gets a new anchor only when all relevant previous
+session IDs are conclusively absent, or belong to another directory/workspace;
+it never adopts their journals. Existing live ownership still causes an
+owner conflict. Preserve the files and report the error rather than resetting them.
+Old classic journals without exact native bindings cannot be migrated automatically:
+`identity_legacy_migration_required` preserves them and stops new identity creation.
+This is a preservation limit, not a successful migration of that old layout.
+
+An old **unapproved** setup request whose owner existed only in the old host
+namespace cannot be resumed safely. It remains intact and inert with
+`setup_owner_recovery_required`; existing approved authorization is unaffected.
+New pending records also persist the exact owner binding privately, so they can
+resume after host-storage namespace loss only when the native session still
+matches. A crash after candidate persistence resumes that same request with GET,
+never another startup enrollment. No direct host-database access is used.
+
+## Verification
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run pack:check
+```
+
+The unit suite checks connector configuration, native session identity, setup state,
+message presentation, scoped tool calls, delivery receipts, cancellation and recovery.
+Host and broker boundaries use in-process fakes; persistence checks use disposable
+local files and SQLite journals. No OpenCode binary, broker server, container,
+network access or provider credentials are needed. See [verification](docs/verification.md).
+
+CI runs source syntax and this same unit suite. Package file-list checks remain a
+separate release safeguard, not an installed-host or end-to-end test. Unit results
+do not prove authenticated native model execution.
+
+MIT. Vendored Psst code keeps its license and exact integrity pins.
+
+## Migrating to the Psst package name
+
+Version 0.7.0 uses a new npm package and GitHub repository name. Follow the [migration checklist](docs/migration-0.6.0.md) before publication or upgrading an existing installation. Preserve all private Psst state and do not load both old and new sources.
+
+### Opt-in registration v2 and retained native conversations
+
+Registration remains v1 by default. With a compatible broker, an operator can set
+`broker.registrationVersion: 2` in plain configuration, or `registration_version: 2`
+in an existing `broker-client-bundle-v1` connection file. Only numeric1 or2 is
+accepted. The bundle keeps its enrollment-receipt requirement, credentials and
+paths; do not convert an enrolled bundle into plain configuration to opt in.
+This does not enable server cleanup. The broker's retention/enforcement activation
+is a separate operator decision after all connectors are compatible.
+
+An inactive native conversation resumes the same identity before expiry. After an
+authenticated lookup confirms its own broker session is gone, the connector
+revalidates the exact native conversation and selected state, then creates a fresh
+empty journal and identity. A private atomic `current-incarnation.json` pointer
+selects that generation on reload. Old pending sends, claims, native admissions and
+uncertain operations are never copied or replayed into the new generation. Old
+local journals remain untouched; this is not local-history deletion.
+
+The original root `owner.sqlite` lock remains held across rebuilding and child
+journals, preventing another worker from concurrently adopting the old root.
+Missing/corrupt pointed journals and v1 fallback after a pointer exists fail closed.
+Storage uncertainty stops automatic restoration for that conversation during the
+plugin lifetime; recovery requires a deliberate plugin reload that first reads the
+durable pointer. Never delete journals or change identities to force a retry.
+
+The reviewed SDK also contains two cooperative presence-event tools. This native
+connector intentionally continues exposing its existing eight tools, not those two
+new tools; unknown future SDK catalog changes still fail closed.
+
+Native offline transport notices and their exact-context ACK semantics are documented in [presence-notices](docs/presence-notices.md).
+
+For interrupted URL setup or multiple open chats, see [setup context and focus recovery](docs/setup-context-recovery.md). Keep unrelated chats open; return to the original chat and reconcile its saved request with `/psst-status`.

package/docs/active-conversation.md

@@ -0,0 +1,68 @@
+# Active conversation availability (Unreleased)
+
+The same root npm package provides the official OpenCode 2.2.5 `./server` and
+`./tui` entries. There is no second plugin installation or CLI wrapper.
+
+Only the conversation currently selected in a local TUI receives automatic
+messages and renews its broker heartbeat. Different TUI processes can select
+different conversations. If two select the same conversation, it remains active
+until the last owner leaves. Home and plugin pages select no conversation.
+
+Changing selection suspends transport and native delivery without closing the
+broker identity or deleting history. The broker may still show it connected until
+its existing lease expires (normally three minutes). Reopening reconnects the
+same persisted identity; heartbeat alone is not used to revive an expired lease.
+A synthetic submission already in flight may finish: its original journal and
+receipt are reconciled, not duplicated or rewritten.
+
+No TUI signal means offline, including a headless server. A remote TUI without a
+shared local private directory is unsupported and shows `Psst offline`; it does
+not restore all historic conversations. A newly selected conversation does not
+create a broker identity from this signal: its verified native prompt, tool or
+approved setup establishes the binding first.
+
+## Local preference, not authority
+
+TUI selection is an ephemeral file lease in the existing private installation
+area, scoped to the native directory and workspace. Files are atomically replaced,
+private (0600 in 0700 directories), bounded, and reject symlinks. A TUI-local
+in-memory owner and increasing sequence survive plugin reload. Each generation
+only removes its own last write. Updates are sampled every 250 ms and expire after
+five seconds without renewal. Server reconciliation runs every 500 ms. On Linux,
+PID start time and boot ID also reject dead or recycled owners; other supported
+platforms use process liveness and the bounded TTL, not Linux-specific `/proc`.
+
+**Processes with the same UID can forge this preference.** It is not an
+anti-spoofing security boundary. A forged lease can change availability of an
+already-authorized conversation (and cause its normal automatic wake/cost).
+It cannot create an authorized native binding, supply credentials, change scopes,
+redirect an inbox to another session, or grant tool access. The server continues
+to own credentials and journals and independently verifies exact native bindings.
+There is no public activate RPC or credential exchange. The native setup RPC
+accepts only a selected session ID, broker URL and exact-request replacement
+confirmation; it cannot supply credentials or bypass broker admin approval.
+
+Archive suspension can resume after native unarchive. Explicit disabled records,
+and older disabled records whose reason is unknown, remain disabled; selection
+never overrides them. Existing unread and uncertain operations remain intact.
+
+## Validation limits
+
+Unit tests exercise connector selection, identity, cancellation and recovery with
+in-process native and transport fakes. They do not start OpenCode or a broker.
+Authenticated model response and native-host compatibility remain separate product
+acceptance concerns. See [setup acceptance](setup-acceptance.md).
+
+## Display metadata
+
+Project labels resolve from the explicit local plugin/config `project`, then the
+single variable named by `PSST_PROJECT_ENV`, local `projectEnv`, or the default
+`AI_AGENTS_SANDBOX_PROJECT_NAME` (in that order), then the native directory's
+basename. Only a bounded display label is used, not a full environment dump.
+
+The exact native session `model.providerID` and `model.id` are preferred. If absent,
+`OPENCODE_MANAGED_MODEL=provider/model` is an explicitly configured fallback,
+reported as `configured`, never `observed`. Otherwise model remains `unknown`.
+Initial registration and newly prepared outgoing sends observe this metadata;
+retries retain their original immutable outgoing payload. Model selections and
+permissions are not modified.

package/docs/message-lifecycle.md

@@ -0,0 +1,31 @@
+# Outgoing message lifecycle
+
+`broker_send` takes recipient ID and text; retry keys are private.
+`broker_sent_history` lists the exact sender session's outgoing metadata;
+`broker_message_content` retrieves a retained original; `broker_resend` explicitly
+creates a new delivery; `broker_cancel` cannot undo receipt or execution.
+
+A native call's original assistant tool block supplies its stable ID and creation
+time. The connector persists the operation before HTTP and preserves its key on
+technical retry/recovery. A different native call is new intent even when text is
+identical. Aged or missing original proof fails closed, including after ledger GC.
+
+Inspect current status/history after uncertainty before requesting a new explicit
+send. Recovery is bounded to 10 retained operations and 5 seconds. Unknown effects
+remain unknown, never fabricated success. Broker 0.5.0 supplies the lifecycle APIs;
+transport, native admission and model completion remain separate evidence.
+
+## CodeMode routing
+
+OpenCode's CodeMode executor forwards one outer `execute` ID to all nested calls.
+The plugin therefore registers only `broker_send` and `broker_resend` with the
+supported `options.codemode:false`. The actual host catalog advertises those as
+direct tools alongside `execute`; all other broker tools retain normal CodeMode
+routing. Direct calls retain individually persisted native IDs and original
+timestamps. No invented child index, random retry ID or content-based dedup is
+used. An obsolete wrapper call remains fail-closed instead of sending ambiguously.
+
+Unit tests exercise scoped outgoing calls, stable operation IDs, payload conflicts,
+cancellation and recovery using an in-process transport and native API. They also
+assert that send/resend bypass CodeMode while other tools retain default routing.
+They do not run OpenCode's executor or prove an authenticated model turn.

package/docs/migration-0.6.0.md

@@ -0,0 +1,21 @@
+# 0.7.0 package and repository migration
+
+This is an unreleased source candidate, not proof of npm publication. The new package is `@matuto-ai/opencode-psst-connector@0.7.0`; the old package is `@matuto-ai/opencode-broker-connector`. No prerelease/RC package is required.
+
+## Owner publication order
+
+1. Review and merge the code in the existing repository; retain its history and branch protections. CI checks out this repository and runs its unit suite; it does not fetch a second repository.
+2. Rename the GitHub repository to `matuto-ai/opencode-psst-connector`. Do not create a replacement repository. Update local remotes and verify the `verify` check and repository settings after the rename. Package metadata already points at this final name.
+3. Establish the new public npm package through npm's supported owner/account setup. Configure its own trusted publisher for GitHub owner `matuto-ai`, repository `opencode-psst-connector`, workflow `npm-publish.yml`, allowing direct `npm publish`. The old package's trusted publisher does not transfer. Validate new configuration within npm's two-day first-publish window. Account and publishing actions belong to the owner, not this code change.
+4. Publish the GitHub release tagged `v0.7.0` only when the new package's publishing access is ready. The workflow checks tag/version parity and tests before publishing. Never publish the same package-name/version twice: if initial owner setup already published the final `0.7.0` artifact, do not trigger a second publish of it; reconcile the artifact and workflow plan first.
+5. Verify the new npm artifact, provenance, exact version and a clean native install plus upgrade. Only then deprecate the old package with a message naming its replacement. Keep old versions downloadable; do not unpublish them.
+
+## Existing installation migration
+
+After the new npm version is confirmed, list the native manager's existing package sources and remove only this connector's exact old source. Keep unrelated plugins and every private Psst state/credential directory. Add the new exact package version using the README command, then reload the native host. Do not load old and new copies together. An ordinary update of the old npm name does not switch names automatically.
+
+The change is packaging only: native commands, tool names, identities, protocol, saved authorization and durable journals stay unchanged. Do not delete state or request fresh credentials just to change the package name. Validate reconnect/resume and absence of duplicate delivery with the preserved installation, separately from clean-install tests. Unit test success is not acceptance in the user's authenticated environment.
+
+Keep native plugin ID `matuto.psst`, exports `.` and `./server`, commands and tool names unchanged. Preserve `PSST_OPENCODE_CONFIG_DIR` or the current `~/.config/opencode/psst` location and host-owned plugin storage. Use `opencode plugin list` to find the exact old source and `opencode plugin remove` for that source only; then add the new npm package. Do not erase the old private plugin journals or add a second plugin identity.
+
+References: [npm deprecation](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions/) · [trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/docs/native-automation.md

@@ -0,0 +1,37 @@
+# Native delivery contract
+
+The supported OpenCode 2.2.5 plugin uses public `session.get`, `synthetic`,
+`context`, hooks, events, storage and tool transforms. The root npm package exposes
+one server plugin, `matuto.psst`; no classic or optional alternate entry is shipped.
+
+- A durable private host/native-session binding and exclusive SQLite ownership
+  keep inboxes isolated. Same-session reopen retains the original broker identity.
+- Exact payload, native ID and injection ID commit before the single
+  `synthetic({delivery:"queue",resume:true})` effect. Receipt validation compares
+  session, ID, type, delivery and complete payload, not HTTP success alone.
+- At most one native item is pending. Native cancellation removes the host's
+  idempotency lookup, so uncertain delivery never automatically retries synthetic
+  admission. Read-only context proof can reconcile promotion; missing, cancelled,
+  compacted or mismatched evidence remains blocked rather than reinjected.
+- Interrupt/failure pauses delivery. Subsequent native execution can reopen the
+  event pause. Move/archive/delete/unload fence the exact owner; resumable unload
+  does not terminally close its surviving broker identity.
+- Losing the native event subscription, including a clean stream end, stops
+  transport, delivery and tools. Reload the plugin to resume the same durable
+  identities. In-flight admissions remain uncertain until exact native context
+  proves acceptance; stream recovery never resubmits them automatically.
+- Peer messages are native synthetic machine-origin input, not human authority.
+  Agent/model selection, drafts and native permissions remain unchanged.
+- Private operation IDs include the verified native call identity and original
+  assistant tool timestamp. An aged replay after journal GC fails closed.
+
+The public-ID correction preserves approved filesystem state. Identity recovery
+requires a single proven private anchor; old unapproved setup-owner records cannot
+be read from another host plugin namespace and remain inert. See the README.
+
+Official contracts: [plugin manager](https://opencode.ai/v2/docs/plugins/),
+[server plugins](https://opencode.ai/v2/docs/build/plugins/server),
+[synthetic admission](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/core/src/session/session.ts),
+[host loader](https://github.com/anomalyco/opencode/blob/v2.2.5/packages/plugin/src/host.ts).
+
+Unreleased: automatic transport is additionally limited by the local TUI selection preference described in [active-conversation.md](active-conversation.md). This does not grant authentication or tool authority.

package/docs/presence-notices.md

@@ -0,0 +1,21 @@
+# Native prolonged-offline notices
+
+With a broker advertising `policy.presence_events: true`, selected OpenCode conversations poll one bounded page (10 events, at most 64 KiB) per minute. Empty continuation pages are followed on later polls; each completed scan restarts without a cursor. Older brokers are not polled. The broker chooses the prolonged-absence grace and which affected sender may see an event; this connector does not infer a reply timeout or override presence policy.
+
+Notices enter the same bound native conversation as a synthetic machine message, without changing agent/model, granting permissions or treating peer data as human instructions. They contain only validated recipient/event/message IDs, timestamps and pending-delivery uncertainty. A leased transport is not proof of process or model responsiveness. Status is an observation, not a guarantee that the recipient remains offline. Messages are never automatically resent, cancelled or closed.
+
+The inbox's private, exclusively owned SQLite journal stores event ID, native ID and immutable payload before submission. Queue acceptance alone does **not** ACK an event. ACK requires an exact matching synthetic entry in native context, and means verified native presentation/admission into context, not human/model reading or a response. The original payload is compared on recovery, even if the broker's pending-message sample or observation timestamp changes.
+
+Lost responses remain pinned; no potentially invoked native submission is repeated, including after restart. Exact context can reconcile it later. ACK failures can retry after durable local presentation. If a broker suppresses an obsolete event before submission, no notice is submitted; once queued it cannot be silently removed, so its text explicitly states that current state may have changed. Durably presented notices retry ACK independently of polling results, including after a lost applied ACK. An exact broker `404 message_not_found` retires an obsolete presented notice; other errors remain unresolved.
+
+Cancellation, interrupted/failed execution, archive/revert, foreign binding, deselection and disposal fence this path just as they fence normal delivery. Explicit host-started execution can resume a paused conversation. No fallback prompt, notification subprocess or model-selection override is used.
+
+Confirmed/obsolete tombstones are retained eight days, then pruned; the broker already deduplicates their ACK. Uncertain/unconfirmed rows are never automatically pruned. The journal is capped at 10,000 events; the existing database/free-space bounds also apply. At capacity, new notices stop with `native_presence_capacity`, rather than evicting uncertainty and risking duplicate presentation. No credential changes, destructive journal cleanup or automatic reset is performed.
+
+## Validation scope
+
+`test/presence-notices.test.mjs` covers context-only ACK, restart, unknown native
+outcome, ACK failure, immutable payload, capability gating, cancellation, selection,
+bounded pagination, invalid metadata and durable-write failure. Native and transport
+APIs are in-process fakes. These unit checks do not prove broker grace-period behavior,
+authenticated model response or actual interactive TUI acceptance.

package/docs/publishing.md

@@ -0,0 +1,19 @@
+# Publishing the current OpenCode plugin
+
+The root npm package is `@matuto-ai/opencode-psst-connector`; the next version
+is **0.7.0**. Both `.` and `./server` resolve to the same native server object.
+The official ./tui entry is included in that same package. No alternate package, Git source dependency or host installer is included.
+
+The owner publishes the matching GitHub release after review/merge. The release
+workflow verifies tag/package parity, runs syntax, unit and package file-list
+checks, then packs once and publishes that archive to npm with provenance. Code publication and a green workflow are not proof that a
+release exists. Do not instruct installation of an unpublished version.
+
+After npm publication is verified, the supported command is:
+
+```sh
+opencode plugin add @matuto-ai/opencode-psst-connector@0.7.0
+```
+
+Keep current 2.2.5 native-runtime acceptance separate from the unit and package file-list checks.
+Do not use a Git URL, Git shorthand, source tarball workaround or policy bypass.

package/docs/reference-snapshot.sha256

@@ -0,0 +1,7 @@
+fbf0fa6096996cb9bc3f928e55f3eca496420880a03460e993dda3417b32ad88  reference/inbox.mjs
+e8ab94e6de6b5afb17b1dded9839fefa26481fef87ed715b041c09d41dbc93d5  reference/client.mjs
+8fdaa105b2e81aeaabb628131671989f951148f602844bca6819af827269f2c3  reference/runtime.mjs
+e1836d5c33ed80a9e15c1ca9d07888c9db3caf40aeb2a115c813f74a45077c6e  reference/tools.mjs
+88c61c995f9285ef7e22c401d7f0cf50fefc7dd6c76ae79c6bcc94097a33a5c3  reference/mcp-stdio.mjs
+85b0d0736c5a439f7c66697c3b1ce6cee998cda744dd3169c856ebf2b82bd2a7  reference/errors.mjs
+651f7d99987b58621070c5f24107ac621a09e325880506bc2e73cfe998d5b6aa  src/protocol.mjs

package/docs/setup-acceptance.md

@@ -0,0 +1,96 @@
+# URL-only setup and persistence
+
+## Install, configure, use
+
+The scoped 0.7.0 package is an unreleased source candidate. After publication,
+install it using the single native plugin-manager command in the README. The
+same package loads its server and TUI entries; do not install a second wrapper.
+
+1. Select a conversation in the local OpenCode 2.2.5 TUI. Run `/psst-setup` and
+   enter only the HTTPS broker origin.
+2. Open the displayed broker `/admin` page. Its form login and exact-request
+   approval are human actions. Pending setup is not a connection.
+3. Once approved, use the existing send/client tools. Incoming peer data enters
+   the native synthetic queue automatically for the selected conversation.
+   `/psst-status` reports status; `/psst-cancel-setup` pauses a pending local flow.
+
+Missing configuration never starts enrollment. Pending retries retain the same
+candidate and request, including uncertain network results. Private candidate
+persistence precedes the first enrollment POST. Restart only reads or polls an
+already durable request; it cannot generate a request or rotate credentials.
+If the server starts before the owner TUI, selecting that exact owner later
+resumes GET-only polling. Fatal poll, attachment or selection failures pause the
+flow; selection changes alone cannot retry them. Explicit setup is required.
+
+## Replacement and recovery
+
+The native dialog asks before replacing a terminal request and fences that
+confirmation to its exact request ID. Model tools cannot supply this confirmation.
+The prior authorization remains selected and usable until the approved candidate
+has attached and the original selection revision still matches. Cancellation,
+late results, failed attachment or an intervening selection cannot promote it.
+Retrying an approved but uncommitted candidate reuses its receipt and original
+selection baseline rather than silently replacing a newer choice.
+
+An explicit replacement creates a new credential-bound identity. It retains the
+old authorization's local inbox and history, but does not move unread messages or
+uncertain sends across authorities. Ordinary plugin upgrade or restart, without
+replacement, retains the original credential, mailbox, addresses and pending data.
+
+Denied, expired, paused and pending states are restored from private records.
+An expired but fully validated receipt can be inspected only for exact identity
+recovery, allowing the native setup UI to offer replacement. It is never accepted
+for connection or selection. Wrong token hashes, origin/type mismatches, missing
+receipts and corrupt files remain fatal. Broker rejection is reported separately
+from validated expiry and from protocol/retry failures.
+
+## Paths for disposable runtimes
+
+The shared installation directory is, in precedence order:
+
+- `PSST_OPENCODE_CONFIG_DIR`;
+- `$OPENCODE_CONFIG_DIR/psst`;
+- `$XDG_CONFIG_HOME/opencode/psst`, default `~/.config/opencode/psst`.
+
+Persist the complete directory, including selected and pending records, approval
+receipts, credentials, binding manifests and inbox journals. Keep the same absolute
+path and UID, directory permissions 0700 and file permissions 0600. Do not mount a
+subdirectory that omits receipts or owner locks. TUI and server must share this
+local private installation directory for active-conversation signaling.
+
+Installation sharing does not recreate OpenCode conversation history. To reopen
+an existing native conversation, also retain that host's OpenCode configuration,
+native data and state roots under the same project/workspace location. The pinned
+host uses `XDG_CONFIG_HOME/opencode`, `XDG_DATA_HOME/opencode` and
+`XDG_STATE_HOME/opencode` (default `~/.config/opencode`, `~/.local/share/opencode`
+and `~/.local/state/opencode`). An `OPENCODE_CONFIG_DIR` override must also remain
+available. Keep native host data separate for intentionally independent hosts;
+share the Psst installation, not their entire OpenCode database.
+
+A new host receives a fresh anchor only after native lookup proves all relevant
+previous sessions absent, or the persisted bindings belong elsewhere. Matching
+native history recovers the existing anchor. Unknown lookups, changed live
+bindings, multiple matching anchors or corruption do not permit a reset. Classic
+journals without a current native binding are retained and require explicit
+migration work; they are never silently adopted.
+
+## Test scope and remaining acceptance
+
+The maintained suite covers connector behavior with in-process native/transport
+fakes and temporary private storage: exact session bindings, setup cancellation,
+late results, selection CAS, attachment rollback, malformed state, expiry handling,
+identity separation, delivery receipts and uncertainty recovery.
+
+Real broker/server, OpenCode TUI, package-install, container recreation and
+end-to-end harnesses have been removed. There are no opt-in heavy test stages.
+Historical results remain in the repository's pull-request history; they are not
+current CI checks or proof of the current environment.
+
+Unit success does not establish authenticated provider execution, active model
+toolchain/abort behavior, release availability or native-host compatibility.
+For issue #8, the owner explicitly accepted source implementation, focused unit
+tests, independent review and CI as the current acceptance scope on 2026-11-04.
+Real-environment and integrated native/provider/container tests are deferred to a
+later run on the owner's machine, not current acceptance gates. Package
+publication is handled separately by the owner. These changes do not provision
+credentials or deploy anything.

package/docs/setup-context-recovery.md

@@ -0,0 +1,55 @@
+# Setup context and focus recovery
+
+Keep unrelated chats open. `/psst-setup` and `/psst-status` use the selected
+conversation and location captured by that TUI, not the number of open chats.
+Another TUI's selection or blur does not cancel this TUI's command.
+
+The supported OpenCode 2.2.5 boundary supplies renderer blur and selection
+events, but blur does not prove whether the user went to a browser, another
+terminal, or another native dialog. The connector therefore suspends the current
+action on blur instead of trusting a confirmation returned after losing focus.
+It also fences actual conversation/location changes, including away-and-back.
+
+- If you need a URL from another window, copy it first. Return to the intended
+  chat, dismiss the old dialog, and reopen `/psst-setup`.
+- After a request is saved, opening the broker `/admin` page is expected. Return
+  to the original chat and run `/psst-status`; any interrupted call does not erase
+  the durable request. If paused, `/psst-setup` with the same URL reconciles/resumes
+  that request. A running owner retry returns its existing request without a
+  second enrollment call. Never replay an old replacement confirmation.
+- `/psst-reauthorize` uses the same context guards and saved candidate. Its native
+  confirmation shows the broker origin and is bound to both the previous request
+  and selected-installation revision. Reconnect is automatic reuse of the saved
+  credential; reauthorization is a new human-approved candidate; revoke remains
+  a separate human action in Psst admin. Neither an agent nor a peer message may
+  silently substitute one action for another.
+- `request=not_submitted` means this action never called setup. It does not mean
+  there was no earlier request. `saved` means a durable request identity exists,
+  not proof that the broker has received or approved it. `unknown` means a reply
+  was lost or persistence could not be established; inspect status before retry.
+- Setup owned elsewhere must be resumed in its original chat. Pausing a pending
+  request does not authorize a different conversation to adopt it. Existing
+  explicit replacement of a terminal authorization remains available with a
+  fresh confirmation bound to its exact request.
+
+Warnings include only fixed phase/cause/request-state enums. Record those fields,
+host version, and whether the two chats were views of one TUI or independent
+TUIs/servers. Do not include messages, tokens, private paths or credentials. Do
+not delete locks, reset identity, terminate other CLIs or change permission policy.
+
+## Evidence and limits for issue #27
+
+Native-boundary unit doubles reproduce cancellation when this renderer emits
+blur during URL entry, preflight, replacement confirmation, setup, status or
+pause. A second independent TUI sharing the project can change its selection
+and emit blur without interrupting the stable first TUI. These tests establish
+connector event handling, not the original incident's host topology or trigger.
+The report that closing another chat helped remains a workaround observation,
+not evidence that two chats cause cancellation. No real-host reproduction,
+container/provider suite, live setup change or release is claimed.
+
+Regressions also cover selection change after receipt persistence, lost setup
+reply after replacement preflight, same-owner retry while polling, cancellation
+before/after persistence, durable read-only status and cross-chat ownership.
+The existing selection CAS, credentials, journal, native permission, active-chat
+routing and model/agent selection paths remain in place.