@matuto-ai/claude-psst-connector 0.0.0-stage → 0.7.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.7.0"
+    }
+  ],
+  "metadata": {
+    "description": "Native Psst agent-messaging connector for Claude Code"
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "psst",
+  "version": "0.7.0",
+  "description": "Session-bound Psst agent messaging with explicit receive and acknowledgment. Bounded opt-in native notices; no permission relay.",
+  "author": {
+    "name": "Bruno Orsolon"
+  },
+  "repository": "https://github.com/matuto-ai/claude-psst-connector",
+  "license": "MIT",
+  "userConfig": {
+    "broker_url": {
+      "type": "string",
+      "title": "Psst broker URL",
+      "description": "HTTPS broker origin. Explicit setup requests administrator approval once; ordinary startup only reconnects a saved approved installation.",
+      "required": false,
+      "default": ""
+    }
+  }
+}

package/.mcp.json

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

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,288 @@
-# 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.
+> **Unreleased 0.7.0 release candidate.** This version moves to `@matuto-ai/claude-psst-connector`. The previous package remains available; no existing installation changes automatically. Use the versioned commands only after the new publication is verified. See [migration checklist](docs/migration-0.6.0.md).
+
+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.
+
+## Before installation
+
+Use the exposed launcher and native plugin manager only. If you only have the
+in-session `!` shell, use it for npm and the read-only doctor below, then use
+Claude’s `/plugin` UI; do not start a nested interactive Claude or use
+`--plugin-dir` startup flags. Package installation is not native MCP readiness.
+
+If `psst-connectors` already exists, stop before adding a different source.
+The [managed installation guide](docs/managed-native-installation.md) provides
+the identity-preserving npm catalog entry, read-only ownership diagnostics,
+supported upgrade workflow and the later owner-machine integration checks.
+
+## Install from GitHub
+
+After release `v0.7.0` is published, install the pinned release:
+
+```sh
+claude plugin marketplace add matuto-ai/claude-psst-connector#v0.7.0
+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.310).
+
+After installing, open Claude normally and configure just **broker_url** in the
+native `/plugin` configuration dialog. No pairing-secret field, copied token or
+per-session connection file is required. Close the panel and verify its reload
+applied; if necessary run `/reload-plugins` inside Claude or start a fresh session.
+Then explicitly run `/psst:connect` once. It requests access from an approval-capable
+Psst broker. The broker owner logs into its `/admin` form and approves the exact
+installation request. A URL alone is not authorization.
+
+The connector generates and privately persists its candidate before contacting
+the broker. While pending it cannot use messaging. Approval connects automatically;
+future sessions reuse that installation authorization with independent client IDs
+and inboxes. A transient error from the initial setup request keeps the original
+error visible while the host checks the same saved pending request, respecting
+server backoff. It never automatically submits another request. If Claude
+restarts while pending, it only checks the same durable
+request: no new key or enrollment POST. Denial/expiry stop the attempt.
+
+Explicit replacement uses `/psst:connect` with an explicit replacement request;
+the old connection stays usable until the new approval attaches and selection is
+safely committed. Cancel setup only stops this session's pending attachment; it
+does not revoke shared access. Existing private bundles remain an advanced legacy
+path, not the primary onboarding flow. See [persistence and limits](docs/installation-selection.md).
+
+No environment-variable setup, extra agent or new container is required. The
+plugin must be loaded before a genuine native SessionStart; its MCP tools can be used while disconnected **only when the native host actually
+loads the plugin MCP server**. Verify Psst appears in `/mcp`; hooks and skills
+alone do not establish that. Existing sessions can reload the plugin, but a
+reload does not fabricate native session binding. Existing private bundles work;
+[private pairing files](docs/pairing.md) are optional when the broker supports them.
+Legacy environment/default-file configuration remains supported; see
+[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_setup`: explicitly request administrator approval using the configured URL; optional `replace: true` requires explicit replacement intent.
+- `broker_setup_status`: read local status without a network or model polling loop.
+- `broker_setup_cancel`: cancel this session’s pending setup, preserving existing access.
+- `broker_connect`: activate this session using a private connection JSON file.
+- `broker_disconnect`: stop transport without acknowledging unread messages.
+- `broker_identity`: this exact session address.
+- `broker_list_clients`: discover authorized peers; select the exact `client_id`.
+- `broker_send`: send to an exact recipient; technical retry keys stay private; inspect outgoing history after uncertainty.
+- `broker_receive`: read the FIFO head with its private receipt kept inside the connector.
+- `broker_acknowledge`: explicitly acknowledge that read using its `message_id`
+  (the connector resolves the previously exposed receipt internally), 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.
+A native plugin monitor starts automatically in every interactive Claude session on
+2.1.310+. Its bounded, body-free mailbox notices let Claude receive and explicitly
+acknowledge messages without a user polling prompt. No terminal input is injected
+and no permission is granted. Agent content remains untrusted AGENT data.
+**Production requires automatic delivery; do not treat manual pull as a fallback.**
+If the native monitor/MCP is absent, readiness is blocked.
+**Prototype:** authenticated native wakeup is not yet certified;
+[see delivery limits and evidence](docs/automatic-delivery.md).
+
+### What acknowledgment means
+
+Broker `delivered` means safely stored in the connector inbox. Local explicit
+acknowledgment means the model called `broker_acknowledge` for the exact message
+it read; the connector keeps the matching receipt private.
+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 `message_id`. Unacknowledged messages remain pending, including across an
+MCP restart within the same confirmed native session/process lifetime.
+
+`read_acknowledgment: confirmed` completes that message's read acknowledgment.
+`native_injection_receipt: not_provided_by_this_delivery_mode` describes a
+capability this monitor-plus-tool flow does not provide, **not** failed delivery
+or a missing user validation step. Identity/setup `readiness: monitor_observed`
+reports only the local monitor observation; it does not certify task execution.
+Unread-message reminder limits survive a same-lifetime monitor restart. A failed
+private reminder checkpoint blocks automatic readiness without consuming messages;
+see [durable reminder limits](docs/automatic-delivery.md#limits-and-failure-behavior).
+See the [response-field mapping](docs/automatic-delivery.md#read-ack-and-status-fields)
+for older diagnostic consumers.
+
+A new native session receives its own broker identity. The native MCP transport
+stays available while a verified `/clear`/`/new` transition retires the old runtime
+and attaches the new lifetime using saved approved configuration. A same-lifetime
+compact retains the identity and inbox. Old journals and uncertain work stay with
+their original lifetime; no cross-session replay or implicit enrollment occurs.
+If native tools are missing, use the bounded `/mcp` recovery above rather than
+starting a second server. Monitor availability is checked independently.
+See [native lifetime boundaries](docs/native-lifetime.md) for validation scope.
+
+Use `/psst:disconnect` to stop fetching; pending inbox messages remain local.
+An explicit reconnect within the same native lifetime resumes them. Broker
+presence can remain until lease expiry. Legacy journal connection paths remain
+pinned; explicit replacement enrollment after disconnect uses a separate
+credential-bound journal and never silently adopts old pending messages.
+
+## npm alternative
+
+After npm publication is verified, install the released package into a private
+local tools directory (reuse your existing prefix when updating):
+
+```sh
+npm install --prefix "$HOME/.local/share/psst-claude" --ignore-scripts --no-audit --no-fund @matuto-ai/claude-psst-connector@0.7.0
+"$HOME/.local/share/psst-claude/node_modules/.bin/psst-claude" doctor
+```
+
+The read-only doctor needs no connection file. It checks Node **>=24.19 and <25**,
+the bundled runtime, observed plugin-MCP suppression and the documented native
+marketplace listing. It prints the exact native install or update step for this
+package. It never writes registration, settings or credentials. Exit 2 means a
+restriction/source conflict or unavailable inspection; exit 1 means an invalid
+package/runtime/configuration. Exit 0 means only local checks passed, **not** native
+readiness. If the launcher cannot list sources from `!`, use `/plugin` directly.
+
+For a **fresh** local source, the printed native command is:
+
+```text
+/plugin install psst --marketplace <printed-package-root>
+```
+
+For an **existing source backed by this same npm directory**, keep the prefix
+across upgrades, refresh `/plugin marketplace update psst-connectors`, then use
+`/plugin manage` to update Psst at its existing scope. If `psst-connectors` points
+elsewhere (including an existing managed local source), doctor stops: an npm
+install in another prefix does not update it. Its administrator must update the
+approved persistent source. Do not overwrite it, remove/re-add the marketplace,
+create a duplicate or bypass restricted Git. Shared source/bootstrap upgrades
+remain an administrator integration step, not an automatic connector migration.
+
+After native installation/update, use a fresh session for genuine SessionStart.
+Verify the exact version in `/plugin list` and actual Psst attachment in `/mcp`,
+then `/plugin configure psst@psst-connectors` → broker URL → `/psst:connect`.
+If MCP is missing, stop there: a standalone server smoke test is not attachment.
+A reported `CLAUDE_CODE_SKIP_PLUGIN_MCP_SERVERS` restriction needs administrator
+review at its approved source, not a flag override or a parallel MCP registration.
+The doctor deliberately distinguishes an inherited flag from a setting observed
+on disk; neither its absence nor readable settings prove effective host policy.
+No repeated reload/restart loop is needed without new evidence.
+
+The local npm path avoids Git distribution, but does not bypass native permission,
+source ownership or sandbox policy. Real launcher compatibility and authenticated
+native setup/arrival still need acceptance testing. No postinstall scripts run.
+`doctor [absolute-config-path]` additionally validates an explicitly selected
+legacy configuration without reading its credential file.
+
+## Maintainer checks
+
+```sh
+npm run check
+npm test
+npm pack --dry-run
+```
+
+The checkout is self-contained: Node 24.19.0 or later in the Node 24 line is
+all that is needed. `npm test` runs focused unit tests of connector behavior
+using in-memory streams, injected collaborators and temporary private files.
+It needs no Psst checkout, network service, Claude binary, credentials or Docker.
+`npm pack` runs syntax checks and the unit suite through `prepack`.
+[Verification details](docs/verification.md) describe the coverage and its limits.
+
+Bundled runtime source is unmodified and SHA256-checked against Psst commit
+`ba2219cd87a1feac23e01b23d2c2b3d3bdd65359`, with MIT attribution. The older
+`bin/launch.mjs` exact-session launcher remains for compatibility;
+the normal installation path above does not use it.
+
+### Private pairing files
+
+The same `/psst:connect /absolute/private/file.json` command accepts an operator-issued pairing file or an existing connection bundle. Never paste a secret into chat. See [pairing requirements, retry behavior and credential isolation](docs/pairing.md).
+
+## Installation-scoped automatic attachment
+
+See [installation selection](docs/installation-selection.md) for native `broker_url` configuration,
+`PSST_BROKER_URL` fallback, persistence under `CLAUDE_CONFIG_DIR`, automatic attachment
+of new sessions, and the limits of legacy external bundles. Each native session
+still has its own client ID/inbox. The monitor uses the official always-start
+trigger. Actual authenticated dialog-to-MCP handoff and native delivery acceptance
+remain unverified; fixture tests are not a claim of live model acceptance.
+
+Outgoing history, content, explicit resend and cancellation: [candidate contract](docs/message-lifecycle.md).
+
+[Candidate verification and deferred integration](docs/candidate-verification.md).
+
+### Readable received messages
+
+Native `broker_receive` shows a clearly labeled message from another agent with
+a readable multiline body, not nested JSON. The original machine result stays
+in `structuredContent`; exact routing/ACK IDs remain in text as well. The host
+controls whether tool output is collapsed: this does not create an assistant
+message or guarantee an always-open card. See [format, compatibility and limits](docs/receive-presentation.md).
+
+## Verification
+
+See [focused verification](docs/verification.md) for the syntax/unit checks and the later owner-machine integration session.
+
+### Shared project label
+
+The project label is descriptive metadata, not a routing or authorization field.
+The connector reads only `AI_AGENTS_SANDBOX_PROJECT_NAME` by default. To select a
+different local environment variable, set `PSST_PROJECT_ENV=MY_PROJECT_LABEL`.
+This option contains the variable **name**, not its value; never select a secret.
+Where a local connector configuration object is supported, `projectEnv` supplies
+the same selector; `PSST_PROJECT_ENV` overrides it. An explicit nonempty `project`
+label takes precedence. No credential/enrollment bundle fields are changed.
+Labels must be well-formed, at most 256 characters, and contain no control/bidi
+characters. Missing/blank values use a native directory basename where available,
+otherwise remain unknown; absolute paths and the complete environment are not sent.
+
+Model metadata continues to come from the native host, not the project setting.
+Readable presentation shows model ID and project, not the provider; protocol and
+stored provenance remain unchanged. This common configuration is being rolled out
+across connectors; Antigravity adoption remains pending, not implemented here.
+
+## Offline-delivery transport notices
+
+On compatible Psst brokers, the native monitor also announces prolonged-offline
+pending delivery. Read `broker_presence_events`, then explicitly acknowledge the
+exact event IDs you read with `broker_acknowledge_presence_event`. Notices contain
+only transport metadata, never message bodies or a reply deadline. They do not
+resend, cancel, close, or acknowledge any message automatically. See the
+[durable bounds, recovery and validation limits](docs/presence-notices.md).
+
+
+## Explicit reauthorization
+
+Use **/psst:reauthorize** to request replacement installation authorization:
+command → confirm the displayed configured HTTPS broker → new public request ID
+→ administrator approves that ID at `/admin` → native attachment and selection.
+`/psst:connect` reconnects saved access; it does not request replacement.
+
+Pending, approved-but-not-connected, and connected are distinct outcomes.
+Existing working access and old journals/unread messages are retained until the
+candidate attaches and is safely selected. Revoked access is not working access.
+A new credential-bound address never replays the old inbox. Replacement does
+**not** revoke the old credential: manual revocation in Psst admin is a separate
+human action, not a prerequisite. This command never accesses admin automatically.
+
+Repeat the command to resume the same pending candidate after cancellation,
+restart or uncertain response. For an approved candidate that failed attachment,
+choose retry attachment or explicitly request a new approval if necessary. Cancellation stops this native
+session's intent only. Preserve state and locks; use the public request ID for
+admin diagnosis. Do not run a separate MCP server or fabricate session binding.
+Missing native tools require `/psst:connect`'s bounded native MCP diagnostics.
+
+**Execution cost:** `/psst:reauthorize` is a user-invoked native plugin skill.
+Claude executes its fixed instructions and tool calls in a model turn; it is not
+token-free. Host-owned approval polling does not consume repeated model turns.
+The owner accepted this trade-off for discoverability. The newer Claude Mods
+command API offers deterministic dispatch, but its compatibility with the owner's
+installed host has not been verified and this change does not require it.
+
+See [command contract and verification](docs/reauthorization.md).

package/bin/cli.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { supportedRuntime, pluginMcpDiagnostic, inspectNativeInstallation } from '../src/preflight.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(!supportedRuntime()) throw new Error('linux_node_24_19_through_24_x_required');
+    verifyReference(join(root,'vendor','psst'));
+    if (argument) { const { readPluginConfig } = await import('../src/plugin-state.mjs'); readPluginConfig(argument); }
+    const report = { package_version: JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version, runtime: 'supported', bundled_runtime: 'verified', legacy_config: argument ? 'valid' : 'not_requested', native_mcp: pluginMcpDiagnostic(), installation: inspectNativeInstallation(root), live_acceptance: 'not_tested' };
+    console.log(JSON.stringify(report, null, 2));
+    console.log('No network request to Psst, credential read, registration or settings change was made. A local preflight is not native readiness.');
+    if (report.native_mcp.state !== 'native_attachment_unverified' || report.installation.blockers.length > 0) process.exitCode = 2;
+  } else if (!command || ['--help','help'].includes(command)) console.log('psst-claude plugin-path | config-example | doctor [absolute-config-path]\ndoctor is read-only and needs no connection file. Review its native /plugin source and ownership diagnostics; unresolved facts stop without changes. Then verify native /mcp before setup.');
+  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,50 @@
+import { projectMetadata } from '../src/project-metadata.mjs';
+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), project: projectMetadata(config) }),
+    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: projectMetadata(config), 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,34 @@
+#!/usr/bin/env node
+import {dirname} from 'node:path';
+import {resolveNativeBinding,associateNativeBinding} from '../src/native-binding.mjs';
+import {issueNativePermit} from '../src/native-call-permit.mjs';
+import {selectedConfig} from '../src/installation-selection.mjs';
+import {processIdentity} from '../src/launch-state.mjs';
+import { readPluginConfig, nativeStateConfig, 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 event=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  const host=processIdentity(process.ppid),nativeConfig=nativeStateConfig(process.env,host,event.session_id);
+  let result;
+  if(event.hook_event_name==='PreToolUse'){
+    let legacyConfig=null;try{legacyConfig=(process.env.PSST_CLAUDE_CONFIG||process.env.PSST_CONFIG_FILE)?readPluginConfig():(selectedConfig()??readPluginConfig());}catch{}
+    const resolved=resolveNativeBinding({nativeConfig,legacyConfig,host,sessionId:event.session_id});
+    if(!resolved)throw Error('native_binding_unavailable');
+    result=pluginHook({stateRoot:dirname(resolved.directory)},event,host);
+    if(!result){const issued=issueNativePermit({...resolved,event});result={hookSpecificOutput:{hookEventName:'PreToolUse',updatedInput:issued.arguments}};}
+  }else{
+    let legacyConfig=null;try{legacyConfig=(process.env.PSST_CLAUDE_CONFIG||process.env.PSST_CONFIG_FILE)?readPluginConfig():(selectedConfig()??readPluginConfig());}catch{}
+    // Resolve the previously committed owner BEFORE modifying canonical state.
+    let previous;try{previous=resolveNativeBinding({nativeConfig,legacyConfig,host,sessionId:event.session_id});}catch(error){if(event.hook_event_name!=='SessionStart'||event.source==='compact')throw error;}
+    if(event.hook_event_name==='SessionStart'&&event.source==='compact'&&!previous)throw Error('compact_authority_unavailable');
+    result=pluginHook(nativeConfig,event,host);
+    const chosen=previous?{stateRoot:previous.authorityRoot}:legacyConfig;
+    if(chosen&&chosen.stateRoot!==nativeConfig.stateRoot)pluginHook(chosen,event,host);
+    if(event.hook_event_name==='SessionStart'&&!event.agent_id)associateNativeBinding({nativeConfig,legacyConfig:chosen,host,sessionId:event.session_id});
+  }
+  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,44 @@
+#!/usr/bin/env node
+import {dirname,join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {processIdentity} from '../src/launch-state.mjs';
+import {readPluginConfig,nativeStateConfig} from '../src/plugin-state.mjs';
+import {selectedConfig} from '../src/installation-selection.mjs';
+import {resolveNativeBinding} from '../src/native-binding.mjs';
+import {consumeNativePermit} from '../src/native-call-permit.mjs';
+import {createNativeEpochManager} from '../src/native-epoch-manager.mjs';
+import {createPluginEpoch} from '../src/plugin-epoch.mjs';
+import {serveStdio,TOOL_DEFINITIONS} from '../src/cooperative-stdio.mjs';
+import {NATIVE_RECEIVE_RESPONSE_BYTES} from '../src/receive-presentation.mjs';
+import {verifyReference} from '../src/reference-pin.mjs';
+
+let server,timer,manager,closed=false;
+try {
+ const root=dirname(dirname(fileURLToPath(import.meta.url)));verifyReference(join(root,'vendor','psst'));
+ const [{BrokerClient},{AdapterRuntime},{createTools},{createCooperativeInbox}]=await Promise.all([
+  import('../vendor/psst/reference/client.mjs'),import('../vendor/psst/reference/runtime.mjs'),import('../vendor/psst/reference/tools.mjs'),import('../src/cooperative-inbox.mjs')]);
+ const dependencies={BrokerClient,AdapterRuntime,createTools,createCooperativeInbox};
+ const host=processIdentity(process.ppid);
+ const loadLegacy=()=>{try{return (process.env.PSST_CLAUDE_CONFIG||process.env.PSST_CONFIG_FILE)?readPluginConfig():(selectedConfig()??readPluginConfig());}
+ catch(error){if(error.code!=='ENOENT')process.stderr.write('psst_default_config_invalid: staying disconnected; provide a valid private connection file.\n');return null;}};
+ const hostAlive=()=>{try{const now=processIdentity(host.pid);return now.start===host.start&&now.boot===host.boot;}catch{return false;}};
+ manager=createNativeEpochManager({hostAlive,
+  resolve(){const legacyConfig=loadLegacy(),nativeConfig=nativeStateConfig(process.env,host);const found=resolveNativeBinding({nativeConfig,legacyConfig,host});return found?{...found,nativeConfig,legacyConfig,dependencies}:null;},
+  create:createPluginEpoch
+ });
+ const synchronize=manager.synchronize;
+ const nativeAdmission=async(name,args)=>{
+  const epoch=await synchronize();
+  if(!epoch?.isCurrent())throw Error('session_binding_unavailable');
+  const permit=consumeNativePermit({directory:epoch.directory,binding:epoch.binding,toolName:name,args});
+  if(!epoch.isCurrent())throw Error('session_changed');
+  return {arguments:permit.arguments,tools:epoch.tools,isCurrent:()=>manager.isCurrent(epoch)};
+ };
+ const advertised=Object.fromEntries(TOOL_DEFINITIONS.map(({name})=>[name,()=>{throw Error('native_admission_required');}]));
+ const close=async()=>{closed=true;clearInterval(timer);await manager.close();};
+ server=serveStdio({tools:advertised,nativeAdmission,readableNativeReceive:true,maxReceiveResponseBytes:NATIVE_RECEIVE_RESPONSE_BYTES,onClose:close,onDiagnostic:()=>{}});
+ let ticking=false,blockedNotice=false;
+ timer=setInterval(()=>{if(ticking||closed)return;ticking=true;void(async()=>{const epoch=await synchronize();await epoch?.tick();blockedNotice=false;})().catch(error=>{if(error.message==='native_host_departed'){void server.close();return;}if(!blockedNotice){blockedNotice=true;process.stderr.write('psst_native_binding_unavailable: catalog retained; no new lifetime admitted.\n');}}).finally(()=>{ticking=false;});},250);
+ await server.done;
+}catch{process.stderr.write('psst_mcp_unavailable: native session/configuration check failed; no message was acknowledged.\n');process.exitCode=1;}
+finally{closed=true;clearInterval(timer);await server?.close();await manager?.close();}

package/bin/plugin-monitor.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Native plugin monitor, not a second broker client. No token or inbox body is read.
+import {resolveNativeBinding,isNativeBindingCurrent} from '../src/native-binding.mjs';
+import {selectedConfig} from '../src/installation-selection.mjs';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { processIdentity, readPrivateJson, writePrivateJson } from '../src/launch-state.mjs';
+import { nativeStateConfig, readPluginConfig, hostDirectory, readBinding, verifyBinding } from '../src/plugin-state.mjs';
+import { noticeBudget } from '../src/native-notices.mjs';
+import { monitorBudget } from '../src/monitor-budget.mjs';
+import { PRESENCE_NOTICE } from '../src/presence-notices.mjs';
+try {
+ // Claude's native shell launcher supplies both. Never infer a session from a name or arbitrary journal.
+ const pid=Number(process.env.CLAUDE_PID),sessionId=process.env.CLAUDE_CODE_SESSION_ID;
+ if(!Number.isSafeInteger(pid)||pid<1||!sessionId)throw Error('native_monitor_context_missing');
+ const host=processIdentity(pid),nativeConfig=nativeStateConfig(process.env,host,sessionId);
+ let legacyConfig=null;try{legacyConfig=(process.env.PSST_CLAUDE_CONFIG||process.env.PSST_CONFIG_FILE)?readPluginConfig():(selectedConfig()??readPluginConfig());}catch{}
+ let expected,directory;
+ // Native always-start monitors may precede the SessionStart hook. Wait only for
+ // this exact native owner/session; never create a binding or infer another one.
+ for(let attempt=0;attempt<100&&!expected;attempt++){
+  try{const found=resolveNativeBinding({nativeConfig,legacyConfig,host,sessionId});if(found){expected=found.binding;directory=found.directory;}}catch{}
+  if(!expected){const actual=processIdentity(pid);if(actual.start!==host.start||actual.boot!==host.boot)break;await delay(100);}
+ }
+ if(!expected)throw Error('native_monitor_binding_missing');
+ const budget=monitorBudget({path:join(directory,'message-notice-budget.json'),binding:expected});
+ // Keep transport-hint attempts across monitor restarts. Reserve before stdout;
+ // neither the checkpoint nor successful stdout acknowledges a broker event.
+ const presenceBudgetPath=join(directory,'presence-notice-budget.json');
+ let presenceBudget;
+ try{
+  const saved=readPrivateJson(presenceBudgetPath);
+  const same=saved.sessionId===sessionId&&saved.lifetime===expected.lifetime&&saved.host?.pid===host.pid&&saved.host?.start===host.start&&saved.host?.boot===host.boot;
+  presenceBudget=noticeBudget({initialState:same?saved.checkpoint:null});
+ }catch(error){if(error.code==='ENOENT')presenceBudget=noticeBudget();}
+
+ while(isNativeBindingCurrent({nativeConfig,directory,binding:expected,host})){
+  try{
+   const status=readPrivateJson(join(directory,'notice.json'));
+   if(status.sessionId===sessionId&&status.lifetime===expected.lifetime&&status.host?.pid===pid&&status.host?.start===host.start&&status.host?.boot===host.boot&&Date.now()-status.updated_at>=0&&Date.now()-status.updated_at<5000&&budget.next(status)){
+    process.stdout.write('Psst: authorized collaboration mailbox has pending AGENT data. Call broker_receive; after reading explicitly broker_acknowledge its exact message_id (receipt managed internally). No human permission or action completion is implied.'+(budget.snapshot.attention_required?' Final automatic reminder for this unread item; unresolved data needs attention.':'')+'\n');
+   }
+   if(presenceBudget&&status.sessionId===sessionId&&status.lifetime===expected.lifetime&&status.host?.pid===pid&&status.host?.start===host.start&&status.host?.boot===host.boot&&Date.now()-status.updated_at>=0&&Date.now()-status.updated_at<5000
+    &&presenceBudget.next({connected:status.connected,pending_id:status.presence_event_id})){
+    writePrivateJson(presenceBudgetPath,{sessionId,lifetime:expected.lifetime,host,checkpoint:presenceBudget.checkpoint});
+    process.stdout.write(PRESENCE_NOTICE+(presenceBudget.snapshot.attention_required?' Final automatic reminder for this transport notice.':'')+'\n');
+   }
+   writePrivateJson(join(directory,'monitor-state.json'),{sessionId,lifetime:expected.lifetime,pending_id:status.pending_id,...budget.snapshot,updated_at:Date.now()});
+  }catch{/* Disconnected/not yet configured: silent, no broker access. */}
+  await delay(1000);
+ }
+}catch{process.stderr.write('psst_monitor_unavailable: native binding was not confirmed; no message consumed.\n');}

package/distribution/npm-marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "psst-connectors",
+  "owner": {
+    "name": "Bruno Orsolon"
+  },
+  "plugins": [
+    {
+      "name": "psst",
+      "source": {
+        "source": "npm",
+        "package": "@matuto-ai/claude-psst-connector",
+        "version": "0.7.0"
+      },
+      "description": "Psst messaging for Claude Code"
+    }
+  ],
+  "metadata": {
+    "description": "Native Psst agent-messaging connector for Claude Code"
+  }
+}