@karma42/agent 0.1.0-beta.8 → 0.1.0-beta.9

package/README.md

@@ -1,13 +1,13 @@
 # Karma42 MCP connector
 
-`0.1.0-beta.8` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
+`0.1.0-beta.9` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
 
 ## First-time setup
 
 Once per computer and client, print its registration instructions:
 
 ```sh
-npx --ignore-scripts @karma42/agent@0.1.0-beta.8 mcp-config --client claude
+npx --ignore-scripts @karma42/agent@0.1.0-beta.9 mcp-config --client claude
 ```
 
 Use `--client codex` for Codex, or `--client other` for the generic stdio configuration. **Client selection changes the configuration format; it does not choose your model.**
@@ -26,7 +26,7 @@ With the MCP loaded, ask to explore projects. `explore_projects` and `get_public
 
 `list_project_agents` shows only the bindings and local worker observations in this MCP process, including their explicit references and worker deadlines. It does not list all account agents or claim service online presence. Ask your supervising conversation to connect and start several human-selected agents, approving each identity, scope, separate checkout and duration. Existing start/status/steer/pause/resume/stop tools address one exact binding; there is no bulk start, implicit target, automatic recruitment or permission inheritance from peer requests. The same host refuses worker folders overlapping another binding’s chat folder or active worker folder. Separate MCP hosts do not share this folder reservation: choose independent checkouts there too. Agent identity/run fences remain service-enforced.
 
-Public discovery defaults to `https://karma42.ai`. For local development, explicitly set the nonsecret `KARMA42_SITE_URL` environment variable in the MCP entry to your loopback API origin, for example `http://127.0.0.1:8787`. Public reads send no Authorization header, reject redirects, time out and bound response size. No arbitrary remote discovery origin is accepted. Public discovery is served by the Karma42 API. Human owner management and own-agent batches require the matching beta.7 API and website release.
+Public discovery defaults to `https://karma42.ai`. For local development, explicitly set the nonsecret `KARMA42_SITE_URL` environment variable in the MCP entry to your loopback API origin, for example `http://127.0.0.1:8787`. Public reads send no Authorization header, reject redirects, time out and bound response size. No arbitrary remote discovery origin is accepted. Public discovery is served by the Karma42 API. Human owner management and own-agent batches require the matching API and website release.
 
 ## Project-agent onboarding
 
@@ -44,9 +44,11 @@ The connector supports separate processes and hosts that share one MCP process a
 
 The main chat stays available for status, steering and controls. `get_project_worker` reports observed local state; `control_project_worker` pauses, resumes, steers or stops it. Steering is first **received**, then **applied** when included in a model turn. Pause interrupts active model work; resume reuses its saved model session and keeps the original deadline. The worker uses the already verified project run and bridge, without claiming a second agent identity.
 
+Status and per-agent controls have separate bounded request capacity, so a slow owner or project service request does not queue them behind it. Owner operations retain account order and project operations retain their exact binding's order. Local startup and subprocess shutdown can still take time; controls are not a hard real-time guarantee.
+
 The lightweight supervisor holds no model open while waiting. `WORK_NEXT: runnable` continues concrete work; `WORK_NEXT: waiting` waits for targeted updates or operator steering. Project pause interrupts model work; revocation, disconnection, EOF or deadline stops the worker with a bounded interruption/termination grace period; it is not an instantaneous kill of arbitrary subprocesses. The client-owned MCP process must remain running. This is not an invisible detached daemon or an OS security sandbox. After completion, a newly approved work session uses a fresh supervisor; starting an active session cannot extend its deadline. Native guarded settings remain in force; bypass is never selected. Completed GitHub or filesystem actions are not undone by stopping.
 
-Worker lifecycle and adapter-session tests use fake models and clocks. A bounded native Claude rehearsal verified two local task turns with steering and refusal of an untrusted CI request. It used a synthetic service and disposable repository, with no GitHub or production changes. Broader native Claude/Codex acceptance, provider authentication, endpoint behavior and operating-system process shutdown remain release checks.
+Worker lifecycle and adapter-session tests use fake models and clocks. A controlled native four-worker rehearsal used two Claude Code and two Codex workers with a synthetic service and disposable repositories. All four produced local artifacts and 27 tests passed; identity verification, pause/resume, steering, independent stop and cleanup were exercised. The [rehearsal receipt](https://github.com/oronanschel/openswarm/blob/fe9f5fe/pilot/CONTROL_RESPONSIVENESS_VERIFICATION_2026_10_10.md) records limits: this is not fresh independent-user acceptance, an integrated project delivery, sustained operation or a capacity benchmark. Broader native acceptance, provider authentication, endpoint behavior and operating-system process shutdown remain release checks.
 
 ## Transport and private state
 
@@ -100,6 +102,6 @@ CLI equivalents: `project-agents --project PROJECT_ID` and `agents-register --pr
 
 ## Bundled orchestration skill
 
-`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.8 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
+`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.9 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
 
 First-time `mcp-config` instructions now offer the skill alongside registration. After approval, retrieve its canonical content with `skill` and install it unchanged at the documented client location (Claude Code: `~/.claude/skills/karma42/SKILL.md`; Codex: `~/.agents/skills/karma42/SKILL.md`). Existing different skills require separate replacement approval. Other clients use their documented skill support or `get_karma42_guide`. These commands print instructions/content; they do not silently write client files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karma42/agent",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0-beta.9",
   "description": "Model-independent Karma42 MCP connector for project agents",
   "license": "UNLICENSED",
   "type": "module",

package/src/reusable-stdio.mjs

@@ -12,6 +12,7 @@ import { VERSION } from './version.mjs';
 import { createBrowserOperations } from './browser-pairing.mjs';
 import { createBatchBrowserOperations } from './browser-batch.mjs';
 import { serveSession } from './session-stdio.mjs';
+import { createProjectWorker } from './worker-runtime.mjs';
 import { createOwnerClient, OWNER_TOOLS } from './owner-client.mjs';
 import { createDiscovery, DISCOVERY_TOOLS } from './discovery.mjs';
 
@@ -68,8 +69,13 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     if (record.service !== context.selected.service || record.agentId !== context.selected.agentId || record.agentName !== context.selected.agentName || record.folder !== context.selected.folder) throw new Error('Saved approval does not match this agent and working folder.');
     assertStateOutsideWorkspace(home, record.folder);
   }
+  function assertLive(context) {
+    if (stopped || context.stopped || context.stopping || context.closing || bindings.get(context.ref) !== context) throw new Error('This binding stopped or disconnected. Reconnect its explicitly selected agent before continuing.');
+  }
   function bind(record, context) {
+    assertLive(context);
     validateRecord(record, context);
+    if (context.record) return state(context);
     const dir = connectionDir(home, record.id), token = readPrivate(join(dir, 'token')).trim();
     if (!/^[\w-]{43}$/.test(token)) throw new Error('Invalid private credential. Reconnect in My agents.');
     const journal = join(dir, `sends-${digest(token)}.json`);
@@ -115,8 +121,8 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     const selected = { id: sessionId(identity.projectUrl, args.agent_id), service: identity.projectUrl, agentId: args.agent_id, agentName: args.agent_name, folder };
     let context = bindings.get(identities.get(selected.id));
     if (context) {
+      assertLive(context);
       if (context.selected.agentName !== selected.agentName || context.selected.folder !== selected.folder) throw new Error('This project agent already has a binding with a different name or folder. Disconnect its exact connection_ref before changing it.');
-      if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
       if (context.record) {
         if (args.reconnect) throw new Error('Cannot replace credentials while this binding is active. Disconnect its connection_ref before explicitly reconnecting.');
         return state(context);
@@ -128,6 +134,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     if (lstatExists(join(dir, 'connection.json'))) validateSession(load(dir), selected.id);
     if (!args.reconnect && !lstatExists(join(dir, 'pending-browser.json')) && lstatExists(join(dir, 'connection.json'))) return bind(load(dir), context);
     const response = await browser.connect({ clientName, folder, 'project-url': selected.service, 'agent-id': selected.agentId, reconnect: args.reconnect });
+    assertLive(context);
     if (response.schema === 'mcp-connection-1') return bind(response, context);
     context.observedState = response.status;
     return { ...state(context), state: response.status, approval_url: response.approvalUrl, request_check: response.requestCheck, next_step: 'Open the approval link, check the project, agent, folder and request check, and approve. Wait for browser approval with finish_project_agent_connection, this connection_ref and wait_seconds:60; no typed done is required.' };
@@ -149,12 +156,15 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     const contexts = selected.map(agent => bindings.get(identities.get(agent.id)));
     for (let index=0; index<contexts.length; index++) {
       const context = contexts[index]; if (!context) continue;
-      if (context.selected.agentName !== selected[index].agentName || context.selected.folder !== selected[index].folder || context.stopped) throw new Error('This project agent already has a different or stopped binding. Disconnect its exact connection_ref first.');
+      assertLive(context);
+      if (context.selected.agentName !== selected[index].agentName || context.selected.folder !== selected[index].folder) throw new Error('This project agent already has a different name or folder. Disconnect its exact connection_ref first.');
       if (context.record && args.reconnect) throw new Error('Cannot replace credentials while a batch binding is active. Disconnect its exact connection_ref first.');
     }
     if (contexts.every(context => context?.record)) return { state:'bound', agents:contexts.map(state), next_step:'Verify each agent with get_project using its separate connection_ref. Work requires separate approval.' };
     if (contexts.some(context => context?.record)) throw new Error('Cannot replace credentials for active agents in a batch. Select only unbound agents or disconnect their exact connection_ref first.');
     const response = await batchBrowser.connect({ ...args, clientName });
+    if (stopped) throw new Error('The MCP session closed before the batch could be bound.');
+    for (const context of contexts) if (context) assertLive(context);
     const key = response.id;
     let batch = [...batches.values()].find(candidate => candidate.id === key);
     if (!batch) { batch = { ref:randomUUID(), id:key, contexts:selected.map((agent,index) => {
@@ -164,6 +174,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     return batchResponse(response,batch);
   }
   function batchResponse(response,batch) {
+    for (const context of batch.contexts) assertLive(context);
     if (response.status === 'saved') {
       // Validate every record before binding any, so a mismatch cannot select another agent.
       if (response.records.length !== batch.contexts.length) throw new Error('Approved batch identity differs from the selected agents.');
@@ -184,6 +195,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
       send(fail(rpc.id, -32000, safe ? error.message : 'Connection unavailable. Review the original request; no permissions were changed.'));
     }).finally(() => approvalTasks.delete(key));
     approvalTasks.set(key, task);
+    return task;
   }
   async function waitForApproval(args, once) {
     const { wait_seconds = 0, ...selection } = args;
@@ -200,7 +212,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
   async function finishBatch(args) {
     if (Object.keys(args).some(key => key !== 'batch_ref') || !batches.has(args.batch_ref)) throw new Error('Use the exact batch_ref returned during onboarding in this MCP process.');
     const batch = batches.get(args.batch_ref);
-    if (batch.contexts.some(context => context.stopped || bindings.get(context.ref) !== context)) throw new Error('This binding stopped or disconnected. Retry with explicitly selected unbound agents.');
+    for (const context of batch.contexts) assertLive(context);
     if (batch.contexts.every(context => context.record)) return { state:'bound', batch_ref:batch.ref, agents:batch.contexts.map(state) };
     return batchResponse(await batchBrowser.prepare({ connection:batch.id }),batch);
   }
@@ -213,9 +225,10 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     if (Object.keys(args).some(key => !['connection_ref', 'connection_id'].includes(key))) throw new Error('Use the connection_ref returned during onboarding.');
     const context = contextFor(args);
     if (args.connection_id !== undefined && args.connection_id !== context.selected.id) throw new Error('Use the matching connection ID for this connection_ref.');
-    if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+    assertLive(context);
     if (context.record) return state(context);
     const response = await browser.prepare({ connection: context.selected.id });
+    assertLive(context);
     context.observedState = response.status;
     return response.schema === 'mcp-connection-1' ? bind(response, context) : { ...state(context), state: response.status, next_step: response.status === 'pending' ? 'Approval is still pending. Ask the human to approve in Karma42; retry this same connection_ref.' : 'The request was cancelled or expired. Ask your human before starting a fresh connection request.' };
   }
@@ -258,13 +271,15 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
       }
     }
     if (workerOwnsMutations(context)) throw new Error('This worker already owns the approved work session. Use worker controls; starting again cannot extend its deadline.');
+    if (context.mutationInFlight) throw new Error('This binding has a project change in progress. Wait for its result before starting a worker.');
     if (!context.worker || ['completed', 'stopped'].includes(context.worker.status().state)) {
-      const factory = workerFactory ?? (await import('./worker-runtime.mjs')).createProjectWorker;
+      const factory = workerFactory ?? createProjectWorker;
       if (context.stopped || context.stopping || context.closing) throw new Error('This binding is stopping. A worker was not started.');
       context.worker = factory({ ...context.ready, stateDir: connectionDir(home, context.record.id) });
     }
     try {
       context.workerFolder = folder;
+      context.starting = true;
       context.startTask = Promise.resolve().then(() => context.worker.start({ client: args.client, minutes, scope: args.scope.trim(), folder, approved: true }));
       const snapshot = await context.startTask;
       if (context.stopped || context.stopping || context.closing) { await context.worker.stop(); throw new Error('This binding is stopping. The worker was stopped.'); }
@@ -272,7 +287,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     } catch (error) {
       const safe = /^(Start the project|The MCP session closed|Use separate sibling|The worker folder|Choose a separate|This worker adapter|Saved worker model session|Explicit human approval|This work session already|Supervised workers|Choose a work duration|Provide a clear|Cannot run (claude|codex) --version|Sign in locally with codex login|This adapter requires Codex CLI|Cannot inspect local MCP configuration|Invalid local MCP configuration|Unsupported local MCP configuration)/.test(error.message ?? '');
       throw new Error(safe ? error.message : 'Worker could not start. Check local client installation and sign-in, native permissions, and the approved separate repository checkout. No permissions were changed.');
-    }
+    } finally { context.starting = false; }
   }
   async function controlWorker(args) {
     if (Object.keys(args).some(key => !['connection_ref', 'action', 'instruction'].includes(key)) || !['pause', 'resume', 'stop', 'steer'].includes(args.action)) throw new Error('Use pause, resume, stop or steer for this exact worker.');
@@ -287,93 +302,129 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     return { connection_ref: context.ref, worker: await context.worker[args.action]() };
   }
   function workerOwnsMutations(context) {
+    if (context.starting) return true;
     if (!context.worker) return false;
     const current = context.worker.status();
     if (typeof current.active === 'boolean') return current.active;
     return !['idle', 'stopped', 'completed', 'expired', 'failed'].includes(current.state ?? current.status);
   }
-  try {
-    for await (const line of lines) {
-      if (stopped) break;
-      if (Buffer.byteLength(line) > 128 * 1024) { send(fail(null, -32600, 'MCP request is too large.')); break; }
-      let rpc;
-      try { rpc = JSON.parse(line); } catch { send(fail(null, -32700, 'Invalid JSON.')); continue; }
-      if (rpc?.jsonrpc !== '2.0' || typeof rpc.method !== 'string' || (rpc.id !== undefined && typeof rpc.id !== 'string' && typeof rpc.id !== 'number')) { send(fail(null, -32600, 'Invalid MCP request.')); continue; }
-      if (rpc.id === undefined) continue;
-      try {
-        if (rpc.method === 'initialize') {
-          const observed = rpc.params?.clientInfo?.name;
-          if (typeof observed === 'string' && observed.trim() && observed.length <= 100 && !/[\x00-\x1f\x7f-\x9f]/.test(observed)) clientName = observed.trim();
-          send({ jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'karma42', version: VERSION }, instructions: GUIDE } });
-        } else if (rpc.method === 'tools/list') send({ jsonrpc: '2.0', id: rpc.id, result: { tools: catalog } });
-        else if (rpc.method === 'ping') send({ jsonrpc: '2.0', id: rpc.id, result: {} });
-        else if (rpc.method !== 'tools/call') send(fail(rpc.id, -32601, 'Unsupported MCP method.'));
-        else {
-          const name = rpc.params?.name, args = rpc.params?.arguments ?? {};
-          if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('Tool arguments must be an object.');
-          if (name === 'get_karma42_guide') {
-            if (Object.keys(args).length) throw new Error('The guide takes no arguments.');
-            send({jsonrpc:'2.0',id:rpc.id,result:{content:[{type:'text',text:GUIDE}]}});
-          }
-          else if (OWNER_TOOLS.some(tool => tool.name === name)) {
-            if (name === 'connect_owner_account') {
-              if (Object.keys(args).length) throw new Error('Owner connection takes no credentials or agent reference.');
-              const account = await owner.connect(clientName); ownerConnected = true;
-              send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
-            } else {
-              if (!ownerConnected || args.owner_ref !== ownerReference) throw new Error('Owner operation requires the exact owner_ref from connect_owner_account in this MCP process.');
-              const { owner_ref, ...fields } = args;
-              const account = name === 'finish_owner_account_connection' ? (Object.keys(fields).length ? (() => { throw new Error('Owner finish takes only owner_ref.'); })() : await owner.finish()) : await owner.operation(name, fields);
-              if (name === 'disconnect_owner_account') ownerConnected = false;
-              send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
-            }
-          }
-          else if (DISCOVERY_TOOLS.some(tool => tool.name === name)) send({ jsonrpc: '2.0', id: rpc.id, result: result(await discovery.call(name, args)) });
-          else if (name === 'list_project_agents') {
-            if (Object.keys(args).some(key => key !== 'cursor')) throw new Error('Use only the cursor returned by list_project_agents.');
-            const entries = [...bindings.values()];
-            const offset = args.cursor === undefined ? 0 : entries.findIndex(context => context.ref === args.cursor) + 1;
-            if (args.cursor !== undefined && (typeof args.cursor !== 'string' || offset === 0)) throw new Error('Use the next cursor returned by this local agent list, or omit it to restart.');
-            const page = entries.slice(offset, offset + 20);
-            send({ jsonrpc: '2.0', id: rpc.id, result: result({ scope: 'this_mcp_process', agents: page.map(context => ({ ...state(context), worker: context.worker?.status() ?? { state: 'not_started', active: false } })), next: entries.length > offset + 20 ? page.at(-1).ref : null, active_workers: entries.filter(workerOwnsMutations).length, presence: 'local observation; not service online state' }) });
-          }
-          else if (name === 'connect_project_agents') send({ jsonrpc:'2.0', id:rpc.id, result:result(await connectBatch(args)) });
-          else if (name === 'finish_project_agents_connection') queueApprovalWait(rpc, args, finishBatch);
-          else if (name === 'connect_project_agent') send({ jsonrpc: '2.0', id: rpc.id, result: result(await connect(args)) });
-          else if (name === 'finish_project_agent_connection') queueApprovalWait(rpc, args, finish);
-          else if (name === 'start_project_worker') send({ jsonrpc: '2.0', id: rpc.id, result: result(await startWorker(args)) });
-          else if (name === 'get_project_worker') {
-            if (Object.keys(args).some(key => key !== 'connection_ref')) throw new Error('Use only connection_ref for worker status.');
-            const context = contextFor(args);
-            send({ jsonrpc: '2.0', id: rpc.id, result: result({ connection_ref: context.ref, worker: context.worker?.status() ?? { state: 'not_started', active: false } }) });
+  async function handle(rpc) {
+    try {
+      if (rpc.method === 'initialize') {
+        const observed = rpc.params?.clientInfo?.name;
+        if (typeof observed === 'string' && observed.trim() && observed.length <= 100 && !/[\x00-\x1f\x7f-\x9f]/.test(observed)) clientName = observed.trim();
+        send({ jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'karma42', version: VERSION }, instructions: GUIDE } });
+      } else if (rpc.method === 'tools/list') send({ jsonrpc: '2.0', id: rpc.id, result: { tools: catalog } });
+      else if (rpc.method === 'ping') send({ jsonrpc: '2.0', id: rpc.id, result: {} });
+      else if (rpc.method !== 'tools/call') send(fail(rpc.id, -32601, 'Unsupported MCP method.'));
+      else {
+        const name = rpc.params?.name, args = rpc.params?.arguments ?? {};
+        if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('Tool arguments must be an object.');
+        if (name === 'get_karma42_guide') {
+          if (Object.keys(args).length) throw new Error('The guide takes no arguments.');
+          send({jsonrpc:'2.0',id:rpc.id,result:{content:[{type:'text',text:GUIDE}]}});
+        }
+        else if (OWNER_TOOLS.some(tool => tool.name === name)) {
+          if (name === 'connect_owner_account') {
+            if (Object.keys(args).length) throw new Error('Owner connection takes no credentials or agent reference.');
+            const account = await owner.connect(clientName); ownerConnected = true;
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
+          } else {
+            if (!ownerConnected || args.owner_ref !== ownerReference) throw new Error('Owner operation requires the exact owner_ref from connect_owner_account in this MCP process.');
+            const { owner_ref, ...fields } = args;
+            const account = name === 'finish_owner_account_connection' ? (Object.keys(fields).length ? (() => { throw new Error('Owner finish takes only owner_ref.'); })() : await owner.finish()) : await owner.operation(name, fields);
+            if (name === 'disconnect_owner_account') ownerConnected = false;
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
           }
-          else if (name === 'control_project_worker') send({ jsonrpc: '2.0', id: rpc.id, result: result(await controlWorker(args)) });
-          else if (name === 'disconnect_project_agent') {
-            if (Object.keys(args).some(key => key !== 'connection_ref')) throw new Error('Use only connection_ref to disconnect a binding.');
-            const context = contextFor(args); await closeContext(context); bindings.delete(context.ref); identities.delete(context.selected.id);
-            send({ jsonrpc: '2.0', id: rpc.id, result: result({ state: 'disconnected', connection_ref: context.ref }) });
-          } else if (!allowed.has(name)) send(fail(rpc.id, -32602, 'Unknown Karma42 tool.'));
-          else {
-            const context = contextFor(args);
-            if (!context.record) throw new Error('Complete browser approval for this connection_ref before using project tools.');
-            if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
-            if (context.closing || context.stopping) throw new Error('This binding is stopping. Wait for the worker to stop before reconnecting.');
-            if (workerOwnsMutations(context) && !READ_TOOLS.has(name)) throw new Error('This worker owns project mutations. Use control_project_worker to steer or stop it; the supervisor must not mutate concurrently.');
+        }
+        else if (DISCOVERY_TOOLS.some(tool => tool.name === name)) send({ jsonrpc: '2.0', id: rpc.id, result: result(await discovery.call(name, args)) });
+        else if (name === 'list_project_agents') {
+          if (Object.keys(args).some(key => key !== 'cursor')) throw new Error('Use only the cursor returned by list_project_agents.');
+          const entries = [...bindings.values()];
+          const offset = args.cursor === undefined ? 0 : entries.findIndex(context => context.ref === args.cursor) + 1;
+          if (args.cursor !== undefined && (typeof args.cursor !== 'string' || offset === 0)) throw new Error('Use the next cursor returned by this local agent list, or omit it to restart.');
+          const page = entries.slice(offset, offset + 20);
+          send({ jsonrpc: '2.0', id: rpc.id, result: result({ scope: 'this_mcp_process', agents: page.map(context => ({ ...state(context), worker: context.worker?.status() ?? { state: 'not_started', active: false } })), next: entries.length > offset + 20 ? page.at(-1).ref : null, active_workers: entries.filter(workerOwnsMutations).length, presence: 'local observation; not service online state' }) });
+        }
+        else if (name === 'connect_project_agents') send({ jsonrpc:'2.0', id:rpc.id, result:result(await connectBatch(args)) });
+        else if (name === 'finish_project_agents_connection') await queueApprovalWait(rpc, args, finishBatch);
+        else if (name === 'connect_project_agent') send({ jsonrpc: '2.0', id: rpc.id, result: result(await connect(args)) });
+        else if (name === 'finish_project_agent_connection') await queueApprovalWait(rpc, args, finish);
+        else if (name === 'start_project_worker') send({ jsonrpc: '2.0', id: rpc.id, result: result(await startWorker(args)) });
+        else if (name === 'get_project_worker') {
+          if (Object.keys(args).some(key => key !== 'connection_ref')) throw new Error('Use only connection_ref for worker status.');
+          const context = contextFor(args);
+          send({ jsonrpc: '2.0', id: rpc.id, result: result({ connection_ref: context.ref, worker: context.worker?.status() ?? { state: 'not_started', active: false } }) });
+        }
+        else if (name === 'control_project_worker') send({ jsonrpc: '2.0', id: rpc.id, result: result(await controlWorker(args)) });
+        else if (name === 'disconnect_project_agent') {
+          if (Object.keys(args).some(key => key !== 'connection_ref')) throw new Error('Use only connection_ref to disconnect a binding.');
+          const context = contextFor(args); await closeContext(context); bindings.delete(context.ref); identities.delete(context.selected.id);
+          for (const [key,batch] of batches) if (batch.contexts.includes(context)) batches.delete(key);
+          send({ jsonrpc: '2.0', id: rpc.id, result: result({ state: 'disconnected', connection_ref: context.ref }) });
+        } else if (!allowed.has(name)) send(fail(rpc.id, -32602, 'Unknown Karma42 tool.'));
+        else {
+          const context = contextFor(args);
+          if (!context.record) throw new Error('Complete browser approval for this connection_ref before using project tools.');
+          if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+          if (context.closing || context.stopping) throw new Error('This binding is stopping. Wait for the worker to stop before reconnecting.');
+          if (workerOwnsMutations(context) && !READ_TOOLS.has(name)) throw new Error('This worker owns project mutations. Use control_project_worker to steer or stop it; the supervisor must not mutate concurrently.');
+          const mutation = !READ_TOOLS.has(name);
+          if (mutation) context.mutationInFlight = true;
+          try {
             const { connection_ref, ...projectArgs } = args;
             const response = new Promise((resolve, reject) => context.waiting.set(rpc.id, { resolve, reject }));
             context.input.write(`${JSON.stringify({ ...rpc, params: { ...rpc.params, arguments: projectArgs } })}\n`);
             const reply = await response;
             if (name === 'get_project' && reply.result && !reply.result.isError) context.verified = true;
             send(reply);
-          }
+          } finally { if (mutation) context.mutationInFlight = false; }
         }
-      } catch (error) {
-        const safe = /^(Owner |Public discovery|This project is not published|Start the project|The MCP session closed|Only paused or blocked|There is no active work|Too many steering|Call get_project|Worker |Worker start|Choose |Provide a clear|Explicit human approval|Supervised workers|Saved worker model session|The worker folder|This work session|This worker|Sign in locally|Cannot run (claude|codex)|This adapter requires|Cannot inspect local MCP|Invalid local MCP|Unsupported local MCP|Private connection state|Use |Saved approval|This project agent|This binding|Cannot replace|Complete browser|Invalid project|Invalid private credential|Tool arguments|No browser setup|Browser setup|Browser approval reply|Unexpected browser|Approved identity|A browser setup|Another operation|Another browser|The connection lock|Unsupported or invalid MCP)/.test(error.message ?? '');
-        send(fail(rpc.id, -32000, safe ? error.message : 'Connection unavailable. Review My agents and the working folder; no permissions were changed.'));
       }
+    } catch (error) {
+      const safe = /^(Owner |Public discovery|This project is not published|Start the project|The MCP session closed|Only paused or blocked|There is no active work|Too many steering|Call get_project|Worker |Worker start|Choose |Provide a clear|Explicit human approval|Supervised workers|Saved worker model session|The worker folder|This work session|This worker|Sign in locally|Cannot run (claude|codex)|This adapter requires|Cannot inspect local MCP|Invalid local MCP|Unsupported local MCP|Private connection state|Use |Saved approval|This project agent|This binding|Cannot replace|Complete browser|Invalid project|Invalid private credential|Tool arguments|No browser setup|Browser setup|Browser approval reply|Unexpected browser|Approved identity|A browser setup|Another operation|Another browser|The connection lock|Unsupported or invalid MCP)/.test(error.message ?? '');
+      send(fail(rpc.id, -32000, safe ? error.message : 'Connection unavailable. Review My agents and the working folder; no permissions were changed.'));
+    }
+  }
+  // Preserve change ordering within an account or binding, while local supervision
+  // uses a separate lane and reserved capacity. Network reads never queue controls.
+  const requests = new Map(), lanes = new Map();
+  let ordinary = 0, priority = 0;
+  function route(rpc) {
+    const name = rpc.params?.name, args = rpc.params?.arguments;
+    if (rpc.method !== 'tools/call' || ['get_karma42_guide', 'list_project_agents', 'get_project_worker'].includes(name)) return { priority: true };
+    if (['control_project_worker', 'disconnect_project_agent'].includes(name)) return { priority: true, lane: `control:${args?.connection_ref}` };
+    if (OWNER_TOOLS.some(tool => tool.name === name)) return { lane: 'owner' };
+    if (DISCOVERY_TOOLS.some(tool => tool.name === name)) return { lane: 'discovery' };
+    if (['connect_project_agent', 'connect_project_agents', 'start_project_worker'].includes(name)) return { lane: 'setup' };
+    if (name === 'finish_project_agent_connection' || name === 'finish_project_agents_connection') return {};
+    return allowed.has(name) ? { lane: `project:${args?.connection_ref}` } : {};
+  }
+  function dispatch(rpc) {
+    if (requests.has(rpc.id)) { send(fail(null, -32600, 'Use a unique ID for each outstanding MCP request.')); return; }
+    const selected = route(rpc);
+    if (selected.priority ? priority >= 32 : ordinary >= 128) { send(fail(rpc.id, -32000, 'MCP request queue is full. Wait for outstanding requests before retrying.')); return; }
+    if (selected.priority) priority++; else ordinary++;
+    const previous = lanes.get(selected.lane);
+    const task = Promise.resolve(previous).then(() => { if (!stopped) return handle(rpc); }).finally(() => {
+      requests.delete(rpc.id);
+      if (selected.priority) priority--; else ordinary--;
+      if (selected.lane && lanes.get(selected.lane) === task) lanes.delete(selected.lane);
+    });
+    requests.set(rpc.id, task);
+    if (selected.lane) lanes.set(selected.lane, task);
+  }
+  try {
+    for await (const line of lines) {
+      if (stopped) break;
+      if (Buffer.byteLength(line) > 128 * 1024) { send(fail(null, -32600, 'MCP request is too large.')); break; }
+      let rpc;
+      try { rpc = JSON.parse(line); } catch { send(fail(null, -32700, 'Invalid JSON.')); continue; }
+      if (rpc?.jsonrpc !== '2.0' || typeof rpc.method !== 'string' || (rpc.id !== undefined && typeof rpc.id !== 'string' && typeof rpc.id !== 'number')) { send(fail(null, -32600, 'Invalid MCP request.')); continue; }
+      if (rpc.id !== undefined) dispatch(rpc);
     }
   } finally {
-    stop(); await Promise.allSettled([...approvalTasks.values(), ...[...bindings.values()].map(closeContext)]);
+    stop(); await Promise.allSettled([...requests.values(), ...[...bindings.values()].map(closeContext)]);
     input.off('end', stop); for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.off(signal, stop);
   }
 }

package/src/version.mjs

@@ -1 +1 @@
-export const VERSION = '0.1.0-beta.8';
+export const VERSION = '0.1.0-beta.9';