@matuto-ai/claude-code-broker-connector 0.0.0-stage → 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "psst-connectors",
+  "owner": {
+    "name": "Bruno Orsolon"
+  },
+  "plugins": [
+    {
+      "name": "psst",
+      "source": "./",
+      "description": "Psst messaging for Claude Code",
+      "version": "0.2.0"
+    }
+  ],
+  "metadata": {
+    "description": "Native Psst agent-messaging connector for Claude Code"
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "psst",
+  "version": "0.2.0",
+  "description": "Session-bound Psst agent messaging with explicit receive and acknowledgment. No permission relay or unsolicited prompts.",
+  "author": { "name": "Bruno Orsolon" },
+  "repository": "https://github.com/matuto-ai/claude-code-broker-connector",
+  "license": "MIT"
+}

package/.mcp.json

@@ -0,0 +1,5 @@
+{
+  "mcpServers": {
+    "psst": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/bin/plugin-mcp.mjs"] }
+  }
+}

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,105 @@
-# Temporary Holding Version
+# Psst for Claude Code
 
-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.
+Native Claude Code plugin for discovery, send, receive, explicit read acknowledgment,
+and delivery status through [Psst](https://github.com/matuto-ai/psst).
+Install **inside the existing Linux sandbox where Claude already runs**. No host
+launcher, new container, broker source checkout, API model key, or npm dependency
+is needed. The plugin uses the existing Claude login and normal permissions.
+
+## Install from GitHub
+
+After this PR merges, install from `main` (before merge, use
+`#chore/matuto-ai-npm-scope` instead):
+
+```sh
+claude plugin marketplace add matuto-ai/claude-code-broker-connector#main
+claude plugin install psst@psst-connectors
+```
+
+Once released, pin the reviewed release tag instead of the branch. This package
+is a private/custom marketplace, not a listing in Anthropic's official catalog.
+Review the plugin prompt before installing. Requires **Linux, Node 24.19+ within
+24.x on PATH**, and Claude Code with exec-form hooks (audited with 2.1.309).
+
+Configure the path to this client's private enrollment bundle before starting
+Claude normally:
+
+```sh
+export PSST_CONFIG_FILE=/absolute/private/claude-code/connection.json
+claude
+```
+
+Restart Claude after first installation/configuration. Hot-attachment to an
+already running TUI is not supported. `PSST_CLAUDE_CONFIG` overrides the common
+variable; without either, the plugin reads `~/.config/psst/claude.json`.
+[Custom configuration and troubleshooting](docs/integration.md).
+
+## Use
+
+Ask Claude to use Psst for the peers and purpose you authorize, or invoke `/psst:psst`.
+The native MCP tools are:
+
+- `broker_identity`: this exact session address.
+- `broker_list_clients`: discover authorized peers; select the exact `client_id`.
+- `broker_send`: send with a stable `send_key`; preserve it if the result is uncertain.
+- `broker_receive`: read the FIFO head and its opaque `receipt_token`.
+- `broker_acknowledge`: explicitly acknowledge that read using its `message_id`
+  and `receipt_token`, advancing to the next message.
+- `broker_message_status`: broker delivery state.
+- `broker_update_metadata`: descriptive name/project/model metadata.
+
+No model tokens are used for transport heartbeats or durable inbox storage.
+Mailbox reads are **cooperative**: incoming messages do not interrupt the user,
+wake an idle agent, inject terminal input, or grant permission. Agent content is
+always labeled untrusted AGENT data, including a peer's apparent “yes”.
+
+### What acknowledgment means
+
+Broker `delivered` means safely stored in the connector inbox. Local explicit
+acknowledgment means the model called `broker_acknowledge` with a receipt it saw.
+It is **not** proof that the requested work succeeded, human approval, or a
+native transcript persistence receipt. Lost responses are safe to retry with
+the same receipt. Unacknowledged messages remain pending, including across an
+MCP restart within the same confirmed native session/process lifetime.
+
+A new Claude process creates a new broker identity. After `/clear`, reconnect
+Psst through `/mcp` or restart Claude to register the new session. Old journals are
+retained rather than silently routing their messages into another conversation.
+No automatic replay into a different session is performed.
+
+## npm alternative
+
+The prepared npm package is `@matuto-ai/claude-code-broker-connector`, with the `psst-claude`
+CLI. Publication is a separate maintainer step; do not assume it is on npm yet.
+A source checkout can already be packed and installed locally:
+
+```sh
+npm pack
+npm install --prefix /your/private/tools ./matuto-ai-claude-code-broker-connector-0.2.0.tgz
+/your/private/tools/node_modules/.bin/psst-claude plugin-path
+```
+
+Add that printed directory with `claude plugin marketplace add <directory>`,
+then install `psst@psst-connectors` normally. The CLI also offers `config-example`
+and `doctor [absolute-config-path]`; it never writes credentials or changes
+Claude settings by itself. No postinstall scripts are used.
+
+## Maintainer checks
+
+```sh
+npm run check
+npm test
+npm pack --dry-run
+```
+
+Unit/pack tests are self-contained. `npm run test:integration` additionally needs
+the pinned Psst broker checkout at `../ai-agent-msg-broker`; CI provides it. Native
+plugin hooks, real broker transport, SQLite persistence, explicit multi-message
+ACK, MCP restart, and session shutdown are exercised by a synthetic native
+parent. [Verification details](docs/verification.md) distinguish this from a real
+logged-in Claude/model exchange, which must be tested by the operator.
+
+Bundled runtime source is unmodified and SHA256-checked against Psst commit
+`ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`, with MIT attribution. The older
+`bin/launch.mjs` exact-session launcher remains only as a compatibility fixture;
+the normal installation path above does not use it.

package/bin/cli.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { readPluginConfig, configPath } from '../src/plugin-state.mjs';
+import { verifyReference } from '../src/reference-pin.mjs';
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const [command, argument] = process.argv.slice(2);
+try {
+  if (command === 'plugin-path') console.log(root);
+  else if (command === 'config-example') console.log(JSON.stringify({brokerUrl:'https://broker.example.invalid',tokenFile:'/absolute/private/claude/token',stateRoot:'/absolute/private/claude/state',name:'claude-code',project:null},null,2));
+  else if (command === 'doctor') {
+    if(process.platform !== 'linux' || Number(process.versions.node.split('.')[0]) !== 24) throw new Error('linux_node_24_required');
+    verifyReference(join(root,'vendor','psst'));
+    readPluginConfig(argument ?? configPath());
+    console.log('Local configuration and bundled runtime are valid. No network request, credential read, or live Claude session was tested.');
+  } else if (!command || ['--help','help'].includes(command)) console.log('psst-claude plugin-path | config-example | doctor [absolute-config-path]\nNative installation: claude plugin marketplace add <plugin-path>, then claude plugin install psst@psst-connectors. Restart Claude after configuration.');
+  else throw new Error('unknown_command');
+} catch(error) { console.error(`psst-claude: ${/^[a-z0-9_]+$/.test(error.message)?error.message:'configuration_check_failed'}`);process.exitCode=1; }

package/bin/launch.mjs

@@ -0,0 +1,29 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { readPrivateJson, validateConfig, privateDirectory, launchFiles, writePrivateJson, processIdentity, markClosed } from '../src/launch-state.mjs';
+
+let runDirectory;
+try {
+  if (process.argv.length !== 3 || process.platform !== 'linux') throw new Error('usage_linux_launch_config');
+  const config = validateConfig(readPrivateJson(process.argv[2]));
+  const version = spawnSync(config.claudeBinary ?? 'claude', ['--version'], { encoding: 'utf8', timeout: 10000, maxBuffer: 4096 });
+  if (version.status !== 0 || version.stdout.trim().match(/^(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] !== config.expectedCliVersion) throw new Error('cli_version_mismatch');
+  privateDirectory(config.stateRoot);
+  runDirectory = join(config.stateRoot, randomUUID());
+  const adapterRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+  const { args } = launchFiles({ config, runDirectory, adapterRoot });
+  const close = () => { try { markClosed(runDirectory); } catch { /* Parent identity also expires. */ } };
+  process.once('exit', close);
+  // Inherit the real user's terminal, never synthesize keys, prompts or approvals.
+  const child = spawn(config.claudeBinary ?? 'claude', args, { stdio: 'inherit', shell: false });
+  if (!child.pid) throw new Error('cli_start_failed');
+  writePrivateJson(join(runDirectory, 'host.json'), processIdentity(child.pid));
+  const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', code => resolve(code ?? 1)); });
+  close(); process.exitCode = code;
+} catch {
+  try { if (runDirectory) markClosed(runDirectory); } catch { /* No implicit recovery. */ }
+  process.stderr.write('broker_launch_failed: use a private valid config and the exact installed CLI version; no automatic retry or permission override was applied.\n');
+  process.exitCode = 1;
+}

package/bin/mcp.mjs

@@ -0,0 +1,49 @@
+import { verifyReference } from '../src/reference-pin.mjs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readPrivateJson, validateConfig, verifyLaunch, observedModel, closed } from '../src/launch-state.mjs';
+import { createClaudeSessionBridge } from '../src/session-bridge.mjs';
+
+let bridge, inbox, monitor;
+try {
+  if (process.argv.length !== 3) throw new Error('invalid_mcp_arguments');
+  const run = process.argv[2], config = validateConfig(readPrivateJson(join(run, 'config.json'))), expected = readPrivateJson(join(run, 'launch.json'));
+  verifyReference(config.referenceRoot);
+  const load = path => import(pathToFileURL(join(config.referenceRoot, path)).href);
+  const [{ Inbox, newSessionIdentity }, { BrokerClient }, { AdapterRuntime }, { createTools }, { serveStdio }] = await Promise.all([
+    load('reference/inbox.mjs'), load('reference/client.mjs'), load('reference/runtime.mjs'), load('reference/tools.mjs'), load('reference/mcp-stdio.mjs'),
+  ]);
+  const identity = newSessionIdentity('claude-code');
+  // A restarted MCP subprocess gets a fresh identity and never adopts old pending
+  // mail. The previous journal is preserved for explicit operator reconciliation.
+  inbox = new Inbox({ directory: join(run, `inbox-${identity.client_id}`), identity });
+  let alive = true;
+  const lifetime = {}, binding = { nativeSessionId: expected.sessionId, lifetime };
+  const current = () => ({ ...binding, alive: alive && verifyLaunch(run, expected) });
+  const client = new BrokerClient({ url: config.brokerUrl, tokenFile: config.tokenFile, caFile: config.caFile,
+    insecureDevelopment: config.insecureDevelopment === true, inbox });
+  const runtime = new AdapterRuntime({ client, inbox, verifySession: () => current().alive, isAlive: () => current().alive });
+  bridge = createClaudeSessionBridge({ reference: { createTools, serveStdio }, client, inbox, runtime,
+    binding, getCurrentBinding: current, input: process.stdin, output: process.stdout,
+    observeMetadata: () => ({ model: observedModel(run) }),
+    onDiagnostic: ({ code }) => process.stderr.write(`${code}\n`),
+  });
+  process.stdin.once('end', () => { alive = false; });
+  // MCP discovery can finish while the native SessionStart hook runs. No broker
+  // registration, heartbeat, or tool effect occurs before that confirmation.
+  const deadline = Date.now() + 30000;
+  while (!current().alive) {
+    if (!alive || closed(run) || Date.now() >= deadline) throw new Error('session_confirmation_unavailable');
+    await delay(25);
+  }
+  await bridge.start({ name: config.name, project: config.project ?? null, model: observedModel(run) });
+  monitor = setInterval(() => { if (!current().alive) { alive = false; void bridge.close(); } }, 250);
+  await bridge.done;
+} catch {
+  process.stderr.write('broker_mcp_unavailable: exact session confirmation or transport failed; pending inbox content was not consumed.\n');
+  process.exitCode = 1;
+} finally {
+  if (monitor) clearInterval(monitor);
+  await bridge?.close(); inbox?.close();
+}

package/bin/native-hook.mjs

@@ -0,0 +1,12 @@
+import { applyHook, markClosed } from '../src/launch-state.mjs';
+let bytes = 0, chunks = [];
+try {
+  if (process.argv.length !== 3) throw new Error('invalid_hook_arguments');
+  for await (const chunk of process.stdin) { bytes += chunk.length; if (bytes > 256 * 1024) throw new Error('hook_input_too_large'); chunks.push(chunk); }
+  const result = applyHook(process.argv[2], JSON.parse(Buffer.concat(chunks).toString('utf8')));
+  if (result) process.stdout.write(JSON.stringify(result) + '\n');
+} catch {
+  try { if (process.argv[2]) markClosed(process.argv[2]); } catch { /* Fail closed through missing/unreadable state. */ }
+  process.stderr.write('broker_hook_failed: adapter binding is closed; review the private launch state.\n');
+  process.exitCode = 2;
+}

package/bin/plugin-hook.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { readPluginConfig, pluginHook } from '../src/plugin-state.mjs';
+try {
+  let size=0; const chunks=[];
+  for await (const chunk of process.stdin) { size+=chunk.length; if(size>256*1024) throw new Error('hook_too_large'); chunks.push(chunk); }
+  const result=pluginHook(readPluginConfig(),JSON.parse(Buffer.concat(chunks).toString('utf8')));
+  if(result) process.stdout.write(JSON.stringify(result)+'\n');
+} catch {
+  process.stderr.write('psst_hook_unavailable: check private plugin configuration and Node 24; no permission was granted.\n');
+  process.exitCode=2;
+}

package/bin/plugin-mcp.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writeFileSync } from 'node:fs';
+import { readPrivateJson, privateDirectory } from '../src/launch-state.mjs';
+import { verifyReference } from '../src/reference-pin.mjs';
+import { readPluginConfig, hostDirectory, readBinding, verifyBinding, bindingModel } from '../src/plugin-state.mjs';
+
+let server, runtime, inbox, monitor, live=true, closeSessionOnExit=true;
+try {
+  const root=dirname(dirname(fileURLToPath(import.meta.url))), reference=join(root,'vendor','psst');
+  verifyReference(reference);
+  const [{Inbox,newSessionIdentity},{BrokerClient},{AdapterRuntime},{createTools},{createCooperativeInbox},{serveStdio}]=await Promise.all([
+    import('../vendor/psst/reference/inbox.mjs'),import('../vendor/psst/reference/client.mjs'),import('../vendor/psst/reference/runtime.mjs'),import('../vendor/psst/reference/tools.mjs'),import('../src/cooperative-inbox.mjs'),import('../src/cooperative-stdio.mjs')]);
+  const config=readPluginConfig(),{directory,host}=hostDirectory(config);
+  let expected=null, started=false;
+  const active=()=>live && expected && verifyBinding(directory,expected);
+  const unavailable=()=>({error:{code:'session_binding_unavailable',retryable:true,effect:'not_applied',message:'Psst awaits the native SessionStart hook. Restart Claude after installing/configuring the plugin.'}});
+  let tools=null;
+  // Initialize MCP immediately; tools have no effect until native hook confirmation.
+  const names=['broker_list_clients','broker_send','broker_update_metadata','broker_message_status','broker_receive','broker_acknowledge','broker_identity'];
+  const guarded=Object.fromEntries(names.map(name=>[name,async args=>{
+    if(!started || !active()) return unavailable();
+    return tools[name](args);
+  }]));
+  server=serveStdio({input:process.stdin,output:process.stdout,tools:guarded,onClose:async()=>{closeSessionOnExit=!active();live=false;await runtime?.stop({closeSession:closeSessionOnExit});},onDiagnostic:()=>{}});
+  const deadline=Date.now()+30000;
+  while(live && !expected) {
+    try { const binding=readBinding(directory);if(binding.host.pid===host.pid && verifyBinding(directory,binding)) expected=binding; } catch { /* Hook and MCP startup ordering can vary. */ }
+    if(!expected) {if(Date.now()>=deadline) throw new Error('session_confirmation_timeout');await delay(25);}
+  }
+  if(!live) throw new Error('mcp_closed');
+  const journal=privateDirectory(join(directory,`inbox-${expected.lifetime}`));
+  const identityFile=join(journal,'identity.json');
+  try {writeFileSync(identityFile,JSON.stringify(newSessionIdentity('claude-code'))+'\n',{mode:0o600,flag:'wx'});} catch(error) {if(error.code!=='EEXIST')throw error;}
+  const identity=readPrivateJson(identityFile);
+  inbox=new Inbox({directory:journal,identity});
+  const client=new BrokerClient({url:config.brokerUrl,tokenFile:config.tokenFile,caFile:config.caFile,insecureDevelopment:config.insecureDevelopment===true,inbox});
+  runtime=new AdapterRuntime({client,inbox,verifySession:active,isAlive:active,onDiagnostic:({code})=>process.stderr.write(`psst_${code}\n`)});
+  tools={...createTools({client,inbox,observeMetadata:()=>({model:bindingModel(readBinding(directory))})}),...createCooperativeInbox({inbox,isActive:active}),
+    broker_identity:async()=>({client_id:identity.client_id,client_type:'claude-code',native_session_id:expected.sessionId,local_mode:'cooperative_pull',automatic_wakeup:false})};
+  await runtime.start({name:config.name,project:config.project??null,model:bindingModel(expected)});
+  if(!active()) throw new Error('session_changed');
+  started=true;
+  monitor=setInterval(()=>{if(!active()){live=false;void server.close();}},250);
+  await server.done;
+} catch {
+  process.stderr.write('psst_mcp_unavailable: check Node 24, private config/token, HTTPS access, and restart Claude with the native plugin. No pending message was implicitly acknowledged.\n');
+  process.exitCode=1;
+} finally {
+  live=false;if(monitor)clearInterval(monitor);
+  await server?.close();await runtime?.stop({closeSession:closeSessionOnExit});inbox?.close();
+}

package/docs/integration.md

@@ -0,0 +1,99 @@
+# Native Claude integration
+
+## Configuration
+
+Use one client's enrollment bundle, not another client's token. `PSST_CONFIG_FILE`
+may point directly to `connection.json` in `broker-client-bundle-v1` format. It must
+allow `claude-code`; `token_file` resolves relative to that JSON file. State goes
+in its adjacent `state/` directory. The broker URL is HTTPS; ordinary system CA
+validation applies. No TLS override or custom CA is needed for public certificates.
+
+Alternatively, create a private JSON config at `~/.config/psst/claude.json` or set
+`PSST_CLAUDE_CONFIG` to its absolute path:
+
+```json
+{
+  "brokerUrl": "https://broker.example.invalid",
+  "tokenFile": "/absolute/private/claude/token",
+  "stateRoot": "/absolute/private/claude/state",
+  "name": "claude-reviewer",
+  "project": "example-project"
+}
+```
+
+JSON and token files must belong to the sandbox user and have mode `0600`; state
+must be an owned, nonsymlink, private `0700` directory. Keep it on persistent local
+storage, not NFS/CIFS. Optional `caFile` is an absolute path for a private CA. The
+`insecureDevelopment` option only permits loopback HTTP, for disposable tests.
+Do not put tokens in JSON, shell arguments, README files, or repository settings.
+
+`PSST_CLAUDE_CONFIG` wins over `PSST_CONFIG_FILE`. The native hook and MCP subprocess
+must inherit the same variables. Install Node 24 inside the sandbox or place its
+existing executable first on PATH before launching Claude; this does not require
+a global Node upgrade on the host. The plugin never creates or migrates credentials.
+
+## Native lifecycle and isolation
+
+Claude's documented exec-form hooks run `node bin/plugin-hook.mjs` directly.
+The MCP stdio subprocess is also launched directly by Claude. Their parent PID,
+Linux process start counter, and boot identity select a private host directory.
+SessionStart records the native session ID and an opaque lifetime; MCP waits up to
+30 seconds for it, while still answering the protocol initialization handshake.
+A host lacking the same direct-parent relationship fails closed instead of guessing
+by project, process name, transcript path, or most recent session. The real native
+exec relationship is checked by the compatibility audit, not a generic MCP promise.
+
+Normal compaction with the same native session preserves the lifetime. SessionEnd
+closes it. After `/clear` or another native session switch, reconnect Psst through `/mcp`
+or restart Claude; the old MCP intentionally stops instead of rebinding silently.
+Session switch invalidates the old binding; old messages are never
+adopted by the new session. PreToolUse can only deny wrong-session and subagent
+access to Psst tools; it never auto-approves tool usage. No permission-relay or
+Channels capability is advertised. State includes no model credentials or transcript.
+
+An MCP restart while the same native host and lifetime remain live can reopen the
+same SQLite journal and broker lease. The OS ownership lock prevents concurrent
+MCP processes from owning it. A new host/lifetime always gets a separate identity.
+A hard native crash falls back to broker lease expiry. Durable old journal files
+remain for operator inspection; do not copy them into another live session.
+
+## Test with a peer
+
+1. Enroll/configure both clients and restart their native sessions.
+2. In Claude ask for `broker_identity`, then `broker_list_clients`.
+3. Select the other client's exact UUID. Send a short test with a unique stable
+   `send_key`. Do not select by a duplicate display name alone.
+4. At the recipient, call receive, inspect the labeled AGENT text, then explicitly
+   acknowledge its message ID and receipt token. Call receive again to verify FIFO
+   advancement. Ask for a reply to the original Claude UUID.
+5. In Claude receive/ack the reply. Status `delivered` is storage, not a completed task.
+
+A healthy `/healthz` alone does not establish authentication or successful messaging.
+Ordinary native MCP approval prompts are for the human to handle. If a tool response
+is uncertain, preserve operation identifiers rather than sending a new operation.
+
+## Troubleshooting and uninstall
+
+- `psst_hook_unavailable`: private config path, Node version/PATH, directory/file
+  permissions, or unsupported native parent relationship. Restart after fixing it.
+- `session_binding_unavailable`: SessionStart has not confirmed this exact native
+  process/session, or it changed. Do not reuse someone else's state directory.
+- `psst_unauthenticated` / `psst_forbidden`: check enrollment and client type/scope.
+- No new message while idle: expected. Ask for a cooperative receive; there is no wakeup.
+- Duplicate receive: expected until explicit acknowledgment. Retry ACK with the exact
+  same receipt after an uncertain result; never invent a receipt or delete pending rows.
+
+Disable/remove through Claude's normal plugin manager:
+
+```sh
+claude plugin uninstall psst@psst-connectors
+```
+
+Then close/restart affected sessions. This does not revoke broker credentials or
+delete the private external state directory. Revoke credentials separately when
+needed; retain pending journals until reconciled. Do not install both the legacy
+wrapper and native plugin in the same session.
+
+Official references: [plugins](https://code.claude.com/docs/en/discover-plugins),
+[plugin manifest](https://code.claude.com/docs/en/plugins-reference),
+[hooks](https://code.claude.com/docs/en/hooks), [MCP](https://code.claude.com/docs/en/mcp).

package/docs/publishing.md

@@ -0,0 +1,35 @@
+# Distribution and npm publishing
+
+The supported native Claude marketplace install works directly from the reviewed
+GitHub branch/tag. npm is optional; it distributes the same self-contained plugin
+files and helper CLI, not a separate model client.
+
+The npm package is prepared as `@matuto-ai/claude-code-broker-connector` version `0.2.0`.
+No package is published by this change. This is a new npm identity under the
+`@matuto-ai` organization, not a transfer or deprecation of the unscoped package.
+The owner must verify organization publishing rights before first publication.
+Native plugin `psst`, marketplace `psst-connectors`, and CLI `psst-claude` remain unchanged.
+
+The release-triggered workflow follows the existing pi-intercom-review-pair
+trusted-publishing pattern, adding version matching, full tests, pack/install
+checks, pinned Actions, and an integration gate before publishing. It does not
+store an npm token in this repository.
+
+For the scoped npm package, configure npm's GitHub Actions trusted publisher for:
+- GitHub owner: `matuto-ai`
+- Repository: `claude-code-broker-connector`
+- Workflow filename: `npm-publish.yml`
+
+Creating/configuring that publisher is an account-security action for the owner.
+If npm requires an initial package publication before a trusted publisher can be
+configured, complete that one-time bootstrap in your authenticated npm environment.
+Do not paste a token into chat or into a committed workflow. The workflow cannot
+magically create publisher permissions.
+
+After reviewing and merging the PR, create release `v0.2.0` from the reviewed
+commit. The tag must match package.json. Tests run first, then npm publication
+uses short-lived OIDC and provenance. Verify the Actions run and npm package
+version before giving users npm install instructions. Native GitHub installation
+does not require waiting for npm.
+
+Official documentation: https://docs.npmjs.com/trusted-publishers/

package/docs/verification.md

@@ -0,0 +1,123 @@
+# Native plugin verification — October 24, 2026
+
+The `0.2.0` native plugin replaces the wrapper-only installation path described
+in the historical notes below. The legacy wrapper remains tested but is not the
+normal operator entry point.
+
+On cloud Linux, Node 24.22.1:
+
+- Syntax checks passed for all adapter and vendored modules.
+- Unit tests cover native binding/lifecycle, config bundle restrictions, source
+  pins, stdio boundaries, explicit cooperative acknowledgment, malformed/unread/
+  departed/uncertain message rejection, durable receipt retries and storage faults.
+- A real `npm pack` artifact was installed offline with scripts disabled into an
+  empty temporary prefix. Native manifests/hooks/MCP/runtime/license were present;
+  helper CLI and local doctor ran without a sibling broker checkout or network call.
+- Two real-broker integration tests passed, including native-plugin startup before
+  SessionStart, multiple messages, exact receipt acknowledgment, reply, same-native-
+  session MCP restart preserving identity/inbox, and native SessionEnd closure.
+  Their native parent is synthetic, not a logged-in Claude model session.
+- Official Claude Code **2.1.309** (`@anthropic-ai/claude-code-linux-x64`) validated
+  the native plugin/marketplace manifest. The only remaining warning is cosmetic:
+  no directory listing icon. This is not a marketplace approval claim.
+- With a fresh isolated HOME and **no authentication/model credentials**, actual
+  Claude `--plugin-dir ... --init-only` launched an instrumented MCP process and
+  exec-form SessionStart hook. Both reported the same native Claude parent PID and
+  Linux process-start identity; SessionStart supplied the real native session UUID.
+  This verifies the critical direct-parent binding assumption, independently of
+  synthetic transport tests. A repeatable `scripts/audit-native.mjs` probe accepts
+  an existing official executable via `CLAUDE_AUDIT_BIN` and makes no model request.
+
+```sh
+CLAUDE_AUDIT_BIN=/absolute/path/to/claude npm run audit:claude
+```
+
+Shared runtime hashes remain byte-identical to the reviewed Psst commit below.
+The separately attributed adapter files add explicit application read ACK and
+bounded MCP tool schemas; **they do not fabricate native acceptance receipts**.
+
+Not tested here: authenticated Claude/model round-trip in Bruno's sandbox,
+permission UI, his TLS/token mounts, all Claude versions, non-Linux platforms,
+or automatic wakeup. Those are not implied by health checks or the native ABI
+probe. Restart after installation; after `/clear`, reconnect Psst or restart.
+No user credentials, production configuration, npm release or main merge occurred.
+
+## Historical wrapper foundation evidence
+
+
+2026-10-23 cloud Linux, Node 24.19.0 / SQLite 3.53.3:
+`npm run check` and **12/12 tests passed** against shared broker commit
+`ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`.
+
+The end-to-end fixture spawns a **synthetic Claude CLI**, real native-hook helper
+processes, the real standard MCP subprocess, shared HTTP broker and SQLite inbox.
+It checks lifecycle confirmation, exact ownership, delivery ACK, model-visible
+AGENT warning, cooperative non-consumption and clean native shutdown. Focused
+tests cover main/subagent guards, unknown/switched lifetime, PID reuse defense,
+model metadata, EOF during registration, bounded arguments and tamper-rejected
+reference source. The fake executable's `0.0.0` version is not a vendor version.
+
+Not run: actual authenticated Claude TUI/broker flow, provider calls, real permission
+UI, native hook ordering under clear/resume/compact/model switch, rootless Podman
+or two-host TLS LAN. Ordinary MCP tools may require human approval; none was
+bypassed. This PR is not a full issue #9 completion claim.
+
+Required next gates:
+
+1. Pin an official CLI version and verify all launch/hook events against it,
+   including root session and subagent tool routing and MCP restart.
+2. Confirm actual provider-visible tool-result provenance with hostile body text
+   (`yes`, fake channel boundaries and prompt-injection strings).
+3. Keep human drafts, active work and approvals untouched. Cooperative tools are
+   invoked only in native flow; no automatic event may inject a prompt.
+4. Establish a supported durable native acceptance receipt before consuming any
+   inbox head. Channel opt-in alone is insufficient and permission relay must
+   remain disabled.
+5. Package and test separate CLI+adapter rootless containers and two-host LAN.
+
+
+## Official Claude 2.1.309 compatibility audit
+
+On 2026-10-23, the official npm packages `@anthropic-ai/claude-code@2.1.309`
+and `@anthropic-ai/claude-code-linux-x64@2.1.309` were unpacked in a disposable
+cloud directory with npm lifecycle scripts disabled. No user installation,
+credentials, login, model request or existing configuration was used.
+
+The actual native Linux x64 executable reported `2.1.309 (Claude Code)` and
+internal commit `1ce7e4ff2da8`. Its SHA256 was:
+
+```text
+4d704a8aecbe038affa3000f498ae17c1b4f753add8facb8764120affc99b658
+```
+
+Verified with a fresh private HOME and empty test project:
+
+1. Actual `--help` lists `--session-id`, `--settings` and `--mcp-config`. The
+   version output matches the existing launcher's exact-version check.
+2. `claude --settings <generated-settings.json> doctor` accepted the launcher's
+   SessionStart/SessionEnd/PostModelSwitch/PreToolUse hook configuration. A
+   negative control changing `args` from an array to a number produced an explicit
+   invalid-settings diagnostic. Doctor exits zero even for that diagnostic, so
+   the output—not exit code alone—was checked.
+3. `claude --settings <isolated-setup-hook.json> --init-only` executed a Setup hook
+   with the same `command` plus `args` form. One argument containing spaces,
+   apostrophe, dollar sign, semicolon and backtick arrived unchanged. It exited
+   zero without authentication or a model call. This verifies exec-form mechanics;
+   it does not claim that Setup is an adapter lifecycle event.
+
+This agrees with the official [hook exec-form reference](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form)
+and [CLI flags reference](https://code.claude.com/docs/en/cli-reference#cli-flags).
+No runtime source change was needed. Shared reference pin and the 12-test
+synthetic/real-broker fixture coverage above are unchanged.
+
+For a user-local test, set `expectedCliVersion` to `2.1.309` and `claudeBinary`
+to the absolute installed executable path in each private adapter config. Launch
+`bin/launch.mjs` with an explicit Node 24.19.0 executable: that exact Node path is
+propagated to hooks and MCP subprocesses, without changing global Node. Use two
+fresh interactive sessions with separate state directories/names, and approve
+ordinary native MCP prompts yourself. See [launch configuration](integration.md).
+
+**Still unverified by this audit:** authenticated SessionStart-to-MCP ordering,
+actual two-session broker/model exchange, permission UI, clear/resume/compact and
+subagent routing in the real TUI. There were no live broker or model calls in this
+compatibility audit. The adapter still peeks rather than consumes its inbox.