@matuto-ai/opencode-broker-connector 0.3.0 → 0.4.0

package/src/cooperative-inbox.mjs

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { LocalError } from '../vendor/broker/reference/errors.mjs';
-import { provenance } from '../vendor/broker/reference/runtime.mjs';
+import { nativeMessage } from './message-format.mjs';
 import { validateUuid } from '../vendor/broker/src/protocol.mjs';
 
 /** Application-level explicit read ACK. Never a native injection receipt or action success. */
@@ -12,29 +12,34 @@ export function createCooperativeInbox({ inbox, isActive = () => true }) {
   const active = () => { if (isActive() !== true) throw new LocalError('session_mismatch'); inbox.assertUsable(); };
   return {
     async broker_receive(args = {}) {
-      if (!args || Array.isArray(args) || typeof args !== 'object' || Object.keys(args).length) throw new LocalError('invalid_configuration');
+      if (!args || Array.isArray(args) || typeof args !== 'object' || Object.keys(args).some(key => key !== 'diagnostic')) throw new LocalError('invalid_configuration');
+      if (args.diagnostic !== true) { const error = new LocalError('unsafe_boundary', {field:'automatic_delivery_required'}); error.message = 'Automatic delivery is required. Manual receive is available only for an explicitly requested diagnostic test with diagnostic:true; nothing was consumed.'; throw error; }
       active();
       return inbox.transaction(() => {
         const head = inbox.head();
-        if (!head) return { message: null, local_mode: 'cooperative_pull' };
+        if (!head) return { message: null, local_mode: 'diagnostic_pull' };
         if (head.state !== 'pending') throw new LocalError('injection_uncertain', { effect: 'unknown' });
         let receipt = inbox.db.prepare('SELECT receipt_token FROM cooperative_receipts WHERE message_id=?').get(head.message_id);
         if (!receipt) {
           receipt = { receipt_token: randomUUID() };
           inbox.db.prepare('INSERT INTO cooperative_receipts(message_id,receipt_token,exposed_at) VALUES(?,?,?)').run(head.message_id, receipt.receipt_token, inbox.now());
         }
-        return { message_id: head.message_id, message: provenance(head.envelope), receipt_token: receipt.receipt_token,
-          local_state: 'pending', local_mode: 'cooperative_pull', native_acceptance_recorded: false,
+        return { message_id: head.message_id, message: nativeMessage(head.envelope),
+          local_state: 'pending', local_mode: 'diagnostic_pull', native_acceptance_recorded: false,
           acknowledgment_required: true };
       }, { growth: 4096 });
     },
     async broker_acknowledge(args) {
-      if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).sort().join(',') !== 'message_id,receipt_token') throw new LocalError('invalid_configuration');
-      try { validateUuid(args.message_id); validateUuid(args.receipt_token); } catch { throw new LocalError('invalid_configuration'); }
+      if (!args || typeof args !== 'object' || Array.isArray(args) || !['message_id','message_id,receipt_token'].includes(Object.keys(args).sort().join(','))) throw new LocalError('invalid_configuration');
+      try { validateUuid(args.message_id); if (args.receipt_token !== undefined) validateUuid(args.receipt_token); } catch { throw new LocalError('invalid_configuration'); }
       active();
       return inbox.transaction(() => {
         const receipt = inbox.db.prepare('SELECT receipt_token,acknowledged_at FROM cooperative_receipts WHERE message_id=?').get(args.message_id);
-        if (!receipt || receipt.receipt_token !== args.receipt_token) throw new LocalError('receipt_required');
+        if (!receipt || args.receipt_token !== undefined && receipt.receipt_token !== args.receipt_token) {
+          const error = new LocalError('receipt_required', {field: receipt ? 'receipt_token' : 'message_id'});
+          error.message = receipt ? 'The supplied legacy read receipt does not match. Nothing was acknowledged; this is not a transient network error. Omit the token and use the exact previously read message_id.' : 'Read this exact message in this inbox before acknowledging it. Nothing was acknowledged; this is not a transient network error.';
+          throw error;
+        }
         if (receipt.acknowledged_at == null) {
           const head = inbox.head();
           if (!head || head.message_id !== args.message_id || head.state !== 'pending') throw new LocalError('unsafe_boundary');

package/src/installation.mjs

@@ -37,8 +37,9 @@ export async function readInstallation(directory = installationDirectory()) {
   return selected ? readExistingConnection(selected.connectionFile) : undefined;
 }
 /** No network. Compare-and-swap fences concurrent UI flows; never deletes old bundles/inboxes. */
-export async function selectInstallation({ directory = installationDirectory(), connectionFile, expectedRevision, signal, pendingFlowId }) {
+export async function selectInstallation({ directory = installationDirectory(), connectionFile, expectedRevision, signal, pendingFlowId, verify }) {
   await readExistingConnection(connectionFile); // exact broker approval receipt, type, URL and token binding
+  if (verify !== undefined && (typeof verify !== 'function' || !await verify())) throw new Error('psst_setup_binding_changed');
   return withSelectionLock(directory, () => {
   let temp;
   try {

package/src/message-format.mjs

@@ -0,0 +1,26 @@
+import { canonical, validateEnvelope } from '../vendor/broker/src/protocol.mjs';
+import { provenance as legacyProvenance } from '../vendor/broker/reference/runtime.mjs';
+import { LocalError } from '../vendor/broker/reference/errors.mjs';
+
+export const NATIVE_FORMAT = 'compact-v1';
+
+// Versioned presentation only. Wire validation/authenticated origin and native
+// custom-message role are unchanged. Do not change compact-v1 after publication:
+// persisted handoffs must reconcile against the exact format originally sent.
+export function nativeMessage(rawEnvelope, format = NATIVE_FORMAT) {
+  if (format === null || format === 'legacy-v1') return legacyProvenance(rawEnvelope);
+  if (format !== NATIVE_FORMAT) throw new LocalError('invalid_configuration');
+  const envelope = validateEnvelope(rawEnvelope);
+  const sender = { name: envelope.sender.name, client_type: envelope.sender.client_type };
+  if (envelope.sender.project?.trim()) sender.project = envelope.sender.project;
+  const model = {};
+  for (const key of ['provider', 'id']) if (envelope.sender.model[key]?.trim()) model[key] = envelope.sender.model[key];
+  if (Object.keys(model).length) sender.model = { ...model, source: envelope.sender.model.source };
+  const data = { message_id: envelope.message_id, sender, text: envelope.content.text };
+  if (envelope.correlation_id) data.correlation_id = envelope.correlation_id;
+  if (envelope.reply_to_message_id) data.reply_to_message_id = envelope.reply_to_message_id;
+  // ASCII controls are JSON escaped; escape terminal/bidi controls as well.
+  const escaped = canonical(data).replace(/[\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/gu,
+    char => `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}`);
+  return `Broker message from AI agent ${envelope.sender.client_id}\n${escaped}`;
+}

package/src/native-plugin.mjs

@@ -1,4 +1,5 @@
-import { ACK_DEFINITION } from './tool-catalog.mjs';
+import { deliveryCapability } from './capabilities.mjs';
+import { ACK_DEFINITION, DIAGNOSTIC_RECEIVE_DEFINITION } from './tool-catalog.mjs';
 import { mkdtempSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -10,7 +11,7 @@ import { contextMarker } from './native-context.mjs';
 const validId = value => typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,256}$/.test(value);
 /** Native, session-keyed cooperative tools. Does not attach to or control a TUI. */
 export async function createNativePlugin({ native, tool, reference, config, clientFactory, experimentalNativeDelivery = false, connectFile = async path => readConfig(path),
-  loadInstallation = async () => undefined, contextReceiver, onDispose, adapterFactory = createOpenCodeAdapter }) {
+  loadInstallation = async () => undefined, contextReceiver, onDispose, adapterFactory = createOpenCodeAdapter, env = process.env }) {
   const directory = realpathSync(native.directory), worktree = realpathSync(native.worktree);
   const sessions = new Map();
   const connections = new Map(), disconnected = new Set(), connectionErrors = new Map();
@@ -124,7 +125,7 @@ export async function createNativePlugin({ native, tool, reference, config, clie
     try { return await state.starting; }
     catch (error) { if (sessions.get(id) === state) sessions.delete(id); throw error; }
   }
-  const catalog = [...reference.TOOL_DEFINITIONS, ACK_DEFINITION];
+  const catalog = [...reference.TOOL_DEFINITIONS.map(def => def.name === 'broker_receive' ? DIAGNOSTIC_RECEIVE_DEFINITION : def), ACK_DEFINITION];
   const proxies = Object.fromEntries(catalog.map(definition => [definition.name, tool({
     description: definition.description,
     args: nativeShape(tool.schema, definition.inputSchema),
@@ -150,7 +151,7 @@ export async function createNativePlugin({ native, tool, reference, config, clie
       for (const [name, description] of Object.entries({
         'psst-connect': 'Connect this session using an absolute private pairing/connection file path (never a secret).',
         'psst-disconnect': 'Stop Psst messaging in this session.',
-        'psst-status': 'Show this session’s Psst connection status.',
+        'psst-status': 'Show transport, exact client address and automatic-delivery readiness separately.',
         'psst-peers': 'List currently addressable Psst peers.',
       })) {
         if (value.command[name]) throw new Error('psst_command_conflict');
@@ -181,14 +182,15 @@ export async function createNativePlugin({ native, tool, reference, config, clie
           disconnected.delete(input.sessionID);
           try { await getSession(input.sessionID); }
           catch (error) { connections.delete(input.sessionID); throw error; }
-          result = { connected: true, delivery: experimentalNativeDelivery ? 'experimental_fixed_snapshot' : 'cooperative_pull',
+          result = { connected: true, ...deliveryCapability(env, {experimental: experimentalNativeDelivery}), client_id: sessions.get(input.sessionID)?.client?.inbox?.identity?.client_id ?? null,
             ...(experimentalNativeDelivery ? { fixed_native_selection: selected, warning: 'Experimental snapshot only; no atomic native selection lease. Changing agent/model disconnects messaging.' } : {}) }; 
         } else if (input.command === 'psst-disconnect') {
           disconnected.add(input.sessionID); connections.delete(input.sessionID); await close(input.sessionID);
           result = { connected: false };
         } else if (input.command === 'psst-status') {
           const state = sessions.get(input.sessionID);
-          result = { connected: !!state?.adapter, delivery: state?.delivery ? 'experimental_fixed_snapshot' : 'cooperative_pull',
+          result = { connected: !!state?.client, ...deliveryCapability(env, {experimental: !!state?.delivery}),
+            client_id: state?.client?.inbox?.identity?.client_id ?? null, identity_scope: 'native_session',
             last_delivery_status: state?.deliveryStatus ?? null,
             credential_id: state?.enrollment?.credentialId ?? null, expires_at: state?.enrollment?.expiresAt ?? null,
             connection_error: connectionErrors.get(input.sessionID) ?? null };

package/src/opencode-adapter.mjs

@@ -1,8 +1,9 @@
+import { createToolScope } from './tool-scope.mjs';
 import { createCooperativeInbox } from './cooperative-inbox.mjs';
-import { ACK_DEFINITION } from './tool-catalog.mjs';
+import { ACK_DEFINITION, DIAGNOSTIC_RECEIVE_DEFINITION } from './tool-catalog.mjs';
 import { isAbsolute, normalize } from 'node:path';
 
-const TOOL_NAMES = ['broker_list_clients', 'broker_send', 'broker_update_metadata', 'broker_message_status', 'broker_receive'];
+const TOOL_NAMES = ['broker_list_clients', 'broker_send', 'broker_update_metadata', 'broker_message_status', 'broker_receive', 'broker_sent_history', 'broker_message_content', 'broker_resend', 'broker_cancel'];
 const localId = value => typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,256}$/.test(value);
 const absolute = value => typeof value === 'string' && isAbsolute(value) && normalize(value) === value;
 const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -62,13 +63,15 @@ function displayJSON(value) {
  * are insufficient lifetime proof. No automatic plugin attachment is implied.
  */
 export function createOpenCodeAdapter({ reference, tool, binding, currentBinding,
-  client, inbox = client?.inbox, observeMetadata = null, onDiagnostic = () => {}, cooperativeAck = false }) {
+  client, inbox = client?.inbox, observeMetadata = null, onDiagnostic = () => {}, cooperativeAck = false, operationContext = null, closeSessionOnStop = true }) {
   if (!reference || typeof reference.AdapterRuntime !== 'function' || typeof reference.createTools !== 'function'
     || typeof reference.invokeTool !== 'function' || typeof reference.safeError !== 'function'
     || typeof reference.LocalError !== 'function' || !Array.isArray(reference.TOOL_DEFINITIONS)
     || typeof tool !== 'function' || !tool.schema || !client || !inbox
     || !binding || !localId(binding.sessionID) || !absolute(binding.directory) || !absolute(binding.worktree)
     || typeof binding.lifetime !== 'symbol' || !(binding.signal instanceof AbortSignal)
+    || typeof closeSessionOnStop !== 'boolean'
+    || operationContext !== null && typeof operationContext !== 'function'
     || typeof currentBinding !== 'function' || observeMetadata !== null && typeof observeMetadata !== 'function'
     || inbox.identity?.client_type !== 'opencode' || client.inbox !== inbox) {
     throw new Error('Invalid adapter configuration: provide a verified exact host binding and shared broker reference objects.');
@@ -78,13 +81,17 @@ export function createOpenCodeAdapter({ reference, tool, binding, currentBinding
     || new Set(definitions.map(definition => definition.name)).size !== TOOL_NAMES.length) {
     throw new Error('Shared tool catalog changed; review it before enabling this adapter.');
   }
-  const catalog = [...definitions, ...(cooperativeAck ? [ACK_DEFINITION] : [])].map(definition => {
+  const catalog = [...definitions, ...(cooperativeAck ? [ACK_DEFINITION] : [])].map(original => {
+    const definition = cooperativeAck && original.name === 'broker_receive' ? DIAGNOSTIC_RECEIVE_DEFINITION : original;
     const args = nativeShape(tool.schema, definition.inputSchema);
     return { definition, args, validator: tool.schema.object(args).strict() };
   });
   const expected = Object.freeze({ sessionID: binding.sessionID, directory: binding.directory,
     worktree: binding.worktree, lifetime: binding.lifetime, signal: binding.signal });
   const identity = Object.freeze({ ...inbox.identity });
+  const toolScope = createToolScope({ closedError: () => new reference.LocalError('session_mismatch', { effect: 'unknown' }), abortedError: () => new reference.LocalError('request_aborted') });
+  const recoveryAbort = new AbortController();
+  let recoveryPromise;
   let started = false, closed = false, startPromise, runtimeStartPromise, stopPromise;
   const diagnostic = code => { try { onDiagnostic({ code }); } catch { /* No raw exception data. */ } };
   function sameIdentity(candidate) {
@@ -104,16 +111,19 @@ export function createOpenCodeAdapter({ reference, tool, binding, currentBinding
     onDiagnostic: entry => diagnostic(entry.code) });
   async function stop() {
     if (stopPromise) return stopPromise;
-    closed = true; started = false;
+    closed = true; started = false; recoveryAbort.abort();
+    const toolsClosed = toolScope.close();
     expected.signal.removeEventListener('abort', onClose);
+    // Fence transport lifetime synchronously, before any deferred tool drain.
+    const runtimeStopped = runtime.stop({ closeSession: false });
     stopPromise = Promise.resolve().then(async () => {
       try {
-        await runtime.stop({ closeSession: false }); // Cancel, but do not close a stale pre-reconnect epoch.
+        await runtimeStopped; // Cancel, but do not close a stale pre-reconnect epoch.
         await runtimeStartPromise?.catch(() => {});
         // Registration may have committed after cancellation. Keep
         // its journal open until a second close fences that exact late lease.
-        await runtime.stop();
-      } finally { inbox.close(); }
+        await runtime.stop({ closeSession: closeSessionOnStop });
+      } finally { await toolsClosed; await recoveryPromise?.catch(() => {}); inbox.close(); }
     });
     return stopPromise;
   }
@@ -141,6 +151,11 @@ export function createOpenCodeAdapter({ reference, tool, binding, currentBinding
         runtimeStartPromise = runtime.start(metadata);
         const result = await runtimeStartPromise;
         await assertBound(undefined, 'unknown');
+        // No durable tool-call ID exists in this pinned ToolContext. Reconcile
+        // private operations after exact-session reattachment, never guess from text/messageID.
+        recoveryPromise = client.recoverOutgoing?.({ limit: 10, signal: AbortSignal.any([recoveryAbort.signal, expected.signal, AbortSignal.timeout(5000)]) });
+        await recoveryPromise?.catch(() => diagnostic('outgoing_recovery_incomplete'));
+        await assertBound(undefined, 'unknown');
         started = true;
         return result;
       } catch (error) {
@@ -153,6 +168,7 @@ export function createOpenCodeAdapter({ reference, tool, binding, currentBinding
   const tools = Object.fromEntries(catalog.map(({ definition, args, validator }) => {
     return [definition.name, tool({ description: definition.description, args,
       async execute(arguments_, context) {
+        return toolScope.run(async operationSignal => {
         try {
           if (!started || !context) throw new reference.LocalError('session_mismatch');
           await assertBound(context);
@@ -160,8 +176,9 @@ export function createOpenCodeAdapter({ reference, tool, binding, currentBinding
           if (!parsed.success) throw new reference.LocalError('invalid_configuration', { field: 'arguments' });
           // Per-invocation closure, never a mutable global current tool context.
           const scopedClient = { inbox, get attachment() { return client.attachment; },
-            prepareSend: (...args_) => client.prepareSend(...args_) };
-          for (const method of ['listClients', 'sendPrepared', 'updateMetadata', 'messageStatus', 'refreshOwnedMetadata']) {
+            prepareSend: (...args_) => client.prepareSend(...args_),
+            prepareResend: (...args_) => client.prepareResend(...args_) };
+          for (const method of ['listClients', 'sendPrepared', 'updateMetadata', 'messageStatus', 'refreshOwnedMetadata', 'resendPrepared', 'sentHistory', 'messageContent', 'cancelMessage']) {
             scopedClient[method] = async (...args_) => {
               await assertBound(context);
               return client[method](...args_);
@@ -170,20 +187,19 @@ export function createOpenCodeAdapter({ reference, tool, binding, currentBinding
           const facade = reference.createTools({ client: scopedClient, inbox, observeMetadata,
             cooperativeBoundary: async read => { await assertBound(context); return read(); } });
           if (cooperativeInbox) Object.assign(facade, cooperativeInbox);
-          const result = await reference.invokeTool(facade, definition.name, parsed.data);
+          const result = await reference.invokeTool(facade, definition.name, parsed.data, { ...(operationContext ? operationContext(context) : {}), signal: AbortSignal.any([operationSignal, expected.signal]) });
           // Unknown/cancelled host results never get repackaged as acceptance.
-          // A write may already have committed; retain its stable send key.
+          // The private outgoing ledger retains any uncertain operation and its key.
           try { await assertBound(context, 'unknown'); }
           catch (error) {
             const failure = reference.safeError(error);
-            const sendKey = result?.send_key ?? parsed.data.send_key;
-            if (definition.name === 'broker_send' && typeof sendKey === 'string') failure.send_key = sendKey;
             return displayJSON(failure);
           }
           return displayJSON(result);
         } catch (error) { return displayJSON(reference.safeError(error)); }
+        }, context?.abort).catch(error => displayJSON(reference.safeError(error)));
       },
     })];
   }));
-  return Object.freeze({ tools, start, stop, localMode: 'cooperative_pull' });
+  return Object.freeze({ tools, start, stop, localMode: 'diagnostic_pull' });
 }

package/src/reference-pin.mjs

@@ -1,15 +1,15 @@
 import { readFileSync, lstatSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
-export const REFERENCE_COMMIT = 'ba2219cd87a1feac23e01b23d2c2b3d3bdd65359';
+export const REFERENCE_COMMIT = '2de9cc3758b9fc593f5afca4fc501fd013d416ec';
 const HASHES = Object.freeze({
-  "reference/inbox.mjs": "93f75786eab29429ace024974e0f61d6ad46d2c5fe065dae387e54fd2373b167",
-  "reference/client.mjs": "f661b45acba106be03d97dacba3cd90ac18b09e7ff9eb93b995d5036d9d1c785",
+  "reference/inbox.mjs": "fbf0fa6096996cb9bc3f928e55f3eca496420880a03460e993dda3417b32ad88",
+  "reference/client.mjs": "c4c313e937d1003f28928a672072b926022aa0e9fd65825bc5db1078eb90afa9",
   "reference/runtime.mjs": "8733076b73a42ab8f12fe20ba9908acdd754d89734ffd335e84b49aee9d737ca",
-  "reference/tools.mjs": "5e6355cef1bec56170dca14b93142a7da8c102f411c5dbf437d84acda7351acf",
-  "reference/mcp-stdio.mjs": "10a93788af426ce898c398e38dd41ac77b6e0129a7697bdc36c8d4f6d6e20138",
+  "reference/tools.mjs": "5d3b16212a048912395d74b95a8b590d278b8b0915bb0bd7a0c3d80daf353839",
+  "reference/mcp-stdio.mjs": "f34b0cdcda9c2d607815e4ef99f1ba80fbd8936ef8c2893a858b6d408bc0ff09",
   "reference/errors.mjs": "e33231d94f514b5a1b59fdd4184f5881dd3712bde725a1cf53352c26293452ac",
-  "src/protocol.mjs": "f3ff24b4429dddc8a9c10513ab72dbc613c91244591132458c7866a812d6316b"
+  "src/protocol.mjs": "2d88829971643d47430d6696d0a6ac61589ea4f9001c860c5c196ecc5ac21a6f"
 });
 /** Verify reviewed source bytes before importing any trusted local module. */
 export function verifyReference(directory) {

package/src/reference.mjs

@@ -2,7 +2,7 @@ import { verifyReference } from './reference-pin.mjs';
 import { isAbsolute, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-export const BROKER_REFERENCE_COMMIT = 'ba2219cd87a1feac23e01b23d2c2b3d3bdd65359';
+export const BROKER_REFERENCE_COMMIT = '2de9cc3758b9fc593f5afca4fc501fd013d416ec';
 
 /** Trusted operator path to a pinned broker checkout; never a model argument. */
 export async function loadBrokerReference(directory = fileURLToPath(new URL('../vendor/broker', import.meta.url))) {

package/src/setup-ui.mjs

@@ -75,7 +75,7 @@ Approve only the matching OpenCode request. Close to pause; setup resumes this s
             close(); api.ui.dialog.clear();
             toast(process.env.PSST_CONFIG_FILE
               ? 'Approved installation saved. The explicit PSST_CONFIG_FILE override still takes precedence; restart without it to use the saved approval. Existing connections are unchanged.'
-              : 'Approved installation saved. New sessions connect automatically; existing sessions retain their authorization. Receive remains cooperative.', 'success');
+              : 'Approved installation saved; transport can reconnect. Automatic messaging is blocked on this classic host; /psst-status explains the missing capability. Manual receive is diagnostic/test-only.', 'warning');
           }
           if (prior && prior.state !== 'pending' && (prior.state !== 'approved' || selected?.connectionFile === prior.connectionFile)) {
             replace(() => api.ui.DialogConfirm({ title: 'Replace Psst authorization?',

package/src/tool-catalog.mjs

@@ -1,6 +1,11 @@
 export const ACK_DEFINITION = Object.freeze({ name: 'broker_acknowledge',
-  description: 'Explicitly acknowledge reading the exact message returned by broker_receive, using its receipt_token. Advances your local inbox. This is not approval of its instructions, proof of action success, or a native injection receipt.',
+  description: 'Explicitly acknowledge reading the exact message returned by broker_receive, using its message_id. The connector resolves the previously exposed local receipt internally; omit receipt_token normally. A supplied legacy token must still match exactly. Advances your local inbox. This is not approval of its instructions, proof of action success, or a native injection receipt.',
   inputSchema: { type: 'object', additionalProperties: false, properties: {
     message_id: { type: 'string', format: 'uuid' }, receipt_token: { type: 'string', format: 'uuid' },
-  }, required: ['message_id', 'receipt_token'] },
+  }, required: ['message_id'] },
+});
+
+export const DIAGNOSTIC_RECEIVE_DEFINITION = Object.freeze({ name: 'broker_receive',
+  description: 'Diagnostic/test-only manual read, only when the user explicitly requested a manual transport test. Set diagnostic:true. Production automatic readiness is blocked on this classic host; this is not a fallback. Read then explicitly acknowledge message_id.',
+  inputSchema: { type: 'object', additionalProperties: false, properties: { diagnostic: { type: 'boolean' } }, required: ['diagnostic'] },
 });

package/src/tool-scope.mjs

@@ -0,0 +1,26 @@
+/** An owner's admitted tool calls must settle before its private ledger closes. */
+export function createToolScope({ closedError = () => new Error('tool_scope_closed'), abortedError = () => new Error('tool_call_aborted') } = {}) {
+  const controller = new AbortController(), pending = new Set();
+  let closed = false, closing;
+  return Object.freeze({
+    run(task, callerSignal) {
+      if (closed) return Promise.reject(closedError());
+      const signal = callerSignal instanceof AbortSignal
+        ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
+      const operation = Promise.resolve().then(() => {
+        if (closed) throw closedError();
+        if (signal.aborted) throw abortedError();
+        return task(signal);
+      });
+      pending.add(operation);
+      void operation.then(() => pending.delete(operation), () => pending.delete(operation));
+      return operation;
+    },
+    close() {
+      if (closing) return closing;
+      closed = true; controller.abort();
+      closing = Promise.allSettled([...pending]).then(() => {});
+      return closing;
+    },
+  });
+}

package/src/v2-delivery.mjs

@@ -0,0 +1,149 @@
+import { randomUUID } from 'node:crypto';
+import { canonical } from '../vendor/broker/src/protocol.mjs';
+import { nativeMessage, NATIVE_FORMAT } from './message-format.mjs';
+
+export const V2_HOST_VERSION = '2.2.5';
+const id = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,256}$/.test(value);
+export function v2SessionBinding(info, hostID) {
+  if (!id(info?.id) || !id(hostID) || !id(info?.projectID)
+    || !Number.isSafeInteger(info?.time?.created) || info.time.created <= 0
+    || typeof info?.location?.directory !== 'string' || !info.location.directory.startsWith('/')) throw new Error('v2_session_binding_unavailable');
+  return { hostID, sessionID: info.id, created: info.time.created, projectID: info.projectID,
+    location: { directory: info.location.directory, ...(info.location.workspaceID ? { workspaceID: info.location.workspaceID } : {}) } };
+}
+
+/** Native V2 queue admission, never classic promptAsync or a human-role prompt.
+ * A successful receipt means durable native admission, NOT model consumption.
+ * No mutation retry: native cancellation removes its idempotency lookup row.
+ */
+export function createV2Delivery({ session, inbox, binding, signal, verify, interval = 250,
+  requestTimeout = 2000, onDiagnostic = () => {} }) {
+  if (!session || ['synthetic', 'context'].some(key => typeof session[key] !== 'function')
+    || !(signal instanceof AbortSignal) || typeof verify !== 'function' || !id(binding?.sessionID)
+    || !Number.isSafeInteger(interval) || interval < 10 || interval > 60000
+    || !Number.isSafeInteger(requestTimeout) || requestTimeout < 10 || requestTimeout > 30000) throw new Error('v2_capability_unavailable');
+  inbox.transaction(() => inbox.db.exec('CREATE TABLE IF NOT EXISTS v2_state(key TEXT PRIMARY KEY, value TEXT NOT NULL)'));
+  const getState = key => { inbox.assertUsable(); const row = inbox.db.prepare('SELECT value FROM v2_state WHERE key=?').get(key); return row ? JSON.parse(row.value) : null; };
+  const setState = (key, value) => inbox.transaction(() => inbox.db.prepare('INSERT INTO v2_state(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run(key, canonical(value)));
+  const persisted = getState('v2_binding');
+  if (persisted && canonical(persisted) !== canonical(binding)) throw new Error('v2_session_mismatch');
+  if (!persisted) setState('v2_binding', binding);
+  inbox.transaction(() => inbox.db.exec(`CREATE TABLE IF NOT EXISTS v2_submissions (
+    broker_message_id TEXT PRIMARY KEY REFERENCES inbox(message_id) ON DELETE CASCADE,
+    native_id TEXT NOT NULL UNIQUE, injection_id TEXT NOT NULL, payload TEXT NOT NULL,
+    promoted INTEGER NOT NULL DEFAULT 0)`));
+  let stopped = false, running, timer, epoch = 0;
+  const active = () => !stopped && !signal.aborted;
+  const diagnostic = code => { try { onDiagnostic({ code }); } catch {} };
+  async function call(method, input, permitted = active) {
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(requestTimeout)]);
+    let listener;
+    try {
+      return await Promise.race([
+        Promise.resolve().then(() => { if (bounded.aborted || !permitted()) throw new Error('v2_request_aborted'); return method(input, { signal: bounded }); }),
+        new Promise((_, reject) => { listener = () => reject(new Error('v2_request_incomplete'));
+          if (bounded.aborted) listener(); else bounded.addEventListener('abort', listener, { once: true }); }),
+      ]);
+    } finally { bounded.removeEventListener('abort', listener); }
+  }
+  async function current() {
+    if (!active()) return null;
+    const info = await verify();
+    if (!active() || !info || canonical(v2SessionBinding(info, binding.hostID)) !== canonical(binding)
+      || info.revert || info.time?.archived) return null;
+    return info;
+  }
+  function exactPayload(candidate, target) {
+    return candidate && canonical(candidate) === target.payload;
+  }
+  function exactAdmission(receipt, target) {
+    return receipt?.id === target.native_id && receipt.sessionID === binding.sessionID
+      && receipt.type === 'synthetic' && receipt.delivery === 'queue' && exactPayload(receipt.payload, target);
+  }
+  function exactContext(message, target) {
+    return message?.id === target.native_id && message.type === 'synthetic'
+      && exactPayload({ text: message.text, description: message.description, metadata: message.metadata }, target);
+  }
+  async function contextProof(target) {
+    const messages = await call(session.context.bind(session), { sessionID: binding.sessionID });
+    if (!Array.isArray(messages)) return false;
+    return messages.some(message => exactContext(message, target));
+  }
+  function accept(head, target) {
+    inbox.recordNativeAcceptance(head.message_id, target.injection_id, {
+      accepted: true, receipt_id: `${binding.sessionID}/${target.native_id}`,
+    });
+  }
+  async function deliver() {
+    const observedEpoch = epoch;
+    const info = await current();
+    if (!info) return;
+    // Interrupt/failure is durable across reload. Never wake a cancelled or
+    // failed session just because the broker has another pending envelope.
+    const idle = info.time.idle ?? 0, busy = info.time.busy ?? 0;
+    if (['interrupted', 'failed'].includes(info.outcome) && idle >= busy || getState('v2_paused')) return;
+    const head = inbox.head();
+    if (!head) return;
+    if (head.state !== 'pending') {
+      const target = inbox.db.prepare('SELECT * FROM v2_submissions WHERE broker_message_id=?').get(head.message_id);
+      if (!target || target.injection_id !== head.injection_id) return;
+      if (await contextProof(target) && active() && observedEpoch === epoch && await current()) {
+        accept(head, target);
+        inbox.transaction(() => inbox.db.prepare('UPDATE v2_submissions SET promoted=1 WHERE broker_message_id=?').run(head.message_id));
+        diagnostic('native_admission_reconciled');
+      }
+      return;
+    }
+    // Bound native backlog to one outstanding item. A lost delivered event is
+    // recovered by exact read-only context inspection, never another submit.
+    const outstanding = inbox.db.prepare('SELECT * FROM v2_submissions WHERE promoted=0 ORDER BY rowid LIMIT 1').get();
+    if (outstanding) {
+      if (!await contextProof(outstanding)) return;
+      if (!active() || observedEpoch !== epoch || !await current()) return;
+      inbox.transaction(() => inbox.db.prepare('UPDATE v2_submissions SET promoted=1 WHERE broker_message_id=?').run(outstanding.broker_message_id));
+    }
+    if (!active() || observedEpoch !== epoch || !await current()) return;
+    const payload = { text: nativeMessage(head.envelope), description: 'Psst agent message', metadata: {
+      source: 'psst', broker_message_id: head.message_id, sender_client_id: head.envelope.sender.client_id, format: NATIVE_FORMAT,
+    } };
+    const target = { native_id: 'msg_psst_' + randomUUID().replaceAll('-', ''), injection_id: randomUUID(), payload: canonical(payload) };
+    // State and exact immutable payload are committed atomically before effect.
+    inbox.transaction(() => {
+      const now = inbox.head();
+      if (now?.message_id !== head.message_id || now.state !== 'pending') throw new Error('v2_inbox_changed');
+      inbox.db.prepare('INSERT INTO v2_submissions(broker_message_id,native_id,injection_id,payload) VALUES(?,?,?,?)')
+        .run(head.message_id, target.native_id, target.injection_id, target.payload);
+      inbox.db.prepare("UPDATE inbox SET state='injecting',injection_id=? WHERE message_id=?").run(target.injection_id, head.message_id);
+    }, { growth: Buffer.byteLength(target.payload) * 2 + 8192 });
+    // Even an aborted request may have reached the server. Leave its journal
+    // pinned, including on timeout, exception, cancellation or payload mismatch.
+    if (!active() || observedEpoch !== epoch) return;
+    try {
+      const receipt = await call(session.synthetic.bind(session), { sessionID: binding.sessionID,
+        id: target.native_id, ...payload, delivery: 'queue', resume: true }, () => active() && observedEpoch === epoch);
+      if (!active() || observedEpoch !== epoch || !await current()) return;
+      if (!exactAdmission(receipt, target)) { diagnostic('native_receipt_mismatch'); return; }
+      accept(head, target);
+      diagnostic('native_admission_confirmed');
+    } catch { diagnostic('native_admission_uncertain'); }
+  }
+  function tick() {
+    if (!active() || running) return running;
+    running = Promise.resolve().then(deliver).catch(() => diagnostic('native_delivery_paused')).finally(() => { running = null; });
+    return running;
+  }
+  return {
+    tick,
+    start() { if (!timer && active()) { timer = setInterval(tick, interval); timer.unref?.(); } },
+    event(event) {
+      if (!active() || event?.data?.sessionID !== binding.sessionID) return;
+      if (['session.execution.interrupted', 'session.execution.failed', 'session.inbox.cancelled', 'session.revert.staged'].includes(event.type)) {
+        epoch++; setState('v2_paused', event.type); diagnostic('native_delivery_paused');
+      }
+      // Only host-started work, not an idle poll, can reopen cancellation.
+      if (event.type === 'session.execution.started') setState('v2_paused', null);
+      if (['session.deleted', 'session.moved', 'session.archived'].includes(event.type)) { epoch++; stopped = true; clearInterval(timer); }
+    },
+    async stop() { stopped = true; epoch++; clearInterval(timer); await running; },
+  };
+}

package/src/v2-inbox.mjs

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto';
+import { openSync, closeSync, readFileSync, writeFileSync, fsyncSync, fstatSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { canonical } from '../vendor/broker/src/protocol.mjs';
+import { privateDirectory } from './config.mjs';
+
+/** Reopen only this installation + native server store + exact native session.
+ * Exclusive Inbox ownership protects concurrent owners. Never reset a partial,
+ * foreign or unreadable manifest: its broker/native effects may be unknown.
+ */
+export function openV2Inbox({ reference, settings, binding }) {
+  const key = createHash('sha256').update(canonical({ binding, broker: settings.broker.url })).digest('hex');
+  const directory = privateDirectory(join(privateDirectory(settings.stateDirectory), 'opencode-v2-' + key));
+  const path = join(directory, 'binding.json');
+  let fd;
+  try {
+    fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    writeFileSync(fd, canonical({ version: 1, binding, broker: settings.broker.url, identity: reference.newSessionIdentity('opencode') }) + '\n');
+    fsyncSync(fd); closeSync(fd); fd = undefined;
+    const parent = openSync(directory, constants.O_RDONLY); try { fsyncSync(parent); } finally { closeSync(parent); }
+  } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  finally { if (fd !== undefined) closeSync(fd); }
+  fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let manifest;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077 || stat.size > 8192 || process.getuid && stat.uid !== process.getuid()) throw new Error('v2_binding_unavailable');
+    manifest = JSON.parse(readFileSync(fd, 'utf8'));
+  } finally { closeSync(fd); }
+  if (manifest.version !== 1 || manifest.broker !== settings.broker.url || canonical(manifest.binding) !== canonical(binding)
+    || Object.keys(manifest).sort().join(',') !== 'binding,broker,identity,version') throw new Error('v2_binding_mismatch');
+  return new reference.Inbox({ directory, identity: manifest.identity });
+}

package/src/v2-lock.mjs

@@ -0,0 +1,17 @@
+import { DatabaseSync } from 'node:sqlite';
+import { openSync, closeSync, lstatSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { privateDirectory } from './config.mjs';
+
+/** Cross-location/process ownership, released by the OS on crash. No stale reset. */
+export async function withV2Lock(directory, name, action) {
+  if (!['host-anchor','setup'].includes(name)) throw new Error('v2_lock_invalid');
+  const path=join(privateDirectory(directory),`v2-${name}-owner.sqlite`);
+  try { const fd=openSync(path,constants.O_CREAT|constants.O_EXCL|constants.O_WRONLY|constants.O_NOFOLLOW,0o600);closeSync(fd); }
+  catch(error){if(error.code!=='EEXIST')throw error;}
+  const stat=lstatSync(path);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.mode&0o077||process.getuid&&stat.uid!==process.getuid())throw new Error('v2_lock_invalid');
+  let db;
+  try{db=new DatabaseSync(path);db.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner(id INTEGER)');return await action();}
+  finally{db?.close();}
+}