@matuto-ai/claude-code-broker-connector 0.4.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "psst",
       "source": "./",
       "description": "Psst messaging for Claude Code",
-      "version": "0.4.0"
+      "version": "0.6.0"
     }
   ],
   "metadata": {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "psst",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Session-bound Psst agent messaging with explicit receive and acknowledgment. Bounded opt-in native notices; no permission relay.",
   "author": {
     "name": "Bruno Orsolon"
@@ -11,17 +11,9 @@
     "broker_url": {
       "type": "string",
       "title": "Psst broker URL",
-      "description": "HTTPS broker origin. This is not a credential; a previously authorized installation is still required. Leave blank to use the selected installation or PSST_BROKER_URL.",
+      "description": "HTTPS broker origin. Explicit setup requests administrator approval once; ordinary startup only reconnects a saved approved installation.",
       "required": false,
       "default": ""
-    },
-    "pairing_secret": {
-      "type": "string",
-      "title": "Psst one-use pairing secret",
-      "description": "Enter only in this native private configuration field, never in chat. Used solely by explicit setup, not startup. Remove through native UI after successful setup if supported.",
-      "required": false,
-      "sensitive": true,
-      "default": ""
     }
   }
 }

package/.mcp.json

@@ -6,8 +6,7 @@
         "${CLAUDE_PLUGIN_ROOT}/bin/plugin-mcp.mjs"
       ],
       "env": {
-        "PSST_PLUGIN_BROKER_URL": "${user_config.broker_url}",
-        "PSST_PLUGIN_PAIRING_SECRET": "${user_config.pairing_secret}"
+        "PSST_PLUGIN_BROKER_URL": "${user_config.broker_url}"
       }
     }
   }

package/README.md

@@ -1,49 +1,58 @@
 # Psst for Claude Code
 
+> **Unreleased 0.6.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 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.
+
 ## Install from GitHub
 
-After release `v0.4.0` is published, install the pinned release:
+After release `v0.6.0` is published, install the pinned release:
 
 ```sh
-claude plugin marketplace add matuto-ai/claude-code-broker-connector#v0.4.0
+claude plugin marketplace add matuto-ai/claude-code-broker-connector#v0.6.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.309).
-
-Initial private setup requires broker **0.3.0 with pairing enabled** and an
-operator-approved, Claude-specific one-use pairing secret for this installation.
-A URL or connector upgrade alone does not authorize enrollment. Enter the secret
-only in the native sensitive field; no per-session file transfer is needed.
-
-After installation, open Claude normally. For first authorization, configure
-`broker_url` and the sensitive one-use `pairing_secret` in the native `/plugin`
-configuration dialog, never in chat. Close the panel and verify its reload applied;
-if changes remain pending, use `/reload-plugins` inside Claude or start a fresh
-session. Then explicitly run:
-
-```text
-/psst:connect
-```
-
-This saves the authorized installation in its existing config volume. New native
-sessions attach automatically with separate client IDs and inboxes; no external
-connect command or credential file per session is required. Existing private
-bundles can instead use `/psst:connect /absolute/private/connection.json`.
-See [configuration, persistence and acceptance limits](docs/installation-selection.md).
+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. 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 remain
-available while disconnected. Existing sessions can reload the plugin, but a
+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
@@ -54,15 +63,17 @@ Legacy environment/default-file configuration remains supported; see
 Ask Claude to use Psst for the peers and purpose you authorize, or invoke `/psst:psst`.
 The native MCP tools are:
 
-- `broker_setup`: explicit initial authorization using private native configuration, no secret arguments.
+- `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 with a stable `send_key`; preserve it if the result is uncertain.
-- `broker_receive`: read the FIFO head and its opaque `receipt_token`.
+- `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`
-  and `receipt_token`, advancing to the next message.
+  (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.
 
@@ -71,6 +82,8 @@ A native plugin monitor starts automatically in every interactive Claude session
 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).
 
@@ -100,27 +113,48 @@ 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-code-broker-connector@0.4.0
-"$HOME/.local/share/psst-claude/node_modules/.bin/psst-claude" plugin-path
+npm install --prefix "$HOME/.local/share/psst-claude" --ignore-scripts --no-audit --no-fund @matuto-ai/claude-code-broker-connector@0.6.0
+"$HOME/.local/share/psst-claude/node_modules/.bin/psst-claude" doctor
 ```
 
-For a first installation, add that printed directory with
-`claude plugin marketplace add <directory>`, then
-`claude plugin install psst@psst-connectors`. For an existing marketplace backed
-by that directory, refresh it and update the installed plugin:
+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.
 
-```sh
-claude plugin marketplace update psst-connectors
-claude plugin update psst@psst-connectors
+For a **fresh** local source, the printed native command is:
+
+```text
+/plugin install psst --marketplace <printed-package-root>
 ```
 
-Use the original installation scope if it was not the default user scope. Do not
-register a duplicate marketplace or replace a shared source without checking it.
-The new plugin version avoids reusing the previous release cache. In an existing Claude
-session use `/reload-plugins`; a fresh session supplies SessionStart normally.
-Native permissions and workspace trust still apply. The CLI also offers
-`doctor [absolute-config-path]`; it never writes credentials or changes Claude
-settings by itself. No postinstall scripts are used.
+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
 
@@ -154,3 +188,7 @@ 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 remaining gates](docs/candidate-verification.md).

package/bin/cli.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { readPluginConfig, configPath } from '../src/plugin-state.mjs';
+import { readFileSync } from 'node:fs';
+import { supportedRuntime, pluginMcpDiagnostic, inspectNativeMarketplace } 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);
@@ -9,10 +10,13 @@ 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');
+    if(!supportedRuntime()) throw new Error('linux_node_24_19_through_24_x_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.');
+    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: inspectNativeMarketplace(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' || ['source_conflict','inspection_unavailable'].includes(report.installation.state)) 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. Follow its native /plugin install/update guidance; conflicts 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/plugin-hook.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
+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 result=pluginHook(nativeStateConfig(),event);
+  const result=pluginHook(nativeStateConfig(process.env,processIdentity(process.ppid),event.session_id),event);
   // Compatibility for an already configured 0.2.1 host journal.
   try { pluginHook(readPluginConfig(),event); } catch { /* Configuration is optional before connect. */ }
   if(result) process.stdout.write(JSON.stringify(result)+'\n');

package/bin/plugin-mcp.mjs

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
+import { createToolScope } from '../src/tool-scope.mjs';
 import { installationRoot, readSelection, selectedConfig, saveSelection, configuredBrokerUrl, enforceConfiguredBroker } from '../src/installation-selection.mjs';
-import { connectPairingFile, connectPairingSecret } from '../src/enrollment-support.mjs';
+import { connectPairingFile } from '../src/enrollment-support.mjs';
+import {switchApproved} from '../src/approval-attachment.mjs';
+import {ApprovalSession} from '../src/approval-session.mjs';
+import {beginApproval,pollApproval,readApprovalState} from '../src/approval-support.mjs';
+import {readSetupContext,saveSetupContext} from '../src/setup-context.mjs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileSync } from 'node:fs';
@@ -8,15 +13,15 @@ import { readPrivateJson, writePrivateJson, privateDirectory } from '../src/laun
 import { verifyReference } from '../src/reference-pin.mjs';
 import { readPluginConfig, nativeStateConfig, hostDirectory, readBinding, verifyBinding, bindingModel, journalName, refreshEnrollment } from '../src/plugin-state.mjs';
 
-let server,runtime,inbox,timer,live=true,expected,directory,host,tools,connected=false,connecting=false,disabled=false,generation=0,autoAttempted=false;
-let legacyConfig=null,connectedConfig=null,lastNotice=null,lastNoticeAt=0;
+let toolScope,connectionAbort,recoveryPromise,server,runtime,inbox,timer,live=true,expected,directory,host,tools,connected=false,connecting=false,disabled=false,generation=0,autoAttempted=false;
+let legacyConfig=null,connectedConfig=null,lastNotice=null,lastNoticeAt=0,approvalSession=null,setupContext=null,approvalTransition=null;
 const failure=(code,effect='not_applied')=>({error:{code,retryable:true,effect}});
 const bound=()=>live&&expected&&verifyBinding(directory,expected);
 const active=()=>connected&&bound();
 function status(){
  if(!directory||!expected)return;
  const head=connected&&inbox?inbox.head():null;
- const value={host,sessionId:expected.sessionId,lifetime:expected.lifetime,connected:!!active(),pending_id:head?.state==='pending'?head.message_id:null};
+ const value={host,sessionId:expected.sessionId,lifetime:expected.lifetime,connected:!!active(),pending_id:head?.state==='pending'?head.message_id:null,setup_state:approvalSession?.status?.state??null,setup_connected:approvalSession?.status?.connected===true};
  const key=JSON.stringify(value),now=Date.now();
  if(key===lastNotice&&now-lastNoticeAt<2000)return;
  writePrivateJson(join(directory,'notice.json'),{...value,updated_at:now});lastNotice=key;lastNoticeAt=now;
@@ -25,7 +30,7 @@ function monitorAttention(){
  try{const s=readPrivateJson(join(directory,'monitor-state.json'));if(s.sessionId===expected.sessionId&&s.lifetime===expected.lifetime&&s.pending_id===(inbox?.head()?.message_id??null)&&Date.now()-s.updated_at>=0&&Date.now()-s.updated_at<5000)return {attention_required:s.attention_required===true,rate_limited:s.rate_limited===true,next_retry_at:s.next_retry_at};}catch{}
  return {state:'not_observed'};
 }
-async function stop(closeSession){connected=false;status();await runtime?.stop({closeSession});inbox?.close();runtime=null;inbox=null;tools=null;}
+async function stop(closeSession){connected=false;status();connectionAbort?.abort();await toolScope?.close();await recoveryPromise?.catch(()=>{});recoveryPromise=null;await runtime?.stop({closeSession});inbox?.close();runtime=null;inbox=null;tools=null;}
 try {
  const root=dirname(dirname(fileURLToPath(import.meta.url)));verifyReference(join(root,'vendor','psst'));
  const [{Inbox,newSessionIdentity},{BrokerClient},{AdapterRuntime},{createTools},{createCooperativeInbox},{serveStdio}]=await Promise.all([
@@ -40,11 +45,12 @@ try {
    try{const b=readBinding(candidate);if(b.host.pid===host.pid&&verifyBinding(candidate,b)){directory=candidate;expected=b;return true;}}catch{}
   }return false;
  }
- async function connect(config){
-  config=enforceConfiguredBroker(refreshEnrollment(config));
+ async function connect(config,{allowSavedOrigin=false,validIntent=()=>true}={}){
+  config=refreshEnrollment(config);if(!allowSavedOrigin)config=enforceConfiguredBroker(config);
   if(connecting)return failure('connection_busy');
   if(!confirm())return failure('session_binding_unavailable');
   if(connected)return connectedConfig.brokerUrl===config.brokerUrl&&connectedConfig.tokenFile===config.tokenFile&&connectedConfig.enrollment?.credentialId===config.enrollment?.credentialId?tools.broker_identity():failure('connection_conflict');
+  if(runtime&&!connected)await stop(false);
   connecting=true;disabled=false;const epoch=generation;
   try{
    const journal=privateDirectory(join(directory,journalName(expected.lifetime,config)));
@@ -55,24 +61,29 @@ try {
    const identityFile=join(journal,'identity.json');
    try{writeFileSync(identityFile,JSON.stringify(newSessionIdentity('claude-code'))+'\n',{mode:0o600,flag:'wx'});}catch(e){if(e.code!=='EEXIST')throw e;}
    const identity=readPrivateJson(identityFile);inbox=new Inbox({directory:journal,identity});
+   connectionAbort=new AbortController();toolScope=createToolScope();
    const client=new BrokerClient({url:config.brokerUrl,tokenFile:config.tokenFile,caFile:config.caFile,insecureDevelopment:config.insecureDevelopment===true,inbox});
-   runtime=new AdapterRuntime({client,inbox,verifySession:bound,isAlive:bound,onDiagnostic:({code})=>process.stderr.write(`psst_${code}\n`)});
+   runtime=new AdapterRuntime({client,inbox,verifySession:bound,isAlive:bound,onDiagnostic:({code})=>{if(['unauthenticated','forbidden','session_closed'].includes(code)){connected=false;status();}process.stderr.write(`psst_${code}\n`);}});
    tools={...createTools({client,inbox,observeMetadata:()=>({model:bindingModel(readBinding(directory))})}),...createCooperativeInbox({inbox,isActive:active}),
-    broker_identity:async()=>({credential_id:config.enrollment?.credentialId??null,credential_expires_at:config.enrollment?.expiresAt??null,monitor_attention:monitorAttention(),client_id:identity.client_id,client_type:'claude-code',native_session_id:expected.sessionId,local_mode:'cooperative_read_with_bounded_monitor_notices',automatic_wakeup:'bounded_monitor_when_interactive',native_acceptance_recorded:false})};
+    broker_identity:async()=>({credential_id:config.enrollment?.credentialId??null,credential_expires_at:config.enrollment?.expiresAt??null,monitor_attention:monitorAttention(),client_id:identity.client_id,client_type:'claude-code',native_session_id:expected.sessionId,mode:'automatic_required',local_mode:'native_monitor_delivery',readiness:monitorAttention().state==='not_observed'?'blocked_monitor_not_observed':'native_wakeup_acceptance_unverified',automatic_wakeup:'bounded_monitor_when_interactive',native_acceptance_recorded:false})};
    await runtime.start({name:config.name,project:config.project??null,model:bindingModel(expected)});
-   if(!bound()||generation!==epoch||disabled)throw Error('session_changed');connected=true;connectedConfig=config;disabled=false;writePrivateJson(join(directory,'activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,disabled:false,config});status();return tools.broker_identity();
+   if(!bound()||generation!==epoch||disabled||!validIntent())throw Error('session_changed');
+   recoveryPromise=client.recoverOutgoing({limit:10,signal:AbortSignal.any([connectionAbort.signal,AbortSignal.timeout(5000)])});
+   await recoveryPromise.catch(()=>{});
+   if(!bound()||generation!==epoch||disabled||!validIntent())throw Error('session_changed');connected=true;connectedConfig=config;disabled=false;writePrivateJson(join(directory,'activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,disabled:false,config});status();return tools.broker_identity();
   }catch{await stop(!bound());return failure(generation!==epoch?'connection_cancelled':'connection_failed','unknown');}finally{connecting=false;}
  }
- 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=>{
+ const names=['broker_list_clients','broker_send','broker_update_metadata','broker_message_status','broker_receive','broker_acknowledge','broker_identity','broker_sent_history','broker_message_content','broker_resend','broker_cancel'];
+ const guarded=Object.fromEntries(names.map(name=>[name,async (args,context)=>{
   if(!active())return failure(expected?'not_connected':'session_binding_unavailable');
-  const result=await tools[name](args);status();return result;
+  return toolScope.run(async signal=>{const result=await tools[name](args,{...context,signal});status();return result;},context?.signal);
  }]));
  let pairing=false;
- const explicitConnect=async({connection_file},nativeSetup=false)=>{
+ const explicitConnect=async({connection_file})=>{
+  approvalSession?.cancel();
   // Explicit user intent supersedes deferred startup resume, including failed attempts.
   autoAttempted=true;
-  if(pairing||connecting)return failure('connection_busy');
+  if(pairing||connecting||approvalTransition)return failure('connection_busy');
   if(!confirm())return failure('session_binding_unavailable');
   try{
    let selectionRevision=null,selectionReadable=true;const selectionEpoch=generation;
@@ -81,13 +92,12 @@ try {
     if(!selectionReadable)selection={saved:false,reason:'installation_selection_invalid_or_unreadable'};
     else try{selection=saveSelection(file,selectionRevision,installationRoot(),connectedConfig);}catch{selection={saved:false,reason:'installation_selection_unavailable'};}
     return {...result,installation_selection:selection};};
-   const input=nativeSetup?null:readPrivateJson(connection_file);
-   if(nativeSetup||input?.format==='psst-pairing-v1'){
+   const input=readPrivateJson(connection_file);
+   if(input?.format==='psst-pairing-v1'){
     if(connected)return failure('disconnect_before_pairing');
     pairing=true;const epoch=generation;
     const options={directory:join(installationRoot(),'enrollment'),clientType:'claude-code',brokerUrl:configuredBrokerUrl()??undefined};
-    if(nativeSetup&&(!options.brokerUrl||!process.env.PSST_PLUGIN_PAIRING_SECRET))return failure('native_setup_configuration_required');
-    const result=nativeSetup?await connectPairingSecret({...options,pairingSecret:process.env.PSST_PLUGIN_PAIRING_SECRET}):await connectPairingFile({...options,pairingFile:connection_file});
+    const result=await connectPairingFile({...options,pairingFile:connection_file});
     if(epoch!==generation||!bound())return failure('connection_cancelled','unknown');
     return remember(await connect(readPluginConfig(result.connectionFile)),result.connectionFile);
    }
@@ -96,10 +106,67 @@ try {
   finally{pairing=false;}
  };
  guarded.broker_connect=args=>explicitConnect(args);
- // Explicit native action only: residual native secrets are never used at startup.
- guarded.broker_setup=()=>explicitConnect({},true);
- guarded.broker_disconnect=async()=>{autoAttempted=true;generation++;disabled=true;connected=false;if(expected)writePrivateJson(join(directory,'activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,disabled:true});status();if(connecting)void runtime?.stop({closeSession:false}).catch(()=>{});else await stop(false);return{connected:false,pending_connection_cancelled:connecting||pairing,pending_retained:true,native_acceptance_recorded:false};};
- server=serveStdio({tools:guarded,onClose:async()=>{const closeSession=!bound();generation++;live=false;await stop(closeSession);},onDiagnostic:()=>{}});
+ const setupOptions=brokerUrl=>({brokerUrl,directory:installationRoot(),clientType:'claude-code',label:'Claude Code installation'});
+ const updateSetup=state=>{
+  if(!setupContext||!state.requestId)return;
+  try{
+   const latest=readSetupContext(),nextState=state.connected?'applied':state.state;
+   if(latest?.broker_url===setupContext.broker_url&&latest.selection_revision===setupContext.selection_revision&&latest.request_id===state.requestId){
+    setupContext=latest;if(latest.state===nextState||latest.state==='applied')return status();
+   }
+   setupContext=saveSetupContext({...setupContext,request_id:state.requestId,state:nextState},setupContext.revision);
+  }
+  catch{/* A competing explicit choice owns selection; never overwrite it. */}
+  status();
+ };
+ approvalSession=new ApprovalSession({beginApproval,pollApproval,readApprovalState,isCurrent:()=>bound()&&!disabled,
+  onState:updateSetup,onApproved:async(result,current)=>{
+   const context=readSetupContext();
+   if(!current()||!context||context.broker_url!==setupContext?.broker_url||context.selection_revision!==setupContext?.selection_revision||(context.revision!==setupContext?.revision&&context.request_id!==result.requestId)||(context.request_id&&context.request_id!==result.requestId))return {connected:false,error:'setup_context_changed'};
+   const selection=readSelection();if((selection?.revision??null)!==context.selection_revision&&selection?.connection_file!==result.connectionFile)return {connected:false,error:'installation_selection_changed'};
+   const config=readPluginConfig(result.connectionFile),previous=connected?connectedConfig:null;
+   if(new URL(config.brokerUrl).origin!==context.broker_url)return {connected:false,error:'configured_broker_mismatch'};
+   const transaction={phase:'stopping'};approvalTransition=transaction;
+   const restoreAllowed=()=>approvalTransition===transaction&&bound()&&!disabled;
+   return switchApproved({previous,stop:()=>stop(false),
+    connect:(old,{restore,isCurrent})=>connect(restore?old:config,{allowSavedOrigin:restore,validIntent:isCurrent}),
+    select:()=>current()?saveSelection(result.connectionFile,context.selection_revision,installationRoot(),connectedConfig):{saved:false,reason:'connection_cancelled'},
+    isCurrent:()=>current()&&approvalTransition===transaction,canRestore:restoreAllowed,
+    onPhase:phase=>{
+     if(approvalTransition!==transaction)return;
+     transaction.phase=phase;
+     if(phase==='finished'){
+      if(!connected&&expected)writePrivateJson(join(directory,'activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,disabled:true});
+      approvalTransition=null;
+     }
+    }});
+  }});
+ guarded.broker_setup=async({replace=false}={})=>{
+  autoAttempted=true;if(pairing||connecting||approvalSession.busy||approvalTransition)return failure('connection_busy');
+  if(!confirm())return failure('session_binding_unavailable');
+  try{
+   const brokerUrl=configuredBrokerUrl();if(!brokerUrl)return failure('native_setup_configuration_required');
+   const old=readSetupContext();
+   if(old&&old.broker_url===brokerUrl&&['requested','pending','approved'].includes(old.state)&&!replace){setupContext=old;}
+   else setupContext=saveSetupContext({broker_url:brokerUrl,selection_revision:readSelection()?.revision??null,request_id:null,state:'requested'},old?.revision??null);
+   disabled=false;writePrivateJson(join(directory,'setup-activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,cancelled:false});
+   return await approvalSession.start(setupOptions(brokerUrl),{replace});
+  }catch(error){
+   // A failed POST may have durable local candidate state. Later startup may GET
+   // it, but never invent a new request or retry POST automatically.
+   return {...failure(error.retryable?'approval_temporarily_unavailable':'approval_setup_blocked',error.effect??'not_applied'),...(Number.isFinite(error.retryAfterMs)?{retry_after_ms:Math.max(1000,Math.min(300000,error.retryAfterMs))}:{})};
+  }
+ };
+ const deliveryReadiness=()=>({mode:'automatic_required',readiness:monitorAttention().state==='not_observed'?'blocked_monitor_not_observed':'native_wakeup_acceptance_unverified',manual_receive:'diagnostic_test_only'});
+ guarded.broker_setup_status=async()=>{
+  if(approvalSession.status.state!=='not_started')return {...approvalSession.status,...deliveryReadiness()};
+  try{const context=readSetupContext();if(!context)return {state:active()?'connected':'setup_required',connected:!!active(),...deliveryReadiness()};
+   const saved=readApprovalState(setupOptions(context.broker_url));return saved?{state:saved.state,requestId:saved.requestId,requestExpiresAt:saved.requestExpiresAt,connected:!!active(),...deliveryReadiness()}:{state:'setup_required',connected:!!active(),...deliveryReadiness()};
+  }catch{return {state:'blocked',error:'invalid_saved_setup',connected:!!active(),...deliveryReadiness()};}
+ };
+ guarded.broker_setup_cancel=async()=>{approvalSession.cancel();if(approvalTransition&&['stopping','attaching','selecting'].includes(approvalTransition.phase))generation++;if(expected)writePrivateJson(join(directory,'setup-activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,cancelled:true});return {state:'cancelled',existing_connection_retained:!!active()};};
+ guarded.broker_disconnect=async()=>{approvalSession.cancel();autoAttempted=true;generation++;disabled=true;connected=false;if(expected)writePrivateJson(join(directory,'activation.json'),{sessionId:expected.sessionId,lifetime:expected.lifetime,disabled:true});status();if(connecting)void runtime?.stop({closeSession:false}).catch(()=>{});else await stop(false);return{connected:false,pending_connection_cancelled:connecting||pairing,pending_retained:true,native_acceptance_recorded:false};};
+ server=serveStdio({tools:guarded,onClose:async()=>{const closeSession=!bound();approvalSession?.cancel();generation++;live=false;await stop(closeSession);},onDiagnostic:()=>{}});
  // Stay available while disconnected. Never retry failed enrollment/auth indefinitely.
  timer=setInterval(()=>{void(async()=>{
   if(expected&&!bound()){live=false;await server.close();return;}
@@ -107,13 +174,22 @@ try {
   if(expected&&!autoAttempted&&!disabled){
    autoAttempted=true;let config=legacyConfig;
    try{const a=readPrivateJson(join(directory,'activation.json'));if(a.sessionId===expected.sessionId&&a.lifetime===expected.lifetime){disabled=a.disabled===true;config=a.config??null;}}catch{}
+   let resumeOptions=null;
+   try{
+    const saved=readSetupContext(),cancel=(()=>{try{return readPrivateJson(join(directory,'setup-activation.json'));}catch{return null;}})();
+    if(saved&&['requested','pending','approved'].includes(saved.state)&&!(cancel?.sessionId===expected.sessionId&&cancel?.lifetime===expected.lifetime&&cancel?.cancelled)&&!disabled){
+     const local=readApprovalState(setupOptions(saved.broker_url));
+     if(local&&(!saved.request_id||saved.request_id===local.requestId)){setupContext=saved;resumeOptions=setupOptions(saved.broker_url);}
+    }
+   }catch{process.stderr.write('psst_setup_resume_unavailable: existing request state is invalid; no new request created.\n');}
    if(config&&!disabled){
-    try{const result=await connect(config);if(result?.error)process.stderr.write('psst_autoconnect_unavailable: saved installation could not attach; use explicit connect after correcting configuration.\n');}
+    try{const result=await connect(config,{allowSavedOrigin:!!resumeOptions&&setupContext.selection_revision===(readSelection()?.revision??null)});if(result?.error)process.stderr.write('psst_autoconnect_unavailable: saved installation could not attach; use explicit connect after correcting configuration.\n');}
     catch{process.stderr.write('psst_autoconnect_unavailable: saved installation or configured broker is invalid; use explicit connect after correcting configuration.\n');}
    }
+   if(resumeOptions&&!disabled)await approvalSession.resume(resumeOptions);
   }
   if(active())status();
  })().catch(()=>{live=false;void server.close();});},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{if(timer)clearInterval(timer);live=false;await server?.close();await runtime?.stop({closeSession:true});inbox?.close();}
+finally{approvalSession?.cancel();if(timer)clearInterval(timer);live=false;await server?.close();await runtime?.stop({closeSession:true});inbox?.close();}

package/bin/plugin-monitor.mjs

@@ -11,7 +11,7 @@ try {
  if(!Number.isSafeInteger(pid)||pid<1||!sessionId)throw Error('native_monitor_context_missing');
  const host=processIdentity(pid),candidates=[];
  try{candidates.push(hostDirectory(readPluginConfig(),host).directory);}catch{}
- candidates.push(hostDirectory(nativeStateConfig(),host).directory);
+ candidates.push(hostDirectory(nativeStateConfig(process.env,host,sessionId),host).directory);
  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.
@@ -25,7 +25,7 @@ try {
   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 receipt. No human permission or action completion is implied.'+(budget.snapshot.attention_required?' Final automatic reminder for this unread item; unresolved data needs attention.':'')+'\n');
+    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');
    }
    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. */}

package/docs/automatic-delivery.md

@@ -37,7 +37,7 @@ or task-success signal. Native permissions remain in force.
 
 ## Limits and failure behavior
 
-- Interactive Claude Code 2.1.310+ only. Headless/SDK has cooperative tools but no
+- Interactive Claude Code 2.1.310+ only. Headless/SDK has diagnostic-only read tools but no
   plugin monitor. There is no hidden Channels flag or permission-relay capability.
 - Monitors run at plugin-hook trust level, **outside Claude's internal shell-tool
   sandbox**, but inside the existing Docker/container boundary. Respect workspace
@@ -46,7 +46,7 @@ or task-success signal. Native permissions remain in force.
   after 120 seconds. At most 30 notices in a rolling ten-minute window, which refills; new messages
   are not globally silenced forever. A head still unread after its third notice
   enters explicit attention-required state (visible through broker_identity);
-  it remains durable for cooperative receive, with no idle model polling loop.
+  it remains durable for an explicitly requested diagnostic read, with no idle model polling loop.
 - Native output batching/rate limits can suppress notices. Writing stdout is not
   proof of native transcript storage, model reading, or action completion. Only
   an explicit matching `broker_acknowledge` advances the local FIFO.
@@ -54,7 +54,7 @@ or task-success signal. Native permissions remain in force.
   pending messages. The monitor remains an inert local watcher for explicit
   reconnect because Claude arms this monitor once per session. Reconnecting does
   not reset the three-reminder budget for the same unread head: it still needs
-  cooperative receive/acknowledgment; a new head gets its own budget. A native binding
+  explicit diagnostic receive/acknowledgment; a new head gets its own budget. A native binding
   change/SessionEnd terminates it. Broker presence may remain until lease expiry.
 - Failed connect is reported without raw configuration/token errors and is not
   retried forever. The user can explicitly retry the same private file.
@@ -82,3 +82,14 @@ and official docs establish the supported path, not an authenticated success cla
 References:
 - https://code.claude.com/docs/en/plugins/components#monitors
 - https://code.claude.com/docs/en/plugins/manifest-reference#monitors
+
+## Production requirement (2026-11-01)
+
+Automatic receive is required for production. Headless/manual cooperative receive
+is retained only for explicit diagnostics/tests and must not be reported as a
+working production fallback. Missing native MCP or monitor capability is a blocked
+state; preserve pending messages without auto-acknowledging or bypassing policy.
+Receive now renders a compact AI-agent header and escaped message JSON. Wire
+origin/authority validation and normal native permissions are unchanged. Explicit
+read ACK needs only the exact message ID; its already exposed same-inbox receipt
+is resolved internally, with supplied legacy tokens still validated strictly.

package/docs/candidate-verification.md

@@ -0,0 +1,25 @@
+# Unreleased candidate verification — 2026-11-01
+
+Related issue: #11; not closed by this partial delivery.
+
+## Checked locally
+
+Syntax + 70/70 unit tests passed; integration 22 passed and one unavailable container gate skipped. Unit aggregate includes package validation.
+
+Synthetic native parent + real TLS/broker/monitor notices, same-host MCP restart and 30 independent native hosts.
+
+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
+
+Managed plugin-MCP suppression and authenticated native idle/busy/monitor acceptance remain external gates. Preflight is diagnostic, not a supported policy bypass or complete durable source-upgrade solution.
+
+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.