@karma42/agent 0.0.0-stage → 0.1.0-beta.10

package/src/owner-client.mjs

@@ -0,0 +1,109 @@
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { canonicalPath, ensureHome, privateDir, readPrivate, writePrivate, lstatExists, digest } from './state.mjs';
+import { sessionHome } from './session.mjs';
+import { withBrowserLock } from './browser-pairing.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const TOKEN = /^[\w-]{43}$/;
+const ID = /^[a-f0-9]{64}$/;
+const object = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const ownerRef = { type: 'string', description: 'Opaque owner_ref returned for your browser-approved human account. Never use an agent connection_ref.' };
+const project = { type: 'string', pattern: '^[a-f0-9]{64}$' };
+const revision = { type: 'integer', minimum: 0 };
+const requestId = { type: 'string', pattern: '^[\\w-]{1,64}$', description: 'Keep this request ID and the original input when retrying a lost response.' };
+export const OWNER_TOOLS = [
+  { name: 'connect_owner_account', description: 'Connect your human Karma42 account for owner management through browser sign-in and explicit approval. Separate from agent identity; no project or model starts. Returns owner_ref and a browser approval link, or reuses an unexpired approved account.', inputSchema: object({}) },
+  { name: 'finish_owner_account_connection', description: 'Check this human account approval once. Reuse the same owner_ref after lost replies; do not create another approval request.', inputSchema: object({ owner_ref: ownerRef }, ['owner_ref']) },
+  { name: 'list_my_projects', description: 'List your human account’s own proposals and owned projects with states and next steps. Does not use an agent’s identity.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, cursor: { type: 'string', maxLength: 500 } }, ['owner_ref']) },
+  { name: 'list_my_proposals', description: 'Check your own project proposal statuses and reviewer feedback.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, cursor: { type: 'string', maxLength: 500 } }, ['owner_ref']) },
+  { name: 'get_my_proposal', description: 'Read your own proposal status, review feedback and next step.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project }, ['owner_ref', 'project_id']) },
+  { name: 'get_owned_project_status', description: 'Read the owned project’s state, readiness, contributors and blockers before starting it.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project }, ['owner_ref', 'project_id']) },
+  { name: 'start_owned_project', description: 'Start this project only after your human explicitly instructs it and reviews current readiness. Uses optimistic revision and idempotent request ID. Starting the project does not launch participants’ models.', inputSchema: object({ owner_ref: ownerRef, project_id: project, expected_revision: revision, client_request_id: requestId, start_without_minimum: { type: 'boolean', description: 'True only if the human explicitly approves starting below the contributor minimum.' }, approved: { type: 'boolean', const: true } }, ['owner_ref', 'project_id', 'expected_revision', 'client_request_id', 'approved']) },
+  { name: 'list_owned_project_members', description: 'List project members and current project roles so the owner can select an exact person and membership revision.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project, cursor: { type: 'string', maxLength: 500 } }, ['owner_ref', 'project_id']) },
+  { name: 'set_owned_project_role', description: 'After explicit owner instruction, assign an existing participant’s project member/moderator/admin role. These are project roles only; this never grants platform reviewer or co-founder permissions. Requires the current membership revision and an idempotent request ID.', inputSchema: object({ owner_ref: ownerRef, project_id: project, email: { type: 'string', maxLength: 254 }, role: { type: 'string', enum: ['member', 'moderator', 'admin'] }, expected_revision: revision, client_request_id: requestId, approved: { type: 'boolean', const: true } }, ['owner_ref', 'project_id', 'email', 'role', 'expected_revision', 'client_request_id', 'approved']) },
+  { name: 'list_my_project_agents', description: 'List only your own registered agent identities in a project you own. Returns authoritative IDs/names for selecting a team; not worker or online status.', annotations: { readOnlyHint: true }, inputSchema: object({ owner_ref: ownerRef, project_id: project }, ['owner_ref','project_id']) },
+  { name: 'register_my_project_agents', description: 'After the human approves the exact team names, atomically register 1–10 identities under that human account in its owned project. Retry the same names and client_request_id after lost replies. Creates no connection, worker, model, folder or GitHub changes. New owner approval must include register_own_agents. Use returned IDs for separate batch connection approval.', inputSchema: object({ owner_ref: ownerRef, project_id: project, names: { type:'array', minItems:1, maxItems:10, uniqueItems:true, items:{type:'string',pattern:'^[\\w-]{1,64}$'} }, client_request_id:requestId, approved:{type:'boolean',const:true} }, ['owner_ref','project_id','names','client_request_id','approved']) },
+  { name: 'disconnect_owner_account', description: 'Revoke this saved human management connection. Agent bindings and running agents are separate and remain unchanged.', inputSchema: object({ owner_ref: ownerRef }, ['owner_ref']) },
+];
+export function ownerOrigin(site) {
+  const u = new URL(site ?? process.env.KARMA42_SITE_URL ?? 'https://karma42.ai');
+  if (u.username || u.password || u.search || u.hash || u.pathname !== '/' || !(u.protocol === 'https:' && ['karma42.ai', 'karma42-beta.web.app'].includes(u.hostname) && !u.port || u.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(u.hostname))) throw new Error('Owner management requires the Karma42 website or explicit loopback development origin.');
+  return u.origin;
+}
+export function createOwnerClient({ home = sessionHome(), site, fetchImpl = fetch, now = Date.now } = {}) {
+  const origin = ownerOrigin(site); home = canonicalPath(home);
+  function directory() { ensureHome(home); const root = join(home, 'owners'); privateDir(root); const dir = join(root, digest(origin)); privateDir(dir); return dir; }
+  function receipt() {
+    const p = join(directory(), 'owner.json'); if (!lstatExists(p)) return null;
+    const r = readPrivate(p, true);
+    if (r.schema !== 'karma42-owner-1' || r.origin !== origin || !/^[a-f0-9-]{36}$/.test(r.requestId ?? '') || !TOKEN.test(r.pollingSecret ?? '') || !TOKEN.test(r.token ?? '') || !['pending','approved','expired','cancelled','revoked'].includes(r.status)) throw new Error('Owner connection state is invalid. No credentials were changed.');
+    return r;
+  }
+  const save = r => writePrivate(join(directory(), 'owner.json'), r);
+  async function request(path, { method = 'GET', body, token, poll } = {}) {
+    let response;
+    try { response = await fetchImpl(new URL('/api/owner' + path, origin), { method, redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(15000), headers: { Accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}), ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(poll ? { Authorization: `Bearer ${poll}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) }); }
+    catch { throw new Error('Owner service unavailable. Retry the same request; no permissions were changed.'); }
+    let size = 0, chunks = [];
+    for await (const c of response.body) { size += c.byteLength; if (size > 256 * 1024) { await response.body.cancel?.().catch(() => {}); throw new Error('Owner service returned an oversized response.'); } chunks.push(c); }
+    let data; try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw new Error('Owner service returned an invalid response.'); }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Owner service returned an invalid response.');
+    if (!response.ok) {
+      const detail = response.status < 500 && typeof data.message === 'string' && data.message.length <= 500 && !/[\x00-\x1f\x7f-\x9f]/.test(data.message) ? data.message : null;
+      throw new Error(response.status === 401 ? 'Owner account authorization expired or was revoked. Sign in again.' : detail ? `Owner operation refused: ${detail}` : 'Owner operation refused. Read current status and review the original request before retrying.');
+    }
+    return data;
+  }
+  function publicState(r) {
+    const url = new URL('/viewer/', origin); url.searchParams.set('view','owner-connect'); url.searchParams.set('request',r.requestId);
+    return { status: r.status, owner_id: digest(origin), account_name: r.personName ?? null, expires_at: r.connectionExpiresAt ?? r.expiresAt ?? null, ...(r.status === 'pending' ? { approval_url: url.href, request_check: r.verificationCode, next_step: 'Sign in and approve human project management on Karma42. Then finish this same connection.' } : {}), scope: r.scopes ?? ['read_projects','start_projects','manage_project_roles'], agent_work_started: false };
+  }
+  async function connect(clientName = 'Karma42 CLI') {
+    return withBrowserLock(directory(), async () => {
+      let r = receipt();
+      if (r?.status === 'approved' && r.connectionExpiresAt > now()) return publicState(r);
+      if (!r || ['expired','cancelled','revoked','approved'].includes(r.status)) { r = { schema:'karma42-owner-1', origin, requestId:randomUUID(), pollingSecret:randomBytes(32).toString('base64url'), token:randomBytes(32).toString('base64url'), clientName, registerOwnAgents:true, status:'pending' }; save(r); }
+      const response = await request('/connect', { method:'POST', body:{ requestId:r.requestId, pollingSecret:r.pollingSecret, candidateTokenHash:hash(r.token), clientName:r.clientName, registerOwnAgents:r.registerOwnAgents===true } });
+      if (response.requestId !== r.requestId || !['pending','approved','expired','cancelled'].includes(response.status)) throw new Error('Owner service returned an invalid connection response. Retry this saved request.');
+      r = { ...r, status:response.status === 'approved' ? 'pending' : response.status, expiresAt:response.expiresAt, verificationCode:response.verificationCode, ...(Array.isArray(response.scopes) ? {scopes:response.scopes} : {}) }; save(r);
+      return publicState(r);
+    });
+  }
+  async function finish() {
+    return withBrowserLock(directory(), async () => {
+      const r = receipt(); if (!r) throw new Error('Owner connection has not been requested. Connect your human account first.');
+      if (r.status === 'approved' && r.connectionExpiresAt > now()) return publicState(r);
+      const response = await request(`/connect/${r.requestId}`, { poll:r.pollingSecret });
+      if (!['pending','approved','expired','cancelled'].includes(response.status) || response.status === 'approved' && (!Number.isFinite(response.connectionExpiresAt) || response.connectionExpiresAt <= now() || typeof response.personName !== 'string')) throw new Error('Owner service returned an invalid approval response.');
+      const saved = { ...r, ...response }; save(saved); return publicState(saved);
+    });
+  }
+  async function operation(name, args) {
+    const r = receipt(); if (!r || r.status !== 'approved' || r.connectionExpiresAt <= now()) throw new Error('Owner account requires browser sign-in and approval first.');
+    const specs = { list_my_project_agents:[`/projects/${args.project_id}/agents`], register_my_project_agents:[`/projects/${args.project_id}/agents`,'POST'], list_my_projects:['/projects'], list_my_proposals:['/proposals'], get_my_proposal:[`/proposals/${args.project_id}`], get_owned_project_status:[`/projects/${args.project_id}/status`], list_owned_project_members:[`/projects/${args.project_id}/members`], start_owned_project:[`/projects/${args.project_id}/start`,'POST'], set_owned_project_role:[`/projects/${args.project_id}/members`,'POST'], disconnect_owner_account:['/connections/revoke','POST'] };
+    if (!specs[name]) throw new Error('Owner operation is unknown.');
+    if ((name.includes('owned_project') || name === 'get_my_proposal' || name === 'list_my_project_agents' || name === 'register_my_project_agents') && !ID.test(args.project_id ?? '')) throw new Error('Owner operation requires an exact project ID from your project list.');
+    const schema = OWNER_TOOLS.find(t=>t.name===name).inputSchema;
+    if (Object.keys(args).some(k=>!Object.hasOwn(schema.properties,k))) throw new Error('Owner operation accepts only documented fields.');
+    if (args.cursor !== undefined && (typeof args.cursor !== 'string' || args.cursor.length > 500)) throw new Error('Owner cursor is invalid.');
+    let [path,method = 'GET'] = specs[name], body;
+    if (name === 'start_owned_project' || name === 'set_owned_project_role') {
+      if (args.approved !== true || !Number.isSafeInteger(args.expected_revision) || args.expected_revision < 0 || !/^[\w-]{1,64}$/.test(args.client_request_id ?? '')) throw new Error('Owner mutation requires explicit human approval, current revision and the original request ID.');
+      body = { expected_revision:args.expected_revision, client_request_id:args.client_request_id };
+      if (name === 'start_owned_project') { if (args.start_without_minimum !== undefined && typeof args.start_without_minimum !== 'boolean') throw new Error('Owner minimum override must be explicitly selected.'); if (args.start_without_minimum !== undefined) body.start_without_minimum=args.start_without_minimum; }
+      else { if (!['member','moderator','admin'].includes(args.role) || typeof args.email !== 'string' || args.email.length>254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(args.email)) throw new Error('Owner role assignment requires an existing participant email and project member, moderator or admin role.'); Object.assign(body,{ email:args.email,role:args.role,remove:false }); }
+    }
+    if (name === 'register_my_project_agents') {
+      if (args.approved !== true || !/^[\w-]{1,64}$/.test(args.client_request_id ?? '') || !Array.isArray(args.names) || args.names.length < 1 || args.names.length > 10 || new Set(args.names).size !== args.names.length || args.names.some(n => typeof n !== 'string' || !/^[\w-]{1,64}$/.test(n))) throw new Error('Owner team registration requires approved distinct names and the original request ID.');
+      if (!r.scopes?.includes('register_own_agents')) throw new Error('Owner connection did not approve agent registration. Disconnect it and approve a new owner connection including that permission.');
+      body = { names:args.names,client_request_id:args.client_request_id,approved:true };
+    }
+    if (name === 'disconnect_owner_account') body = {};
+    if (args.cursor !== undefined) path += '?cursor=' + encodeURIComponent(args.cursor);
+    const response = await request(path,{method,body,token:r.token});
+    if (name === 'disconnect_owner_account') save({...r,status:'revoked'});
+    return response;
+  }
+  return { connect,finish,operation };
+}

package/src/project-identity.mjs

@@ -0,0 +1,15 @@
+import { isAbsolute } from 'node:path';
+function clean(value, label) {
+  if (typeof value !== 'string' || !value || value.length > 2048 || /[\x00-\x1f\x7f-\x9f]/.test(value)) throw new Error(`Provide a valid ${label}.`);
+  return value;
+}
+export function projectIdentity({ projectUrl, repo = 'https://github.com/placeholder/project', folder }) {
+  let url;
+  try { url = new URL(clean(projectUrl, 'project URL')); } catch { throw new Error('Use a Karma42 project service URL.'); }
+  if (!['https:', 'http:'].includes(url.protocol) || (url.protocol === 'http:' && !['localhost', '127.0.0.1'].includes(url.hostname)) || url.username || url.password || url.search || url.hash || !/^\/p\/[a-f0-9]{64}\/?$/.test(url.pathname)) throw new Error('Use an HTTPS project service URL ending in /p/PROJECT_ID, without credentials or query parameters.');
+  clean(repo, 'GitHub repository URL');
+  if (!/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/?$/.test(repo) || /\/(?:\.|\.\.)(?:\/|$)/.test(repo)) throw new Error('Use a GitHub repository URL without credentials, query parameters or fragments.');
+  clean(folder, 'absolute project folder');
+  if (!isAbsolute(folder)) throw new Error('Choose an absolute project folder.');
+  return { projectUrl: url.href.replace(/\/$/, ''), repo: repo.replace(/\/$/, ''), folder };
+}

package/src/reusable-stdio.mjs

@@ -0,0 +1,444 @@
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { PassThrough } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { join, isAbsolute } from 'node:path';
+import { verifyBundle } from './system.mjs';
+import { assertStateOutsideWorkspace, canonicalPath, connectionDir, digest, load, lstatExists, readPrivate } from './state.mjs';
+import { sessionHome, sessionId, validateSession } from './session.mjs';
+import { projectIdentity } from './project-identity.mjs';
+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 { workerRecoveryStatus, cancelWorkerRecovery } from './worker-recovery.mjs';
+import { createOwnerClient, OWNER_TOOLS } from './owner-client.mjs';
+import { createDiscovery, DISCOVERY_TOOLS } from './discovery.mjs';
+
+const objectSchema = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const approvalWaitSchema = { type: 'integer', minimum: 0, maximum: 60, default: 0, description: 'Wait without a model for browser approval, up to this many seconds. Reuse the same reference if still pending; no typed done is required.' };
+const reference = { type: 'string', description: 'Use the opaque connection_ref returned for this exact project agent. There is no default connection.' };
+const GUIDE = readFileSync(new URL('../skills/karma42/SKILL.md', import.meta.url), 'utf8');
+const BOOTSTRAP = [
+  { name:'get_karma42_guide', description:'Read the Karma42 owner/team orchestration skill before managing projects or assembling agents. No sign-in or connection needed.', annotations:{readOnlyHint:true}, inputSchema:objectSchema({},[]) },
+  { name: 'connect_project_agent', description: 'Connect one human-selected project agent. Reuse its approved local connection or return browser approval details. Returns an explicit connection_ref required by every project tool. No client settings, model or permissions are changed. Use the human-selected project/folder and exact agent IDs/names provided by the human or returned by the owner team tools.', inputSchema: objectSchema({ project_url: { type: 'string' }, agent_id: { type: 'string' }, agent_name: { type: 'string' }, folder: { type: 'string' }, reconnect: { type: 'boolean', description: 'Explicit human-approved replacement only; rotates credentials after browser approval.' } }, ['project_url', 'agent_id', 'agent_name', 'folder']) },
+  { name: 'finish_project_agent_connection', description: 'Check this binding’s browser approval and bind when approved. Optional wait_seconds waits within a bounded budget without blocking other agents. Retry the same connection_ref after a lost reply. Never edit client settings or create a new pairing merely to retry.', inputSchema: objectSchema({ connection_ref: reference, wait_seconds: approvalWaitSchema, connection_id: { type: 'string', description: 'Optional crosscheck with the connection ID returned during onboarding.' } }, ['connection_ref']) },
+  { name: 'disconnect_project_agent', description: 'Stop and release only this project-agent binding. Other bindings in a shared MCP process remain available. The connection_ref becomes invalid; private approved credentials are retained for explicit future reuse.', inputSchema: objectSchema({ connection_ref: reference }, ['connection_ref']) },
+];
+const BATCH_TOOLS = [
+  { name: 'connect_project_agents', description: 'Connect an exact batch of one to ten of your own project agents. One browser approval covers only these agents and folders in this project. Never approve another participant’s agents. Each credential and connection_ref remains independent; this does not start workers or grant work authorization.', inputSchema: objectSchema({ project_url: { type: 'string' }, agents: { type: 'array', minItems: 1, maxItems: 10, items: objectSchema({ agent_id: { type:'string' }, agent_name: { type:'string' }, folder: { type:'string' } }, ['agent_id','agent_name','folder']) }, reconnect: { type:'boolean', description:'Explicit human-approved replacement only.' } }, ['project_url','agents']) },
+  { name: 'finish_project_agents_connection', description: 'Check the exact batch_ref returned during onboarding and bind each approved agent separately. Optional wait_seconds waits within a bounded budget without blocking other agents. Retry this same batch after a lost reply. No worker is started.', inputSchema: objectSchema({ batch_ref: { type:'string' }, wait_seconds: approvalWaitSchema }, ['batch_ref']) },
+];
+const WORKER_TOOLS = [
+  { name: 'start_project_worker', description: 'After your human explicitly approves this work, start one supervised worker for this verified project agent. Uses the existing coordination connection and guarded native permissions. Return promptly; the supervisor can steer, pause or stop through worker controls. Requires a separate approved Git checkout/worktree matching the project repository, distinct from the connection/main-chat folder. Agents may self-organize within the shared approved mission; fixed roles are optional.', inputSchema: objectSchema({ connection_ref: reference, recovery_ref: { type: 'string', format: 'uuid', description: 'Only after explicit approval to recover the exact saved mission from get_project_worker. Repeat its saved client/model/scope/folder and omit minutes. Preserves the original deadline; never takes over a surviving supervisor or native process.' }, client: { type: 'string', enum: ['claude', 'codex'] }, model: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,149}$', description: 'Optional human-approved model ID or client alias. Omit for the client default; verify the actual model through worker status.' }, minutes: { type: 'integer', minimum: 15, maximum: 240, multipleOf: 15, default: 60 }, scope: { type: 'string', minLength: 1, maxLength: 4000 }, folder: { type: 'string' }, approved: { type: 'boolean', const: true, description: 'Set true only after the human explicitly approves this worker, duration, workspace and work scope. Connection approval alone is insufficient.' } }, ['connection_ref', 'client', 'scope', 'folder', 'approved']) },
+  { name: 'get_project_worker', description: 'Read this binding’s actual supervised worker status or saved mission recovery details after its supervisor ended. Reports model, last-turn usage, permission observations, original deadline, requested/applied steering and safe failure stage/code. Saved records are not live process observations. This does not restart work or extend the deadline.', inputSchema: objectSchema({ connection_ref: reference }, ['connection_ref']) },
+  { name: 'control_project_worker', description: 'Steer, pause, resume or stop only this binding’s supervised worker. Steering waits for the next natural model turn without interrupting active work; check requested/applied sequence rather than assuming delivery. Explicit pause/stop still interrupts execution. Resuming preserves the original deadline. Instruction is required only for steer.', inputSchema: objectSchema({ connection_ref: reference, action: { type: 'string', enum: ['pause', 'resume', 'stop', 'steer'] }, instruction: { type: 'string', minLength: 1, maxLength: 2000 } }, ['connection_ref', 'action']) },
+];
+const READ_TOOLS = new Set(['get_project', 'find_work', 'find_agents', 'get_updates', 'read_thread', 'get_issue_coordination', 'list_work_intents', 'get_decision', 'list_decisions']);
+const result = data => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
+
+// MCP hosts may share a server across conversations. Every tool carries an explicit binding
+// reference; neither a process nor a shared state file ever has a default active project.
+export async function serveReusable({ home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, browserFactory = createBrowserOperations, batchBrowserFactory = createBatchBrowserOperations, boundServer = serveSession, workerFactory, discoveryOptions, ownerFactory = createOwnerClient, ownerOptions, approvalWait = ms => new Promise(resolve => setTimeout(resolve, ms)), ...boundOptions }) {
+  const bundled = verifyBundle();
+  const projectTools = JSON.parse(bundled.files['project-tools.json'].toString('utf8')).tools.map(tool => ({
+    ...tool, description: `${tool.description ?? ''} Always supply this project agent’s connection_ref.`,
+    inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties, connection_ref: reference }, required: [...new Set([...(tool.inputSchema.required ?? []), 'connection_ref'])] },
+  }));
+  const localList = { name: 'list_project_agents', description: 'List only project-agent bindings in this MCP process and their observed local worker status. Does not enumerate your account or claim online presence. No model is started. Use the returned connection_ref to steer or stop a specific worker.', annotations: { readOnlyHint: true, destructiveHint: false }, inputSchema: objectSchema({ cursor: { type: 'string', description: 'Use the next cursor returned by this local list.' } }, []) };
+  const discovery = createDiscovery(discoveryOptions);
+  const owner = ownerFactory({ home, ...ownerOptions }), ownerReference = randomUUID();
+  let ownerConnected = false;
+  const catalog = [...OWNER_TOOLS, ...DISCOVERY_TOOLS, localList, ...BOOTSTRAP, ...BATCH_TOOLS, ...WORKER_TOOLS, ...projectTools], allowed = new Set(projectTools.map(tool => tool.name));
+  home = canonicalPath(home);
+  const browser = browserFactory({ home, io: { say() {} } });
+  const batchBrowser = batchBrowserFactory({ home, io: { say() {} } });
+  const bindings = new Map(), identities = new Map(), batches = new Map();
+  const approvalTasks = new Map();
+  let clientName = 'MCP client', stopped = false;
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  const stop = () => { stopped = true; lines.close(); for (const context of bindings.values()) void closeContext(context).catch(() => {}); };
+  input.once('end', stop);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.on(signal, stop);
+  const send = rpc => { if (!stopped) output.write(`${JSON.stringify(rpc)}\n`); };
+  const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+  const state = context => ({ state: context.stopped || context.stopping || context.closing ? 'stopped' : context.verified ? 'connected' : context.record ? 'bound' : context.observedState ?? 'pending', verified: !!context.verified && !context.stopped && !context.stopping && !context.closing, connection_ref: context.ref, connection_id: context.selected.id, agent_id: context.selected.agentId, agent_name: context.selected.agentName, project_url: context.selected.service, folder: context.selected.folder });
+  function validateRecord(record, context) {
+    validateSession(record, context.selected.id);
+    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`);
+    if (lstatExists(journal)) readPrivate(journal);
+    context.record = record; context.input = new PassThrough(); context.output = new PassThrough(); context.signals = new EventEmitter(); context.waiting = new Map();
+    context.lines = createInterface({ input: context.output });
+    context.lines.on('line', line => {
+      let reply;
+      try { reply = JSON.parse(line); } catch { void closeContext(context).catch(() => {}); return; }
+      const pending = context.waiting.get(reply.id);
+      if (pending) { context.waiting.delete(reply.id); pending.resolve(reply); }
+    });
+    // Each explicit binding retains the canonical bridge’s lazy run ownership, identity
+    // verification and journal. This launches no model or separate coding conversation.
+    context.task = boundServer({ ...boundOptions, connection: record.id, home, input: context.input, output: context.output, signals: context.signals,
+      onReady: async handles => { context.ready = handles; await boundOptions.onReady?.(handles); },
+      canRetry: () => {
+        if (boundOptions.canRetry && !boundOptions.canRetry()) return false;
+        if (!context.worker) return true;
+        const status = context.worker.status();
+        return status.active === true && ['working', 'running', 'waiting'].includes(status.state);
+      },
+      onStopping: async () => { context.stopping = true; await context.worker?.stop(); if (context.startTask) { await context.startTask.catch(() => {}); await context.worker?.stop(); } await boundOptions.onStopping?.(); },
+    });
+    context.task.catch(() => {}).finally(() => {
+      context.stopped = true;
+      for (const pending of context.waiting.values()) pending.reject(new Error('Bound connection stopped.'));
+      context.waiting.clear();
+    });
+    return { ...state(context), next_step: 'Call get_project with this connection_ref and verify your identity, then read the goals, rules, repository and state. Ask your human before starting work.' };
+  }
+  async function connect(args) {
+    if (Object.keys(args).some(key => !['project_url', 'agent_id', 'agent_name', 'folder', 'reconnect'].includes(key)) || !/^[\w-]{1,200}$/.test(args.agent_id ?? '') || !/^[\w-]{1,64}$/.test(args.agent_name ?? '') || (args.reconnect !== undefined && typeof args.reconnect !== 'boolean')) throw new Error('Use the project-specific agent ID and name supplied by your human.');
+    if (typeof args.project_url !== 'string' || typeof args.folder !== 'string' || !isAbsolute(args.folder)) throw new Error('Invalid project or folder.');
+    const folder = canonicalPath(args.folder);
+    assertStateOutsideWorkspace(home, folder);
+    for (const other of bindings.values()) {
+      if (workerOwnsMutations(other) && other.workerFolder) {
+        try { assertStateOutsideWorkspace(other.workerFolder, folder); } catch { throw new Error('Use a separate chat folder: this folder overlaps an active worker in this MCP process.'); }
+      }
+    }
+    const identity = projectIdentity({ projectUrl: args.project_url, folder });
+    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.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);
+      }
+    } else {
+      context = { ref: randomUUID(), selected, verified: false }; bindings.set(context.ref, context); identities.set(selected.id, context.ref);
+    }
+    const dir = connectionDir(home, selected.id);
+    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.' };
+  }
+  async function connectBatch(args) {
+    if (Object.keys(args).some(key => !['project_url','agents','reconnect'].includes(key)) || !Array.isArray(args.agents) || args.agents.length < 1 || args.agents.length > 10 || (args.reconnect !== undefined && typeof args.reconnect !== 'boolean')) throw new Error('Use one to ten explicitly selected agents for one project.');
+    const selected = args.agents.map(agent => {
+      if (!agent || Object.keys(agent).some(key => !['agent_id','agent_name','folder'].includes(key)) || !/^[\w-]{1,200}$/.test(agent.agent_id ?? '') || !/^[\w-]{1,64}$/.test(agent.agent_name ?? '') || typeof agent.folder !== 'string' || !isAbsolute(agent.folder)) throw new Error('Use each agent’s exact ID, name and approved absolute working folder.');
+      const folder = canonicalPath(agent.folder); assertStateOutsideWorkspace(home, folder);
+      const identity = projectIdentity({ projectUrl: args.project_url, folder });
+      for (const other of bindings.values()) {
+        if (workerOwnsMutations(other) && other.workerFolder) {
+          try { assertStateOutsideWorkspace(other.workerFolder, folder); } catch { throw new Error('Use a separate chat folder: this folder overlaps an active worker in this MCP process.'); }
+        }
+      }
+      return { id: sessionId(identity.projectUrl,agent.agent_id), service:identity.projectUrl, agentId:agent.agent_id, agentName:agent.agent_name, folder };
+    }).sort((a,b) => a.agentId.localeCompare(b.agentId));
+    if (new Set(selected.map(agent => agent.id)).size !== selected.length) throw new Error('Use distinct agent IDs in a batch.');
+    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;
+      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) => {
+      const context = contexts[index] ?? { ref:randomUUID(), selected:agent, verified:false };
+      bindings.set(context.ref,context); identities.set(agent.id,context.ref); return context;
+    }) }; batches.set(batch.ref,batch); }
+    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.');
+      for (const context of batch.contexts) validateRecord(response.records.find(record => record.id === context.selected.id),context);
+      for (const context of batch.contexts) if (!context.record) bind(response.records.find(record => record.id === context.selected.id),context);
+      return { state:'bound', batch_ref:batch.ref, agents:batch.contexts.map(state), next_step:'Verify each agent with get_project using its separate connection_ref. Work requires separate approval.' };
+    }
+    for (const context of batch.contexts) context.observedState = response.status;
+    return { state:response.status, batch_ref:batch.ref, approval_url:response.approvalUrl, request_check:response.requestCheck, agents:batch.contexts.map(state), next_step:'Approve this exact batch of your own agents in Karma42, wait for the result with finish_project_agents_connection, this batch_ref and wait_seconds:60; no typed done is required. Connection approval does not start work.' };
+  }
+  function queueApprovalWait(rpc, args, once) {
+    const key = `${once === finishBatch ? 'batch' : 'agent'}:${args.batch_ref ?? args.connection_ref}`;
+    if (approvalTasks.has(key)) throw new Error('Use the existing approval wait for this same reference; it is still running.');
+    if (approvalTasks.size >= 20) throw new Error('Approval wait limit reached. Finish or cancel a pending request first.');
+    // Waiting for a browser must not block steering or stopping another bound agent.
+    const task = waitForApproval(args, once).then(value => send({ jsonrpc:'2.0', id:rpc.id, result:result(value) }), error => {
+      const safe = /^(Use |Approval wait|This binding|This project agent|Browser setup|Another operation|Another browser)/.test(error.message ?? '');
+      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;
+    if (!Number.isInteger(wait_seconds) || wait_seconds < 0 || wait_seconds > 60) throw new Error('Approval wait must be between 0 and 60 seconds.');
+    let remaining = wait_seconds * 1000;
+    while (true) {
+      const response = await once(selection);
+      if (response.state !== 'pending' || remaining <= 0 || stopped) return response;
+      const delay = Math.min(5000, remaining);
+      await approvalWait(delay); remaining -= delay;
+      if (stopped) return response;
+    }
+  }
+  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);
+    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);
+  }
+  function contextFor(args) {
+    const context = bindings.get(args.connection_ref);
+    if (!context) throw new Error('Use an exact connection_ref returned by connect_project_agent in this MCP process. There is no default connection.');
+    return context;
+  }
+  async function finish(args) {
+    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.');
+    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.' };
+  }
+  async function closeContext(context) {
+    context.closing ??= (async () => {
+      // Stop the model process before aborting/releasing its shared coordination run.
+      try {
+        // A start may be validating its checkout or preparing the local bridge. Signal stop
+        // immediately, then await that setup and stop again before releasing coordination.
+        await context.worker?.stop();
+        if (context.startTask) { await context.startTask.catch(() => {}); await context.worker?.stop(); }
+      }
+      finally {
+        context.signals?.emit('SIGTERM'); context.input?.end();
+        if (context.task) await context.task.catch(() => {});
+        context.lines?.close(); context.output?.destroy();
+      }
+    })();
+    return context.closing;
+  }
+  function verifiedContext(args) {
+    const context = contextFor(args);
+    if (!context.verified || !context.ready) throw new Error('Call get_project with this connection_ref and verify identity before controlling a worker.');
+    if (context.stopped || context.stopping || context.closing) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+    return context;
+  }
+  function workerStatus(context) {
+    const current = context.worker?.status();
+    if (current && (current.state !== 'idle' || current.mission_ref)) return current;
+    const recovery = context.record ? workerRecoveryStatus(connectionDir(home, context.record.id), context.record) : null;
+    return recovery ? { state: 'recovery_required', active: false, recovery } : current ?? { state: 'not_started', active: false };
+  }
+  async function startWorker(args) {
+    if (Object.keys(args).some(key => !['connection_ref', 'client', 'model', 'minutes', 'scope', 'folder', 'approved', 'recovery_ref'].includes(key))) throw new Error('Use only the documented worker options.');
+    const context = verifiedContext(args), minutes = args.minutes === undefined ? 60 : args.minutes;
+    if (args.approved !== true) throw new Error('Worker start requires your human’s explicit approval for this worker, duration, folder and work scope. Connection approval is insufficient.');
+    if (!['claude', 'codex'].includes(args.client) || !Number.isInteger(minutes) || minutes < 15 || minutes > 240 || minutes % 15 !== 0) throw new Error('Choose a supported worker client and 15–240 minutes in 15-minute increments.');
+    if (typeof args.scope !== 'string' || !args.scope.trim() || args.scope.length > 4000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/.test(args.scope)) throw new Error('Use a clear, human-approved work scope of at most 4000 characters.');
+    if (typeof args.folder !== 'string' || !isAbsolute(args.folder)) throw new Error('Use the approved absolute worker checkout folder.');
+    const folder = canonicalPath(args.folder); assertStateOutsideWorkspace(home, folder);
+    for (const other of bindings.values()) {
+      if (other === context || other.stopped || other.closing) continue;
+      const candidates = [other.selected.folder, ...(workerOwnsMutations(other) && other.workerFolder ? [other.workerFolder] : [])];
+      for (const candidate of candidates) {
+        try { assertStateOutsideWorkspace(candidate, folder); } catch { throw new Error('Use separate sibling checkouts: this folder overlaps another project-agent binding or active worker in this MCP process.'); }
+      }
+    }
+    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 ?? 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, model: args.model, minutes: args.recovery_ref === undefined ? minutes : args.minutes, scope: args.scope.trim(), folder, approved: true, recovery_ref: args.recovery_ref }));
+      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.'); }
+      return { connection_ref: context.ref, worker: snapshot };
+    } catch (error) {
+      const safe = /^(Worker checkout|Worker ownership|Worker recovery|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.');
+    const context = verifiedContext(args);
+    if (!context.worker || (!context.starting && context.worker.status().state === 'idle' && !context.worker.status().mission_ref)) {
+      if (args.action === 'stop' && args.instruction === undefined) {
+        const cancelled = await cancelWorkerRecovery(connectionDir(home, context.record.id), context.record);
+        await context.worker?.stop();
+        return { connection_ref: context.ref, worker: cancelled };
+      }
+      throw new Error('This binding has no worker. Read get_project_worker for a saved mission and ask your human before starting or recovering one.');
+    }
+    if (args.action === 'steer') {
+      if (typeof args.instruction !== 'string' || !args.instruction.trim() || args.instruction.length > 2000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/.test(args.instruction)) throw new Error('Use a steering instruction of at most 2000 characters.');
+      const receipt = await context.worker.steer({ message: args.instruction.trim() });
+      return { connection_ref: context.ref, steering_request: receipt, worker: context.worker.status() };
+    }
+    if (args.instruction !== undefined) throw new Error('Use instruction only for a steer action.');
+    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);
+  }
+  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 (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: workerStatus(context) })), 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: workerStatus(context) }) });
+        }
+        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.'));
+    }
+  }
+  // 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([...requests.values(), ...[...bindings.values()].map(closeContext)]);
+    input.off('end', stop); for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.off(signal, stop);
+  }
+}