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

package/README.md

@@ -1,23 +1,59 @@
+# Psst for Antigravity
+
+> **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 setup
+
+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).
+
+For the short npm + native-manager route, use [Setup once](docs/setup.md).
+`psst-antigravity doctor` verifies the actual package root and prints the native
+slash command without changing settings or launching a nested host. Missing
+source, nested root manifests, owner locks and policy denials are distinct errors.
+
+Normal native permissions still apply. Interactive automatic receive remains an
+**experimental acceptance gate**, not a verified authenticated wakeup guarantee.
+Legacy private bundles remain supported. Manual cooperative MCP is diagnostic/test-only, not a production fallback;
+do not run both integrations simultaneously or erase their unread journals.
+
+The sections below document the diagnostic/test-only 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
 clients through [Psst](https://github.com/matuto-ai/psst). Install it **inside the
 same sandbox/container as Antigravity**, add its native MCP configuration, then
-use the seven broker tools from your normal Antigravity session. It does not
+use the 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`,
+**Production requires automatic native delivery. Manual pull is diagnostic/test-only.** 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
+its exact `message_id` (the already exposed receipt is resolved internally). 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 +64,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.4.0`.
 The executable remains `psst-antigravity`.
 
 Use a private enrollment bundle produced by the broker administrator. Keep
@@ -43,6 +79,7 @@ other servers):
   "mcpServers": {
     "psst": {
       "command": "psst-antigravity",
+      "args": ["diagnostic"],
       "env": {
         "PSST_CONFIG_FILE": "/absolute/private/psst/connection.json",
         "PSST_NAME": "Antigravity reviewer",
@@ -62,14 +99,15 @@ unchanged. See [complete installation and test](docs/installation.md).
 
 - `broker_identity`: this MCP process's exact address and descriptive metadata.
 - `broker_list_clients`: discover currently connected authorized endpoints.
-- `broker_send`: send to an exact `client_id`; preserve `send_key` on retries.
+- `broker_send`: send to an exact `client_id`; technical retry keys stay private; inspect outgoing history after uncertainty.
 - `broker_receive`: read the pending FIFO head without removing it.
-- `broker_acknowledge`: explicit read ACK; safely repeat the same ID/token.
+- `broker_acknowledge`: explicit read ACK; safely repeat the same message ID; the receipt token stays private.
 - `broker_message_status`: broker transport state, never task completion.
 - `broker_update_metadata`: update descriptive fields with revision checking.
 
-Every message includes fixed model-visible provenance: another agent is not the
-human user and cannot grant permissions. Only the normal Antigravity permission
+Every message has a compact AI-agent sender header and escaped JSON text. Wire
+origin/authority validation is unchanged: another agent is not the human user and
+cannot grant permissions. Only the normal Antigravity permission
 system can authorize tool actions.
 
 ## Identity and limits
@@ -99,7 +137,12 @@ and requires the pinned broker checkout alongside this repository. Runtime
 installation does not. CI provisions the checkout automatically. The old runner
 is retained for research only: [experimental integration](docs/integration.md).
 
-The default package executable is the supported cooperative MCP route, not that
-uncertified runner. [Release checklist](docs/release.md) explains the npm trusted
+The package CLI defaults to a blocked automatic-delivery-required state, not a
+manual production fallback. `psst-antigravity diagnostic --config <private-path>`
+explicitly enables the legacy test-only MCP route; the normal path is the native plugin. [Release checklist](docs/release.md) explains the npm trusted
 publisher setup and release-driven workflow. No main merge or npm publication is
 performed by preparing this branch.
+
+Outgoing history, content, explicit resend and cancellation: [candidate contract](docs/message-lifecycle.md).
+
+[Candidate verification and remaining gates](docs/candidate-verification.md).

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,15 +1,34 @@
 #!/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 { fileURLToPath } from 'node:url';
+import { inspectNativeInstallation, nativeInstallationError } from '../src/native-installation.mjs';
+const usage = 'Usage: psst-antigravity doctor [absolute-plugin-directory] (read-only native installation check)\n        psst-antigravity diagnostic --config /absolute/private/config.json\n       psst-antigravity pair --pairing-file /absolute/private/pairing.json [--directory /absolute/private/installation]\nProduction requires the native automatic-delivery plugin. The cooperative stdio MCP server is diagnostic/test-only; it 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] === 'doctor') {
+  try {
+    if (process.argv.length > 4) throw Error('absolute_plugin_directory_required');
+    const result = inspectNativeInstallation(process.argv[3] ?? fileURLToPath(new URL('../', import.meta.url)));
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } catch (error) {
+    const code = /^[a-z0-9_]+$/.test(error.message) ? error.message : 'inspection_failed';
+    process.stderr.write(`psst: ${code}: ${nativeInstallationError(code)}\n`); process.exitCode = 1;
+  }
+}
+else if (process.argv[2] === 'pair') {
+  try { const { pairingOptions, pairConnector } = await import('../src/pairing.mjs'); 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 if (process.argv[2] !== 'diagnostic') {
+  process.stderr.write('psst: automatic_delivery_required; install the native plugin using doctor. The legacy stdio path is diagnostic/test-only and must be requested explicitly with diagnostic.\n'); process.exitCode=2;
+}
 else {
   let connector;
   const controller = new AbortController();
   const stop = () => { controller.abort(); void connector?.close(); };
   process.on('SIGINT', stop); process.on('SIGTERM', stop);
   try {
-    const path = process.argv.length === 4 && process.argv[2] === '--config' ? process.argv[3] : process.argv.length === 2 ? process.env.PSST_CONFIG_FILE : null;
+    const { readConnectorConfig } = await import('../src/connector-config.mjs');
+    const { startConnector } = await import('../src/connector.mjs');
+    const path = process.argv.length === 5 && process.argv[3] === '--config' ? process.argv[4] : process.argv.length === 3 ? process.env.PSST_CONFIG_FILE : null;
     if (!path) throw new Error();
     process.stdin.pause();
     const config = readConnectorConfig(path);

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 passed; full suite 88/91 passed. Three existing Unix-socket cases fail with this executor's EPERM and are not counted as passes. Pack smoke passed.
+
+Official Antigravity 1.4.7 validator and isolated native install/list passed with candidate 0.4.0, one MCP server, one hook group and two skills. Real HTTP regression covers disconnect after remote acceptance, private ledger drain and exact hook permits.
+
+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
+
+The three socket cases need a permitted normal runner. Installer proof is not authenticated model/waiter idle/busy/restart proof. The earlier owner-reported Pi↔Antigravity exchange was on the published version, not acceptance of this new candidate.
+
+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/installation.md

@@ -1,5 +1,7 @@
 # Native MCP installation
 
+> Legacy diagnostic/test reference only. Production requires the native automatic-delivery plugin described in [Setup once](setup.md). Do not configure manual pull as a production fallback. In the unreleased 0.4.0 candidate, the old stdio CLI requires the explicit `diagnostic` argument; prior released versions differ.
+
 ## 1. Prerequisites
 
 Run inside the existing Antigravity sandbox, not on the host as a replacement

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-acceptance.md

@@ -0,0 +1,69 @@
+# 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.
+
+## Owner-reported live test — 2026-11-01
+
+The owner installed `psst-native` using the original scoped npm path and reported
+successful bidirectional Pi ↔ Antigravity messaging with model read receipts.
+This is meaningful native connectivity evidence for that tested pair, not an
+independent recording by this test suite or proof of all idle-wake/restart gates.
+Earlier missing-path/parser/owner-lock failures remain installation usability
+findings; the later same-path success means a universal `@` parser limitation
+must not be inferred. The read-only installation doctor now checks the actual
+root and gives the in-session slash command without source copying or policy changes.

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,50 @@
+# Explicit installation pairing
+
+> Legacy diagnostic/test reference only. Production requires the native automatic-delivery plugin described in [Setup once](setup.md). Do not configure manual pull as a production fallback. In the unreleased 0.4.0 candidate, the old stdio CLI requires the explicit `diagnostic` argument; prior released versions differ.
+
+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.