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

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/pending-resume.mjs

@@ -0,0 +1,38 @@
+import { loadApprovalHelper } from './approval-helper.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { installationDirectory, readPending, updatePending, selectInstallation } from './installation.mjs';
+/** GET-only continuation of an explicitly persisted request. Never creates credentials. */
+export function startPendingResume({ directory = installationDirectory(), loadHelper = loadApprovalHelper,
+  pause = (signal, ms = 2000) => delay(ms, undefined, { signal }), select = selectInstallation } = {}) {
+ const controller = new AbortController();
+ const done = (async () => {
+  let pending;
+  try { pending=readPending(directory); } catch { return; }
+  if(!pending || pending.paused)return;
+  const flowId=pending.flowId;
+  const helper=await loadHelper();
+  while(!controller.signal.aborted) {
+   let waitMs=2000;
+   try {
+    pending=readPending(directory);
+    if(!pending||pending.flowId!==flowId||pending.paused)return;
+    const options={directory,brokerUrl:pending.brokerUrl,clientType:'opencode'};
+    const saved=helper.readApprovalState(options);
+    if(!saved || pending.requestId && saved.requestId!==pending.requestId)return;
+    const result=await helper.pollApproval(options); // Deliberately no beginApproval anywhere in this module.
+    if(controller.signal.aborted)return;
+    if(result.requestId!==saved.requestId)return;
+    if(result.state==='approved') {
+     await select({directory,connectionFile:result.connectionFile,expectedRevision:pending.expectedRevision,pendingFlowId:flowId,signal:controller.signal});
+     return;
+    }
+    if(result.state!=='pending') { updatePending({directory,flowId,paused:true});return; }
+   } catch(error) {
+    if(!error.retryable)return; // Invalid local/auth state is inert; never reset or replace it.
+    waitMs=Math.min(300000,Math.max(2000,error.retryAfterMs||2000));
+   }
+   await pause(controller.signal,waitMs);
+  }
+ })().catch(()=>{});
+ return {done,stop:()=>controller.abort()};
+}

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

@@ -0,0 +1,100 @@
+import { loadApprovalHelper } from './approval-helper.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { installationDirectory, readSelection, selectInstallation, savePending, updatePending } from './installation.mjs';
+
+/** Host-owned form, not a model tool or a conversation command. */
+export async function installSetupUI(api, { directory = installationDirectory(), loadHelper = loadApprovalHelper,
+  select = selectInstallation, pause = (signal, ms = 2000) => delay(ms, undefined, { signal }) } = {}) {
+  let current, pending;
+  const cancel = (pause = true) => {
+    current?.abort(); current = undefined;
+    if (pause && pending) { try { updatePending({ directory, flowId: pending.flowId, paused: true }); } catch {} }
+    pending = undefined;
+  };
+  api.lifecycle.onDispose(() => cancel(false));
+  function toast(message, variant = 'info') { api.ui.toast({ title: 'Psst', message, variant, duration: 6000 }); }
+  function start() {
+    cancel();
+    const controller = new AbortController(); current = controller;
+    const alive = () => current === controller && !controller.signal.aborted && !api.lifecycle.signal.aborted;
+    let submitted = false, transitioning = false;
+    const close = () => { if (!transitioning && current === controller) cancel(); };
+    function replace(render) { transitioning = true; try { api.ui.dialog.replace(render, close); } finally { transitioning = false; } }
+    replace(() => api.ui.DialogPrompt({
+      title: 'Psst setup — broker URL', placeholder: 'https://broker.example',
+      onCancel: close,
+      onConfirm: async value => {
+        if (!alive() || submitted) return;
+        submitted = true;
+        try {
+          const brokerUrl = new URL(value.trim());
+          if (brokerUrl.protocol !== 'https:' || brokerUrl.username || brokerUrl.password || brokerUrl.search || brokerUrl.hash || brokerUrl.pathname !== '/') throw new Error();
+          const helper = await loadHelper();
+          if (!alive()) return;
+          const selected = readSelection(directory);
+          const expectedRevision = selected?.revision ?? null;
+          const options = { directory, brokerUrl: brokerUrl.href, clientType: 'opencode' };
+          const prior = helper.readApprovalState(options);
+          async function enroll(replaceRequestId) {
+            if (!alive()) return;
+            pending = savePending({ directory, brokerUrl: brokerUrl.href, expectedRevision, requestId: replaceRequestId ? null : prior?.requestId ?? null });
+            const flowId = pending.flowId;
+            replace(() => api.ui.DialogAlert({ title: 'Psst approval pending',
+              message: 'Preparing the durable request. Close to pause; setup resumes the same request.',
+              onConfirm: close }));
+            async function retry(operation) {
+              while (alive()) {
+                try { return await operation(); }
+                catch (error) { if (!error.retryable) throw error; await pause(controller.signal, Math.min(300000, Math.max(2000, error.retryAfterMs || 2000))); }
+              }
+              throw new Error('psst_setup_cancelled');
+            }
+            let result = await retry(() => helper.beginApproval({ ...options, ...(replaceRequestId ? { replaceRequestId } : {}) }));
+            const requestId = result.requestId;
+            if (!replaceRequestId && prior?.state === 'pending' && requestId !== prior.requestId) throw new Error('psst_request_changed');
+            if (alive()) {
+              updatePending({ directory, flowId, requestId });
+              if (result.state === 'pending') replace(() => api.ui.DialogAlert({
+                title: 'Psst approval pending',
+                message: `Open ${new URL('/admin', brokerUrl).href}
+Request ID: ${requestId}
+Approve only the matching OpenCode request. Close to pause; setup resumes this same request.`,
+                onConfirm: close }));
+            }
+            while (alive() && result.state === 'pending') {
+              await pause(controller.signal);
+              if (alive()) {
+                result = await retry(() => helper.pollApproval(options));
+                if (result.requestId !== requestId) throw new Error('psst_request_changed');
+              }
+            }
+            if (!alive()) return;
+            if (result.state !== 'approved') { toast(`Request ${result.state}. Run setup explicitly to request replacement.`, 'warning'); close(); api.ui.dialog.clear(); return; }
+            await select({ directory, connectionFile: result.connectionFile, expectedRevision, signal: controller.signal, pendingFlowId: flowId });
+            if (!alive()) return;
+            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; 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?',
+              message: 'Request a new authorization? The current connection and unread messages remain unchanged until approval; existing sessions keep their connection.',
+              onCancel: close, onConfirm: () => {
+                // The native confirmation clears its dialog after this callback.
+                transitioning = true; queueMicrotask(() => { transitioning = false; void enroll(prior.requestId).catch(failed); });
+              } }));
+          } else await enroll();
+        } catch { failed(); }
+        function failed() {
+          if (!alive()) return;
+          toast('Setup paused. Check the URL, private configuration and broker availability; retry setup to resume the same request. No credentials were replaced.', 'warning');
+          cancel(false); api.ui.dialog.clear();
+        }
+      },
+    }));
+  }
+  api.keymap.registerLayer({ commands: [{ name: 'psst.setup', title: 'Psst: setup broker connection',
+    category: 'Psst', namespace: 'palette', slashName: 'psst-setup', run: start }],
+    bindings: [{ key: 'ctrl+alt+p', cmd: 'psst.setup', desc: 'Set up Psst broker connection' }] });
+}

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();}
+}