@matuto-ai/antigravity-broker-connector 0.1.1 → 0.3.1

package/README.md

@@ -1,3 +1,23 @@
+# Psst for Antigravity
+
+## Native setup (0.3.1 source candidate)
+
+Install the packaged native plugin once through Antigravity's normal `/plugin`
+manager, then invoke `psst-setup` and provide **only the broker HTTPS URL**.
+Approve the displayed request in the broker admin UI. Later native sessions load
+the privately saved installation automatically; no token/file handoff or repeated
+per-session enrollment is required. [Setup and exact persistence paths](docs/setup.md).
+
+Normal native permissions still apply. Interactive automatic receive remains an
+**experimental acceptance gate**, not a verified authenticated wakeup guarantee.
+Existing cooperative MCP installations and legacy private bundles remain supported;
+do not run both integrations simultaneously or erase their unread journals.
+
+The sections below document the existing cooperative/legacy entrypoint. For the
+new URL-only native path, use the setup guide above instead of pairing scripts.
+
+---
+
 # Antigravity broker connector for Psst
 
 A self-contained **stdio MCP server** for exchanging messages with other AI
@@ -7,17 +27,26 @@ use the seven broker tools from your normal Antigravity session. It does not
 launch a replacement CLI, need a checkout of the broker, or spend model tokens
 on transport heartbeats.
 
-**Current delivery mode: cooperative pull.** The agent calls `broker_receive`,
+**Default delivery mode: cooperative pull.** The agent calls `broker_receive`,
 reads the returned untrusted-agent message, then calls `broker_acknowledge` with
 its exact `message_id` and `receipt_token`. Nothing injects keystrokes, interrupts
 a task, auto-approves permissions, or wakes an idle model. A receipt means an
 explicit application-level read acknowledgment, **not completion of the requested
 work**.
 
+The [native integration](docs/setup.md) now supports URL-only setup and saved
+installation reconnection; [native acceptance evidence](docs/native-acceptance.md)
+separates tested transport/persistence from the outstanding authenticated wake gate.
+It never enables itself or changes native permission policy.
+
 ## Install and configure
 
+For brokers supporting the pairing API, [explicit installation pairing](docs/pairing.md)
+can create a private bundle from a pairing-file path without initial environment
+variables. Pairing alone does not attach a native conversation or enable push.
+
 Requires Linux and Node **24.19+ within major 24**. No dependencies or install
-scripts. After this naming PR merges, Git install from `main` works before an npm release is available:
+scripts. For reviewed source commits already on `main`, Git installation is available:
 
 ```sh
 npm install --global 'github:matuto-ai/antigravity-broker-connector#main'
@@ -28,7 +57,7 @@ For reproducibility, replace the branch with the reviewed commit SHA. The npm
 package is prepared as `@matuto-ai/antigravity-broker-connector`; **a prepared release
 workflow is not evidence that it has been published**. After the maintainer
 publishes it, install the exact scoped version with
-`npm install --global @matuto-ai/antigravity-broker-connector@0.1.1`.
+`npm install --global @matuto-ai/antigravity-broker-connector@0.3.1`.
 The executable remains `psst-antigravity`.
 
 Use a private enrollment bundle produced by the broker administrator. Keep

package/bin/psst-antigravity-native.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Explicit experimental entrypoint. Never selected by the released MCP command.
+import { serveNativePlugin, handleNativeHook } from '../src/native-plugin.mjs';
+import { waitApproval } from '../src/approval-waiter.mjs';
+import { waitNativeProcess } from '../src/native-process-waiter.mjs';
+const controller=new AbortController();
+const stop=()=>controller.abort();process.on('SIGINT',stop);process.on('SIGTERM',stop);
+try {
+  const [mode,...args]=process.argv.slice(2);
+  if(mode==='serve'&&args.length===1&&args[0]==='--experimental-native') {
+    const server=await serveNativePlugin({signal:controller.signal});await server.done;
+  } else if(mode==='hook'&&(args.length===0||(args.length===1&&args[0]==='observe'))) {
+    let text='';for await(const c of process.stdin){text+=c;if(Buffer.byteLength(text)>128*1024)throw Error();}
+    let output;
+    try{output=handleNativeHook(JSON.parse(text),{observe:args[0]==='observe'});}
+    catch{output={decision:'deny',reason:'Psst native binding is unavailable. No automatic approval or unbound broker call is permitted.'};}
+    process.stdout.write(JSON.stringify(output)+'\n');
+  } else if(mode==='wait-approval'&&args.length===2){process.stdout.write(await waitApproval({directory:args[0],permit:args[1],signal:controller.signal})+'\n');
+  } else if(mode==='wait'&&args.length===2) {
+    process.stdout.write(await waitNativeProcess({directory:args[0],permit:args[1],signal:controller.signal})+'\n');
+  } else throw Error();
+} catch {process.stderr.write('psst: experimental_native_unavailable; do not automatically retry a failed waiter or uncertain broker operation.\n');process.exitCode=1;}
+finally{process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);}

package/bin/psst-antigravity.mjs

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 import { readConnectorConfig } from '../src/connector-config.mjs';
 import { startConnector } from '../src/connector.mjs';
-const usage = 'Usage: psst-antigravity --config /absolute/private/config.json\nRuns a cooperative stdio MCP server; does not launch or inject into Antigravity.\n';
+import { pairingOptions, pairConnector } from '../src/pairing.mjs';
+const usage = 'Usage: psst-antigravity --config /absolute/private/config.json\n       psst-antigravity pair --pairing-file /absolute/private/pairing.json [--directory /absolute/private/installation]\nRuns a cooperative stdio MCP server; does not launch or inject into Antigravity.\nPair explicitly enrolls this installation; it does not connect or wake a native conversation.\n';
 if (process.argv.length === 3 && ['--help','-h'].includes(process.argv[2])) { process.stdout.write(usage); }
+else if (process.argv[2] === 'pair') {
+  try { process.stdout.write(JSON.stringify(await pairConnector(pairingOptions(process.argv.slice(2)))) + '\n'); }
+  catch { process.stderr.write('psst: pairing_failed; keep the same private pairing file and installation directory for a safe retry. No native session was connected.\n'); process.exitCode = 1; }
+}
 else {
   let connector;
   const controller = new AbortController();

package/docs/native-acceptance.md

@@ -0,0 +1,58 @@
+# Native automatic-arrival evidence — 2026-10-26
+
+## Supported mechanism
+
+The official [hook/tool contract](https://www.antigravity.google/docs/hooks)
+exposes `run_command` background tasks and native conversation IDs. Hooks occur
+at existing execution boundaries; they are not themselves an idle wake API.
+The [schedule documentation](https://www.antigravity.google/docs/commands/schedule)
+explicitly explains that a matching background-task completion message wakes
+its conversation. Psst uses that event-driven completion route, NOT recurring
+model calls or schedule polling. One permitted native waiter waits for local
+inbox state and exits with a fixed notice; the native host owns notification
+insertion and subsequent model invocation. The agent then receives and explicitly
+acknowledges the FIFO message. A completion notice alone is neither model-read
+nor task success.
+
+## Reproduced here
+
+`bash scripts/validate-official-native.sh` downloads the pinned official Google
+1.4.7 binary, checks SHA512, uses an isolated HOME, validates the complete plugin
+with `--strict`, installs it and lists it. Current result: one MCP server, one
+hook group, two skills, zero findings. The actual validator identified that
+hooks do not receive PLUGIN_ROOT; packaged hooks now use its documented plugin
+working directory. No permission override is installed.
+
+The native waiter tests prove one owner, one-use permits, request/conversation
+fencing, bounded per-head notices and unchanged pending journals. Real HTTPS
+approval tests exercise the actual broker/admin UI and frozen helper. They use
+synthetic native identities and do NOT establish authenticated vendor wakeup.
+
+A fresh actual interactive CLI launch stopped at its Google OAuth / Google Cloud
+project sign-in chooser. No sign-in choice, account, Terms acceptance or model
+call was made. Earlier headless MCP permission denial remains a failure gate,
+not an invitation to use skip-permission flags. Current environment also denies
+Unix socket binding; those three existing tests remain enabled for Linux CI.
+
+## Reproducible authenticated acceptance (still required)
+
+In an already authenticated, authorized native CLI, install this reviewed plugin
+and complete URL setup/admin approval once. Allow only the plugin's exact MCP
+and waiter operations if the native host asks. End the turn with its native
+waiter armed. From a second session send two distinct benign messages, serially.
+Without typing another prompt, verify each genuine native completion event,
+`broker_receive`, correct message content and explicit `broker_acknowledge`, then
+re-arming. Repeat while busy, reject a permission prompt, disconnect, close the
+native host and restart with the installation directory retained. Verify no
+human-permission inference from message text and no duplicate model processing.
+Stop on a native denial; do not alter authorization to force this test through.
+
+The first-conversation-per-CLI-host fence is deliberate: concurrent independent
+hosts work; switching conversations inside one host is not certified. A documented
+conversation-only close event has not been established, so host exit/disconnect
+is the verified cleanup boundary. Do not advertise all native acceptance gates
+as complete until those observations are recorded.
+
+The native task arguments are taken from the installed host's schema. The plugin
+asks only for `CommandLine` and `WaitMsBeforeAsync=500`; it does not invent an
+`IsDaemon` argument or request persistent/background permission overrides.

package/docs/native-pilot.md

@@ -0,0 +1,187 @@
+> Historical0.2.0 pilot evidence and limitations. The0.3.0 source candidate adds
+> packaged URL-only setup, durable installation selection and GET-only pending
+> recovery; see [current setup](setup.md). Historical disconnected-only/fresh-mailbox
+> statements below describe0.2.0, not the new persistence implementation. Actual
+> authenticated native wakeup and conversation-only cleanup remain unverified.
+
+# Native CLI delivery pilot (not enabled)
+
+The default connector remains cooperative MCP. This pilot is **not certified
+production automatic delivery**, and is not installed or activated by package startup.
+
+## Verified capability and remaining gate (2026-10-25)
+
+The official Antigravity CLI 1.4.7 binary was downloaded from the distribution
+manifest referenced by Google's installer and checked against its SHA-512.
+`--version`, `--help`, and offline plugin validation are available. An isolated
+local fake Gemini provider completed a real headless CLI turn with no account
+credential or paid model request. This proves neither subscription authentication
+nor automatic delivery into an existing interactive conversation.
+
+The runtime's actual `run_command` tool schema says a command continuing in the
+background produces a completion notification. It accepts `CommandLine`,
+`WaitMsBeforeAsync` (500–10000), `toolSummary`, and optional `IsDaemon`. These
+fields differ from some website examples; use the installed runtime schema.
+An interactive test stopped at fresh-profile Terms of Service / Data Use
+onboarding, without accepting it. Existing-user TUI wakeup remains untested.
+
+An independent headless fixture observed the real native process contract:
+plugin MCP runs directly under the CLI with `PLUGIN_ROOT` but no conversation
+environment variable; hooks run through `sh`, with
+`ANTIGRAVITY_CONVERSATION_ID` matching their stdin `conversationId`. The tested
+`nativeHookContext` implementation verified the same host PID/start time/boot ID
+and executable for real SessionStart and PreInvocation hooks. Lazy MCP calls use
+`call_mcp_tool` with `ServerName`, `ToolName` and `Arguments`; plugin server names
+were prefixed with the plugin name. PreToolUse observed this wrapper correctly.
+
+The attempted MCP call was denied by native headless permission policy, which
+cannot prompt. No allow rules, auto-approval or permission-skip flags were added;
+the MCP tool did not execute. Therefore actual `overwrite` propagation to MCP
+and interactive idle wake remain acceptance gates, not verified successes.
+
+Official references:
+- [Native plugins](https://www.antigravity.google/docs/plugins): CLI plugin
+  installation while running; packaged skills, hooks, and MCP configuration.
+- [Hooks](https://www.antigravity.google/docs/hooks): native `conversationId`,
+  `PreToolUse.overwrite`, and `PreInvocation` context steps.
+- [Scheduling](https://www.antigravity.google/docs/commands/schedule): a matching
+  background task completion is a wakeup; no periodic scheduler is proposed here.
+- [Sidecars](https://www.antigravity.google/docs/sidecars): documented
+  `agentapi send-message` support is App-only, not a CLI capability claim.
+- [CLI installation](https://www.antigravity.google/docs/getting-started).
+
+## Intended flow, requiring native proof
+
+1. Install the native plugin in the running CLI. Startup stays disconnected;
+   neither environment variables nor credentials are required to load it.
+2. An explicit connect skill accepts only a private pairing-file **path**, never
+   a secret in conversation text. The shared enrollment helper creates one
+   installation credential; each native conversation receives a fresh address.
+3. Native hooks bind broker calls to their actual conversation, not to a
+   model-supplied ID. A one-use opaque routing ticket must bind conversation,
+   incarnation, tool arguments and expiry. Hook `overwrite` may attach this
+   ticket; `allow` must still delegate to normal permission policy. MCP hook
+   matching and argument overwrite need runtime proof before this is enabled.
+4. After connect, the model arms one native background waiter. Transport receives
+   without model-token polling. A durable pending inbox event completes the task
+   with a fixed notice, not message content. Native completion should wake the
+   owning conversation; the model receives, explicitly acknowledges reading,
+   and re-arms automatically. The human does not call receive.
+5. Disconnect cancels transport/waiters. Reconnect uses bounded transport backoff;
+   lost notices retain pending data. An expired credential requires re-pairing.
+
+`src/native-waiter.mjs` is the tested event-driven waiter primitive. The separate
+experimental adapter uses the same durable inbox and explicit receipt boundary.
+It does not change the default MCP-process singleton. A
+successful notice does not advance the FIFO, create a read receipt, or prove
+the requested action succeeded. No terminal input injection, permission override,
+infinite Stop-hook continuation, or model-polling cron is an acceptable substitute.
+
+`src/native-binding.mjs` is the second gated primitive: a first-conversation fence
+and small private SQLite invocation-permit store. A verified hook issues an
+opaque, one-use, 30-second permit for exact tool arguments; MCP must consume it
+atomically before acting. At most 32 unexpired permits are retained, containing
+the raw short-lived nonce and argument hashes, not message bodies or broker/pairing
+credentials. Missing hooks, modified arguments,
+wrong session/host, expiration and replay fail closed. Uncertain commit/rollback
+fences that handle; a closed host invalidates permits and cancels its waiter.
+It is not a general multiplexing service and is not loaded by the released CLI.
+
+This protects the native integration boundary under the assumption that the
+installed hook code and private connector state are intact. **It is not a
+cryptographic boundary against hostile code with the same OS UID and filesystem
+access.** Native permission policy remains authoritative. `allow` only delegates
+to that policy; it must never be replaced by `auto_approve` or permission overrides.
+
+## Minimum native acceptance test
+
+### Runnable experimental connector
+
+The code now includes a separately gated native entrypoint and plugin generator.
+From a checkout, generate it with:
+
+```sh
+node scripts/prepare-native-plugin.mjs /absolute/new/psst-native --experimental-native
+agy plugin validate /absolute/new/psst-native --strict --json
+```
+
+The packaged generator command is `psst-antigravity-native-plugin` with the same
+arguments. Neither command installs the plugin or edits a live CLI profile.
+The generated plugin uses absolute executable paths from this installation;
+keep that installation available inside the same sandbox. Its native MCP server
+starts disconnected without credentials or initial environment variables.
+
+After explicitly installing the generated directory in an already-onboarded CLI,
+invoke its `psst-connect` skill with a private pairing-file or connection-file
+path. The hook stamps the real conversation; connect creates a fresh broker
+session, recipient discovery uses `broker_list_clients`, and the skill arms the
+returned waiter command under normal native permissions. The waiter exits only
+on durable pending data, cancellation, owner loss or an attention condition;
+background completion is the proposed native wakeup. The model reads and ACKs,
+then re-arms without a human receive command. Errors/denials stop automatic
+retries. Two notices per head are allowed, followed by one attention notice;
+subsequent waits for the same unacknowledged head stay silent. This budget is
+persisted and never consumes the message.
+
+Only the first explicitly connected conversation in a native CLI process is
+supported. A different conversation requires a fresh CLI host. One kernel-held
+MCP-owner lock prevents concurrent owners. MCP EOF invalidates its permits and
+waiter but preserves the verified native host's first-conversation fence. A
+restart under the same host starts disconnected; a new explicit connect creates
+a fresh mailbox, never silently adopts the old one. Owner-incarnation checks
+reject old hooks and permits. Disconnect cancels the waiter and transport, while retaining the
+private installation credential; a new connect creates a fresh session address.
+Re-pairing creates a separate private credential directory. Expiry or terminal
+broker authentication failure stops transport and marks the connection unavailable.
+There is no documented CLI ConversationClosed/SessionEnd hook. `Stop`/`fullyIdle`
+is not treated as session closure because it also describes normal idle work.
+Immediate deregistration when a conversation alone is deleted while its host
+remains alive is therefore not certified; explicit disconnect or closing that
+CLI host is the supported boundary. The live test must inspect task cancellation
+in that case, rather than inferring it from a generic idle observation.
+
+Deterministic adapter tests run the actual HTTP broker transport, durable inbox,
+hook-decision/permit boundary, external waiter, FIFO receive/ACK, and disconnect
+races. Official CLI 1.4.7 strict validation recognizes the generated plugin's
+one MCP server, one hook configuration and one skill with no findings. These
+tests still do not prove native permission acceptance, hook-overwrite delivery,
+or interactive idle wakeup. Those remain the explicit user-owned CLI gate.
+The official CLI also loaded this actual generated plugin in a disposable
+headless fake-provider run: native discovery exposed `psst-native_psst` and
+`broker_connect`, hooks initialized, and the server remained disconnected with
+no client/inbox until EOF. No broker tool was requested in that test.
+
+### Disposable wakeup-only fixture
+
+The disposable first-stage proof plugin can be generated without installing it:
+
+```sh
+node scripts/prepare-native-proof.mjs /absolute/new/proof-plugin
+agy plugin validate /absolute/new/proof-plugin --strict --json
+```
+
+The official CLI 1.4.7 validator returned no findings for the generated manifest,
+one hook and one skill. In an already-onboarded test CLI, explicitly install that
+directory using `/plugin install /absolute/new/proof-plugin` and invoke its
+`psst-native-proof` skill. It prints the separate synthetic signal command. After
+the agent ends its turn, execute that command from the same sandbox. Success is
+an unsolicited `PSST_NATIVE_WAKE_OBSERVED` response in the owning conversation.
+This first stage has no broker or ACK and is not the full acceptance test below.
+It never changes permission policy, sends terminal input, or invokes a timer.
+
+Use an already-onboarded CLI in the intended sandbox, with explicit permission
+for the disposable test commands. No production credentials are necessary for
+the wakeup proof. The pilot adapter must be reviewed before this test:
+
+1. Load a local proof plugin; verify hooks and skills in `/hooks` and `/plugin`.
+2. Start a finite event waiter using native `run_command` (`WaitMsBeforeAsync:500`,
+   `IsDaemon:false`). End the model turn without polling or scheduling.
+3. From the disposable fixture, commit one synthetic pending inbox item.
+4. Without another human prompt, verify the same conversation gets a completion
+   notice, invokes receive and explicit ACK, then arms another waiter exactly once.
+5. Repeat while the model is busy; exercise two conversations, disconnect, lost
+   notice, and restart. No cross-conversation delivery or implicit read ACK.
+
+Record CLI version, native tool/hook observations and the resulting transcript
+events (not hidden reasoning or secrets). Until this passes, automatic CLI
+delivery remains a gated pilot, not a completed production feature.

package/docs/pairing.md

@@ -0,0 +1,48 @@
+# Explicit installation pairing
+
+This additive command prepares a credential bundle. It **does not connect a
+running Antigravity conversation or enable automatic delivery**. Existing
+`--config` and `PSST_CONFIG_FILE` cooperative MCP configuration remain unchanged.
+The broker must support the reviewed `/v1/enrollments` pairing API; a prepared
+broker change is not evidence that the operator deployed it.
+
+The operator provides a short-lived, single-use private pairing file. Place it
+inside the intended sandbox with mode `0600` and a private parent directory.
+Never paste its contents into a model prompt, command argument, URL or log.
+
+```sh
+psst-antigravity pair --pairing-file /absolute/private/pairing.json
+```
+
+No initial environment variables are required. The default installation directory
+is `~/.config/psst/antigravity`; optionally use `--directory /absolute/private/dir`.
+All paths must be absolute. The helper validates HTTPS origin, client type and
+private file ownership/modes; it creates private retry state before HTTP.
+It generates this installation's bearer token locally and transmits only its
+SHA-256 verifier. The pairing secret is sent only in the HTTPS Authorization
+header. Existing credentials and legacy bundles are not overwritten.
+
+Success prints nonsecret JSON including `connectionFile`, `credentialId`,
+`expiresAt` and `connected:false`. Use the returned `connectionFile` as the
+existing MCP entry's `--config` argument. Keep the installation directory: it
+contains the private token and recovery state. A restarted cooperative connector
+still has a fresh process address; pairing does not change that scope.
+
+New bundles are explicitly marked with `enrollment_receipt_file:"enrollment.json"`.
+The connector verifies the private sibling receipt against the bundle's origin,
+client type and token hash; missing, corrupt, mismatched or expired receipts fail
+closed. An older connector may reject this new marker: upgrade the connector
+before pairing. Unmarked legacy administrator-generated bundles remain supported.
+
+For an uncertain network/storage result, keep the same pairing file and directory
+for an explicit retry: the persisted enrollment ID and token are reused. A new
+pairing grant is required after credential expiry or revocation. An error is not
+proof that the broker failed to store the enrollment. Never delete retry state to
+make an uncertain result look new.
+
+The vendored single-file helper is shared with the Psst broker implementation;
+it is separate from the older pinned reference runtime. Its local integrity and
+compatibility are checked by the pairing tests; it makes no native-delivery claim.
+It is pinned to [Psst commit 3e908e7](https://github.com/matuto-ai/psst/blob/3e908e79966d886a02d372c103e31dec6e900c1a/reference/enrollment.mjs)
+from [upstream pairing PR #18](https://github.com/matuto-ai/psst/pull/18).
+That source reference does not imply the upstream PR is merged or deployed.

package/docs/release.md

@@ -11,10 +11,10 @@ it does not assert that npm already hosts the package.
    `antigravity-broker-connector`, workflow `npm-publish.yml`. This is an account
    security configuration performed by the maintainer, not by this code change.
 4. Set package version and create a GitHub release whose tag is exactly
-   `v<package.json version>` on the reviewed commit (next `v0.1.1`).
+   `v<package.json version>` on the reviewed commit (`v0.2.0` for this release).
 5. The workflow runs syntax checks, all tests, and an isolated tarball install;
    only then it runs `npm publish --access public --provenance --ignore-scripts`.
-6. Verify the workflow result and `npm view @matuto-ai/antigravity-broker-connector@0.1.1`
+6. Verify the workflow result and `npm view @matuto-ai/antigravity-broker-connector@0.2.0`
    before advertising the npm install command.
 
 The workflow follows the user's existing release/OIDC pattern, with test and
@@ -24,13 +24,16 @@ back to another identity. Git/packed-tarball installation remains available even
 before npm setup. Release publication, credential creation, and broker enrollment
 are distinct from preparing or merging connector code.
 
-## Patch release
+## Minor release 0.2.0
 
-This PR prepares `0.1.1`; the intended GitHub release tag is `v0.1.1`.
-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.
+The intended GitHub release tag is `v0.2.0`, matching `package.json`.
+Use the existing release-triggered Trusted Publishing workflow and normal npm
+`latest` tag; no prerelease workflow or account configuration is changed here.
+Review the [changelog](../CHANGELOG.md) before publishing. The native pilot is
+opt-in/default-off, and real idle wakeup, native hook overwrite propagation, and
+conversation-only close cleanup remain acceptance gates—not production claims.
 
-Existing `0.1.0` 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.
+Create the new tag only on the reviewed, tested merge commit. Existing versions
+and tags remain untouched. Verify publication, provenance and the scoped npm
+version before recommending installation. A successful merge alone does not
+mean npm publication succeeded.

package/docs/setup.md

@@ -0,0 +1,124 @@
+# Setup once from Antigravity
+
+Install the packaged native plugin once with the ordinary native plugin manager.
+Its directory now includes `plugin.json`, hooks, MCP configuration and skills;
+no generated pairing file or per-window operator script is the primary path.
+Node 24.19+ within major 24 must already be available inside the same sandbox. Do not run
+the old cooperative MCP configuration alongside the native plugin: each would
+otherwise own a separate address. Existing cooperative installations continue to
+work unchanged; switching integrations does not erase their unread journals.
+
+One-time package bootstrap, **after this version is released**:
+
+```sh
+npm install --prefix "$HOME/.local/share/psst-antigravity" --ignore-scripts \
+  @matuto-ai/antigravity-broker-connector@0.3.1
+```
+
+Then use the native `/plugin install` command with the absolute installed folder
+`$HOME/.local/share/psst-antigravity/node_modules/@matuto-ai/antigravity-broker-connector`
+(expand HOME to its real path). A preinstalled sandbox does this once in bootstrap,
+not for each session. The official native manager copies the package's plugin
+files into its managed plugin directory. No global Node change is required.
+
+1. In Antigravity invoke `psst-setup`; provide only the HTTPS broker URL.
+2. The administrator approves the displayed request ID in the broker's login-form
+   UI. There is no token/password to paste into the conversation.
+3. The plugin saves approved installation selection privately. Later native
+   sessions load it automatically, each with a separate conversation mailbox.
+
+Normal startup never creates an enrollment request or rotates a key. A durable
+previously requested pending enrollment may be resumed using GET-only polling;
+closing before approval and reopening afterwards does not require another setup.
+Unknown/network outcomes retain the same local request/token. Denial, expiry,
+revocation or corrupt state needs explicit attention, never automatic replacement.
+Explicit setup again requests replacement while keeping the old working selection
+until the candidate attaches and the selection compare-and-swap commits.
+
+## Persistence/bootstrap contract
+
+Default installation root:
+`~/.gemini/antigravity-cli/psst/installation`
+
+Override: `PSST_ANTIGRAVITY_INSTALLATION_DIR=/absolute/private/persistent/path`.
+Bootstrap may share/mount this directory at the SAME absolute path across local
+containers of the same trusted OS user. Do not share across untrusted users or
+use NFS; private SQLite kernel ownership and atomic local renames are required.
+The directory is 0700, private JSON/token files 0600. `selected.json` contains only
+the approved bundle path, credential ID, request ID and revision; `pending.json`
+contains nonsecret broker/request intent and cancellation state. The vendored
+helper stores candidate secrets and approved bundles in `approvals/` beneath it.
+Never print/copy those credentials into chat or logs.
+
+Native journals are beneath the approved bundle's `state/native-<hash>` directory,
+partitioned by broker, verified credential and native conversation ID. Preserving
+the installation root therefore preserves authorization AND independent pending
+mailboxes. A new native conversation gets a new address; reopening the exact
+native conversation can resume its address/journal, with a single kernel owner.
+A different approved credential never silently adopts its predecessor's inbox.
+Do not delete old directories on replacement or upgrade.
+
+Transient host bindings/waiter ownership remain separate under
+`~/.config/psst/antigravity/native`; do not mount/share this directory between
+containers. The reviewed sandbox archive a7f63e8 (`agents/agy/config.sh`) mounts
+`projects/<project>/agy/<identity>/gemini` at `/home/node/.gemini` and uses an
+`agy-shell-gemini` volume for shell state. The default installation root is
+therefore persistent per project/identity in that archived layout. To share one
+Psst installation across projects, bootstrap can mount only a dedicated private
+`$CONFIG_DIR/psst/antigravity/installation` at `/home/node/.config/psst-installation`
+and set `PSST_ANTIGRAVITY_INSTALLATION_DIR` to that path. Do NOT share entire
+`.gemini` conversation databases or the provider keyring. The archived native
+policy rejects plugin/MCP imports; enabling this plugin needs a separately
+reviewed bootstrap exception, never an adapter bypass. No bootstrap file was
+changed by this connector. Actual user mounts have not been inspected; these paths are the
+connector contract, not a claim about an existing deployment.
+
+`broker_disconnect` stops this host's transport and locally cancels pending setup
+resumption; `broker_cancel_setup` leaves existing approved transport intact.
+Neither revokes server authorization. Admin UI revocation is separate. Pending
+messages are retained; broker presence can remain until lease expiry.
+
+## Native capability and acceptance limits
+
+The primary setup interface is a native skill asking for a single nonsecret URL
+and an MCP tool whose only setup field is `broker_url`; no private secret form is
+needed. SessionStart/PreInvocation hooks provide verified native context and can
+load approved state. PreToolUse permits remain one-use and exact-conversation,
+and `allow` continues to delegate to ordinary native permissions.
+
+Only the first conversation in one CLI host is supported by the conservative
+root/subagent fence. Independent CLI hosts may share installation authorization;
+they do not share conversation identities. Switching to another conversation
+inside the same host is rejected rather than borrowing the first one's mailbox.
+No reliable CLI ConversationClosed/SessionEnd hook was established. Closing a
+host is observed, but deleting only its conversation is still a cleanup gate.
+
+The background command waiter uses supported native completion notifications;
+it does not scrape terminals, simulate keys, force permission approval or run a
+model polling loop. The model arms the approval/inbox waiter under normal native
+permissions, then reads and explicitly acknowledges received AGENT data. Writing
+a notice or recording broker delivery does NOT establish model processing or
+successful task execution. Real authenticated interactive idle wakeup remains
+unverified; previous headless permission denial was not bypassed. The native
+route remains experimental, not a certified production automatic-receive claim.
+
+Sources: https://www.antigravity.google/docs/plugins and
+https://www.antigravity.google/docs/hooks (checked2026-10-26).
+
+### Targeted bootstrap review checklist (not applied)
+
+Keep `agy-policy.py` rejection of arbitrary project/global integrations. The
+narrow addition would allow exactly the reviewed `psst-native` plugin under the
+native manager's installation directory, with a pinned package/digest and its
+known `plugin.json`, `hooks.json`, `mcp_config.json`, two skills and runtime files.
+Validate every plugin path as a regular, non-symlink image-managed file; reject
+additional plugins, servers, hook commands, custom providers and unknown registry
+entries. Permit only the plugin's Node executable/serve command and exact native
+hook entrypoints; do not enable all MCP servers or add permission-skip options.
+The native manager's own registry/import-manifest formats must be inspected and
+allowlisted narrowly as part of that separate bootstrap review. Mount only the
+private installation directory described above; keep native host bindings and
+provider auth separate. Test both the permitted exact plugin and malicious
+extra/symlink/modified-command cases against the real archived policy before a
+user deploys the revised sandbox. This is an integration specification, not a
+claim that the existing archived security policy already permits the connector.

package/hooks.json

@@ -0,0 +1 @@
+{"psst-native-binding": {"SessionStart": [{"type": "command", "command": "node ./bin/psst-antigravity-native.mjs hook observe", "timeout": 5}], "PreInvocation": [{"type": "command", "command": "node ./bin/psst-antigravity-native.mjs hook observe", "timeout": 5}], "PreToolUse": [{"matcher": "call_mcp_tool|run_command", "hooks": [{"type": "command", "command": "node ./bin/psst-antigravity-native.mjs hook", "timeout": 5}]}]}}

package/mcp_config.json

@@ -0,0 +1 @@
+{"mcpServers": {"psst": {"command": "node", "args": ["./bin/psst-antigravity-native.mjs", "serve", "--experimental-native"]}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matuto-ai/antigravity-broker-connector",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "type": "module",
   "engines": {
     "node": ">=24.19.0 <25"
@@ -11,16 +11,27 @@
     "test:pack": "node scripts/pack-smoke.mjs"
   },
   "license": "MIT",
-  "description": "Cooperative stdio MCP connector between Antigravity and the Psst agent message broker.",
+  "description": "Native Antigravity Psst setup and conversation messaging with private administrator-approved installation credentials.",
   "bin": {
-    "psst-antigravity": "bin/psst-antigravity.mjs"
+    "psst-antigravity": "bin/psst-antigravity.mjs",
+    "psst-antigravity-native-plugin": "scripts/prepare-native-plugin.mjs"
   },
   "files": [
     "bin/psst-antigravity.mjs",
+    "bin/psst-antigravity-native.mjs",
+    "scripts/prepare-native-plugin.mjs",
     "src/**/*.mjs",
     "vendor/psst/**",
     "docs/installation.md",
-    "docs/release.md"
+    "docs/pairing.md",
+    "docs/native-pilot.md",
+    "docs/release.md",
+    "plugin.json",
+    "mcp_config.json",
+    "hooks.json",
+    "skills/**",
+    "docs/setup.md",
+    "docs/native-acceptance.md"
   ],
   "repository": {
     "type": "git",

package/plugin.json

@@ -0,0 +1 @@
+{"name":"psst-native","version":"0.3.1","description":"Psst URL-only setup and native conversation messaging; automatic native wakeup remains experimental."}