@microi.net/cli 5.9.1 → 5.9.3

package/scripts/microi-codex-broker.js

@@ -1,450 +1,466 @@
-#!/usr/bin/env node
-/*
- * Shared Microi Agentx MCP broker.
- *
- * Every Codex task still owns a tiny stdio router, but all routers for the same
- * workspace and tool version share this broker. The broker owns at most one
- * real MCP child per connection profile, uses an exclusive lease to survive
- * concurrent starts, and exits after the last router has been idle.
- */
-
-'use strict';
-
-const childProcess = require('node:child_process');
-const crypto = require('node:crypto');
-const fs = require('node:fs');
-const net = require('node:net');
-const os = require('node:os');
-const path = require('node:path');
-
-const PROTOCOL_VERSION = '2024-11-05';
-const endpoint = String(process.env.MICROI_CODEX_BROKER_ENDPOINT || '');
-const leasePath = path.resolve(String(process.env.MICROI_CODEX_BROKER_LEASE || ''));
-const workspaceRoot = path.resolve(String(process.env.MICROI_WORKSPACE_ROOT || process.cwd()));
-const mcpServerPath = path.resolve(String(process.env.MICROI_MCP_SERVER_PATH || path.join(__dirname, 'mcp-server.js')));
-const toolVersion = String(process.env.MICROI_TOOL_VERSION || '0.0.0');
-const idleMilliseconds = Math.max(250, Number(process.env.MICROI_CODEX_BROKER_IDLE_MS || 30000));
-const heartbeatMilliseconds = Math.max(500, Number(process.env.MICROI_CODEX_BROKER_HEARTBEAT_MS || 5000));
-const staleMilliseconds = Math.max(heartbeatMilliseconds * 3, Number(process.env.MICROI_CODEX_BROKER_STALE_MS || 20000));
-
-if (!endpoint || !process.env.MICROI_CODEX_BROKER_LEASE) {
-  process.stderr.write('[microi-codex-broker] Missing endpoint or lease path.\n');
-  process.exit(1);
-}
-
-const ownerToken = crypto.randomBytes(24).toString('hex');
-const children = new Map();
-const clients = new Set();
-let requestSequence = 0;
-let leaseOwned = false;
-let shuttingDown = false;
-let idleTimer = null;
-let heartbeatTimer = null;
-let server = null;
-
-function processExists(pid) {
-  if (!Number.isInteger(pid) || pid <= 1) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error?.code === 'EPERM';
-  }
-}
-
-function readLease() {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-
-function leaseRecord() {
-  return {
-    pid: process.pid,
-    token: ownerToken,
-    endpoint,
-    workspaceRoot,
-    toolVersion,
-    startedAt: startedAtIso,
-    heartbeatAt: new Date().toISOString(),
-  };
-}
-
-function writeLeaseRecord(record, exclusive = false) {
-  fs.mkdirSync(path.dirname(leasePath), { recursive: true });
-  const text = `${JSON.stringify(record, null, 2)}\n`;
-  if (exclusive) {
-    // Publish a complete lease atomically. Creating leasePath first and then
-    // writing its JSON leaves a short empty-file window; concurrent brokers can
-    // mistake that window for a stale lease, remove it, and leave connected
-    // routers without an authentication token. A same-directory hard link is
-    // both exclusive (EEXIST wins the race) and immediately complete.
-    const staged = `${leasePath}.${process.pid}.${Date.now()}.${ownerToken.slice(0, 8)}.new`;
-    try {
-      fs.writeFileSync(staged, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
-      fs.linkSync(staged, leasePath);
-    } finally {
-      try { if (fs.existsSync(staged)) fs.rmSync(staged, { force: true }); } catch { /* harmless */ }
-    }
-    return;
-  }
-  const current = readLease();
-  if (!current || current.token !== ownerToken) throw new Error('Microi Agentx broker lease ownership changed');
-  const staged = `${leasePath}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    fs.writeFileSync(staged, text, { encoding: 'utf8', mode: 0o600 });
-    fs.renameSync(staged, leasePath);
-  } finally {
-    try { if (fs.existsSync(staged)) fs.rmSync(staged, { force: true }); } catch { /* best effort */ }
-  }
-}
-
-function acquireLease() {
-  fs.mkdirSync(path.dirname(leasePath), { recursive: true });
-  for (let attempt = 0; attempt < 4; attempt += 1) {
-    try {
-      writeLeaseRecord(leaseRecord(), true);
-      leaseOwned = true;
-      return true;
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-      const existing = readLease();
-      const heartbeat = Date.parse(String(existing?.heartbeatAt || ''));
-      const fresh = Number.isFinite(heartbeat) && Date.now() - heartbeat < staleMilliseconds;
-      if (existing && processExists(Number(existing.pid)) && fresh) return false;
-      const stalePath = `${leasePath}.stale.${process.pid}.${Date.now()}`;
-      try {
-        fs.renameSync(leasePath, stalePath);
-        try { fs.rmSync(stalePath, { force: true }); } catch { /* harmless */ }
-      } catch (renameError) {
-        if (!['ENOENT', 'EACCES', 'EPERM'].includes(renameError?.code)) throw renameError;
-      }
-    }
-  }
-  return false;
-}
-
-function releaseLease() {
-  if (!leaseOwned) return;
-  const current = readLease();
-  if (current?.token === ownerToken) {
-    try { fs.rmSync(leasePath, { force: true }); } catch { /* next owner can reclaim stale lease */ }
-  }
-  leaseOwned = false;
-}
-
-function safeText(value) {
-  return String(value == null ? '' : value);
-}
-
-function profileIdentity(profile) {
-  return safeText(profile?.identity) || [
-    safeText(profile?.apiBaseUrl).replace(/\/+$/, ''),
-    safeText(profile?.osClient).trim(),
-    safeText(profile?.osClientType).trim(),
-    safeText(profile?.osClientNetwork).trim(),
-  ].join('|');
-}
-
-function workspaceSecretKey(baseKey, profileWorkspace) {
-  const normalized = path.resolve(profileWorkspace).toLowerCase();
-  const hash = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
-  return `${baseKey}.workspace.${hash}`;
-}
-
-function credentialSecretKey(baseKey, profile, profileWorkspace) {
-  const apiBaseUrl = safeText(profile.apiBaseUrl).trim().replace(/\/+$/, '');
-  const osClient = safeText(profile.osClient).trim();
-  return workspaceSecretKey(`${baseKey}.${apiBaseUrl}|${osClient}`, profileWorkspace);
-}
-
-function validateProfile(raw) {
-  const profile = raw && typeof raw === 'object' ? raw : {};
-  const profileWorkspace = path.resolve(safeText(profile.workspaceRoot || workspaceRoot));
-  if (process.platform === 'win32') {
-    if (profileWorkspace.toLowerCase() !== workspaceRoot.toLowerCase()) throw new Error('Broker workspace mismatch');
-  } else if (profileWorkspace !== workspaceRoot) {
-    throw new Error('Broker workspace mismatch');
-  }
-  if (!/^https?:\/\//i.test(safeText(profile.apiBaseUrl))) throw new Error('Invalid Microi API URL');
-  const syncRoot = path.resolve(safeText(profile.syncRoot || path.join(profileWorkspace, 'Microi-V8-Engine')));
-  return {
-    identity: profileIdentity(profile),
-    name: safeText(profile.name || profile.osClient || 'microi'),
-    label: safeText(profile.label),
-    apiBaseUrl: safeText(profile.apiBaseUrl).replace(/\/+$/, ''),
-    osClient: safeText(profile.osClient).trim(),
-    osClientType: safeText(profile.osClientType).trim(),
-    osClientNetwork: safeText(profile.osClientNetwork).trim(),
-    workspaceRoot: profileWorkspace,
-    syncRoot,
-    tokenPath: path.resolve(safeText(profile.tokenPath || path.join(profileWorkspace, 'Microi-V8-Engine', '.microi-mcp-tokens.json'))),
-    applicationsDir: path.resolve(safeText(profile.applicationsDir || path.join(profileWorkspace, 'Microi-V8-Engine'))),
-    workspaceCredentialFilePath: path.join(syncRoot, '.microi-workspace-secrets.dpapi.json'),
-    workspaceCredentialUsernameKey: credentialSecretKey('microi.username', profile, profileWorkspace),
-    workspaceCredentialPasswordKey: credentialSecretKey('microi.password', profile, profileWorkspace),
-  };
-}
-
-function deviceId() {
-  const raw = `MCP:${os.hostname() || 'Unknown'}`;
-  if (/^[\x20-\x7E]{1,128}$/.test(raw)) return raw;
-  return `MCP-${crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16)}`;
-}
-
-class ChildMcp {
-  constructor(profile) {
-    this.profile = profile;
-    this.pending = new Map();
-    this.buffer = '';
-    this.stopping = false;
-    this.ready = this.start();
-  }
-
-  async start() {
-    if (!fs.existsSync(mcpServerPath)) throw new Error(`Microi MCP bundle does not exist: ${mcpServerPath}`);
-    this.child = childProcess.spawn(process.execPath, [mcpServerPath], {
-      cwd: this.profile.workspaceRoot,
-      windowsHide: true,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: {
-        ...process.env,
-        MICROI_API_URL: this.profile.apiBaseUrl,
-        MICROI_TOKEN_FILE: this.profile.tokenPath,
-        MICROI_AUTH_RECOVERY_DIR: `${this.profile.tokenPath}.recovery`,
-        MICROI_WORKSPACE_CREDENTIAL_FILE: this.profile.workspaceCredentialFilePath,
-        MICROI_WORKSPACE_USERNAME_KEY: this.profile.workspaceCredentialUsernameKey,
-        MICROI_WORKSPACE_PASSWORD_KEY: this.profile.workspaceCredentialPasswordKey,
-        MICROI_OS_CLIENT: this.profile.osClient,
-        MICROI_OS_CLIENT_TYPE: this.profile.osClientType,
-        MICROI_OS_CLIENT_NETWORK: this.profile.osClientNetwork,
-        MICROI_WORKSPACE_ROOT: this.profile.workspaceRoot,
-        MICROI_SYNC_ROOT: this.profile.syncRoot,
-        MICROI_AI_APPLICATIONS_DIR: this.profile.applicationsDir,
-        MICROI_LABEL_BASE64: Buffer.from(this.profile.label, 'utf8').toString('base64'),
-        MICROI_MCP_DID: deviceId(),
-        MICROI_TOOL_SOURCE: 'codex-broker',
-        MICROI_TOOL_VERSION: toolVersion,
-        MICROI_CODEX_MODE: '1',
-      },
-    });
-    this.child.stdout.on('data', chunk => this.onData(chunk));
-    this.child.stderr.on('data', chunk => process.stderr.write(`[${this.profile.name}] ${chunk}`));
-    this.child.on('error', error => this.rejectAll(error));
-    this.child.on('exit', code => {
-      this.rejectAll(new Error(`Microi MCP ${this.profile.name} exited (${code ?? 'unknown'})`));
-      if (!this.stopping && children.get(this.profile.identity) === this) children.delete(this.profile.identity);
-    });
-    await this.request('initialize', {
-      protocolVersion: PROTOCOL_VERSION,
-      capabilities: {},
-      clientInfo: { name: 'microi-codex-shared-broker', version: toolVersion },
-    }, true);
-    this.notify('notifications/initialized', {});
-  }
-
-  onData(chunk) {
-    this.buffer += chunk.toString('utf8');
-    let newline;
-    while ((newline = this.buffer.indexOf('\n')) >= 0) {
-      const line = this.buffer.slice(0, newline).trim();
-      this.buffer = this.buffer.slice(newline + 1);
-      if (!line) continue;
-      let message;
-      try { message = JSON.parse(line); } catch { continue; }
-      if (message.id == null) continue;
-      const pending = this.pending.get(String(message.id));
-      if (!pending) continue;
-      this.pending.delete(String(message.id));
-      if (message.error) pending.reject(new Error(message.error.message || JSON.stringify(message.error)));
-      else pending.resolve(message.result);
-    }
-  }
-
-  rejectAll(error) {
-    for (const pending of this.pending.values()) pending.reject(error);
-    this.pending.clear();
-  }
-
-  write(message) {
-    if (!this.child || this.child.stdin.destroyed) throw new Error(`Microi MCP ${this.profile.name} is unavailable`);
-    this.child.stdin.write(`${JSON.stringify(message)}\n`);
-  }
-
-  request(method, params, skipReady = false) {
-    return (async () => {
-      if (!skipReady) await this.ready;
-      const id = `broker-${process.pid}-${++requestSequence}`;
-      const response = new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
-      this.write({ jsonrpc: '2.0', id, method, params });
-      return response;
-    })();
-  }
-
-  notify(method, params) {
-    this.write({ jsonrpc: '2.0', method, params });
-  }
-
-  stop() {
-    this.stopping = true;
-    try { this.child?.stdin.end(); } catch { /* best effort */ }
-    try { this.child?.kill('SIGTERM'); } catch { /* best effort */ }
-    const child = this.child;
-    const forceTimer = setTimeout(() => {
-      if (child && child.exitCode === null) {
-        try { child.kill('SIGKILL'); } catch { /* best effort */ }
-      }
-    }, 2000);
-    forceTimer.unref();
-  }
-}
-
-function childFor(rawProfile) {
-  const profile = validateProfile(rawProfile);
-  const existing = children.get(profile.identity);
-  if (existing) return existing;
-  const child = new ChildMcp(profile);
-  children.set(profile.identity, child);
-  return child;
-}
-
-function send(socket, message) {
-  if (!socket.destroyed) socket.write(`${JSON.stringify(message)}\n`);
-}
-
-async function handleMessage(socket, message) {
-  const id = message?.id;
-  if (id == null) return;
-  if (message.auth !== ownerToken) {
-    send(socket, { id, error: 'Unauthorized local broker client' });
-    return;
-  }
-  try {
-    if (message.type === 'status') {
-      send(socket, {
-        id,
-        result: {
-          pid: process.pid,
-          workspaceRoot,
-          toolVersion,
-          clients: clients.size,
-          childCount: children.size,
-          childPids: [...children.values()].map(item => item.child?.pid).filter(Boolean),
-        },
-      });
-      return;
-    }
-    if (message.type !== 'request') throw new Error('Unsupported broker request');
-    const result = await childFor(message.profile).request(safeText(message.method), message.params || {});
-    send(socket, { id, result });
-  } catch (error) {
-    send(socket, { id, error: error instanceof Error ? error.message : String(error) });
-  }
-}
-
-function cancelIdleShutdown() {
-  if (idleTimer) clearTimeout(idleTimer);
-  idleTimer = null;
-}
-
-function scheduleIdleShutdown() {
-  cancelIdleShutdown();
-  if (clients.size > 0 || shuttingDown) return;
-  idleTimer = setTimeout(() => shutdown(0), idleMilliseconds);
-}
-
-function acceptClient(socket) {
-  cancelIdleShutdown();
-  clients.add(socket);
-  socket.setEncoding('utf8');
-  let buffer = '';
-  socket.on('data', chunk => {
-    buffer += chunk;
-    let newline;
-    while ((newline = buffer.indexOf('\n')) >= 0) {
-      const line = buffer.slice(0, newline).trim();
-      buffer = buffer.slice(newline + 1);
-      if (!line) continue;
-      let message;
-      try { message = JSON.parse(line); }
-      catch { send(socket, { id: null, error: 'Invalid broker JSON' }); continue; }
-      Promise.resolve(handleMessage(socket, message)).catch(() => { /* handled above */ });
-    }
-  });
-  const close = () => {
-    clients.delete(socket);
-    scheduleIdleShutdown();
-  };
-  socket.once('close', close);
-  socket.once('error', close);
-}
-
-function removeUnixSocket() {
-  if (process.platform === 'win32') return;
-  try { if (fs.existsSync(endpoint)) fs.rmSync(endpoint, { force: true }); } catch { /* stale socket is reclaimable */ }
-}
-
-function shutdown(exitCode = 0) {
-  if (shuttingDown) return;
-  shuttingDown = true;
-  cancelIdleShutdown();
-  if (heartbeatTimer) clearInterval(heartbeatTimer);
-  for (const socket of clients) {
-    try { socket.end(); } catch { /* best effort */ }
-  }
-  clients.clear();
-  for (const child of children.values()) child.stop();
-  children.clear();
-  const finish = () => {
-    releaseLease();
-    removeUnixSocket();
-    process.exit(exitCode);
-  };
-  if (server) {
-    try { server.close(finish); } catch { finish(); }
-    const forceTimer = setTimeout(finish, 2200);
-    forceTimer.unref();
-  } else {
-    finish();
-  }
-}
-
-const startedAtIso = new Date().toISOString();
-// Windows 命名管道无需目录；macOS/Linux 首次连接必须先创建 Unix socket 的父目录。
-// 在领取租约前完成，目录不可写时不会留下貌似存活的 Broker 租约。
-if (process.platform !== 'win32') fs.mkdirSync(path.dirname(endpoint), { recursive: true, mode: 0o700 });
-if (!acquireLease()) process.exit(0);
-
-removeUnixSocket();
-server = net.createServer(acceptClient);
-server.on('error', error => {
-  process.stderr.write(`[microi-codex-broker] ${error.message}\n`);
-  shutdown(1);
-});
-server.listen(endpoint, () => {
-  if (process.platform !== 'win32') {
-    try { fs.chmodSync(endpoint, 0o600); } catch { /* best effort */ }
-  }
-  heartbeatTimer = setInterval(() => {
-    try { writeLeaseRecord(leaseRecord()); } catch { shutdown(1); }
-  }, heartbeatMilliseconds);
-  scheduleIdleShutdown();
-});
-
-for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => shutdown(0));
-process.on('uncaughtException', error => {
-  process.stderr.write(`[microi-codex-broker] ${error?.stack || error}\n`);
-  shutdown(1);
-});
-process.on('exit', () => {
-  for (const child of children.values()) {
-    try { if (child.child?.exitCode === null) child.child.kill('SIGKILL'); } catch { /* best effort */ }
-  }
-  if (leaseOwned) {
-    releaseLease();
-    removeUnixSocket();
-  }
-});
+#!/usr/bin/env node
+/*
+ * Shared Microi Agentx MCP broker.
+ *
+ * Every Codex task still owns a tiny stdio router, but all routers for the same
+ * workspace and tool version share this broker. The broker owns at most one
+ * real MCP child per connection profile, uses an exclusive lease to survive
+ * concurrent starts, and exits after the last router has been idle.
+ */
+
+'use strict';
+
+const childProcess = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+
+const PROTOCOL_VERSION = '2024-11-05';
+const endpoint = String(process.env.MICROI_CODEX_BROKER_ENDPOINT || '');
+const leasePath = path.resolve(String(process.env.MICROI_CODEX_BROKER_LEASE || ''));
+const workspaceRoot = path.resolve(String(process.env.MICROI_WORKSPACE_ROOT || process.cwd()));
+const mcpServerPath = path.resolve(String(process.env.MICROI_MCP_SERVER_PATH || path.join(__dirname, 'mcp-server.js')));
+const toolVersion = String(process.env.MICROI_TOOL_VERSION || '0.0.0');
+const idleMilliseconds = Math.max(250, Number(process.env.MICROI_CODEX_BROKER_IDLE_MS || 30000));
+// The launching router may not get scheduled again immediately on a busy host.
+// Do not retire the listening pipe before its first client has had time to join.
+const initialClientGraceMilliseconds = Math.max(10000, idleMilliseconds);
+const heartbeatMilliseconds = Math.max(500, Number(process.env.MICROI_CODEX_BROKER_HEARTBEAT_MS || 5000));
+const staleMilliseconds = Math.max(heartbeatMilliseconds * 3, Number(process.env.MICROI_CODEX_BROKER_STALE_MS || 20000));
+function testDiagnostic(message) {
+  if (process.env.MICROI_CODEX_TEST_DIAGNOSTICS !== '1' || !process.env.MICROI_CODEX_TEST_LOG) return;
+  try { if (!fs.existsSync(process.env.MICROI_CODEX_TEST_LOG) || fs.statSync(process.env.MICROI_CODEX_TEST_LOG).size < 65536) fs.appendFileSync(process.env.MICROI_CODEX_TEST_LOG, `${new Date().toISOString()} ${String(message).slice(0,8192)}\n`); } catch { /* tests report missing evidence */ }
+}
+testDiagnostic(`broker start ${process.version}`);
+
+if (!endpoint || !process.env.MICROI_CODEX_BROKER_LEASE) {
+  process.stderr.write('[microi-codex-broker] Missing endpoint or lease path.\n');
+  process.exit(1);
+}
+
+const ownerToken = crypto.randomBytes(24).toString('hex');
+const children = new Map();
+const clients = new Set();
+let requestSequence = 0;
+let leaseOwned = false;
+let shuttingDown = false;
+let idleTimer = null;
+let heartbeatTimer = null;
+let server = null;
+
+function processExists(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readLease() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function leaseRecord() {
+  return {
+    pid: process.pid,
+    token: ownerToken,
+    endpoint,
+    workspaceRoot,
+    toolVersion,
+    startedAt: startedAtIso,
+    heartbeatAt: new Date().toISOString(),
+  };
+}
+
+function writeLeaseRecord(record, exclusive = false) {
+  fs.mkdirSync(path.dirname(leasePath), { recursive: true });
+  const text = `${JSON.stringify(record, null, 2)}\n`;
+  if (exclusive) {
+    // Publish a complete lease atomically. Creating leasePath first and then
+    // writing its JSON leaves a short empty-file window; concurrent brokers can
+    // mistake that window for a stale lease, remove it, and leave connected
+    // routers without an authentication token. A same-directory hard link is
+    // both exclusive (EEXIST wins the race) and immediately complete.
+    const staged = `${leasePath}.${process.pid}.${Date.now()}.${ownerToken.slice(0, 8)}.new`;
+    try {
+      fs.writeFileSync(staged, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      fs.linkSync(staged, leasePath);
+    } finally {
+      try { if (fs.existsSync(staged)) fs.rmSync(staged, { force: true }); } catch { /* harmless */ }
+    }
+    return;
+  }
+  const current = readLease();
+  if (!current || current.token !== ownerToken) throw new Error('Microi Agentx broker lease ownership changed');
+  const staged = `${leasePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(staged, text, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(staged, leasePath);
+  } finally {
+    try { if (fs.existsSync(staged)) fs.rmSync(staged, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+function acquireLease() {
+  fs.mkdirSync(path.dirname(leasePath), { recursive: true });
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    try {
+      writeLeaseRecord(leaseRecord(), true);
+      leaseOwned = true;
+      return true;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const existing = readLease();
+      const heartbeat = Date.parse(String(existing?.heartbeatAt || ''));
+      const fresh = Number.isFinite(heartbeat) && Date.now() - heartbeat < staleMilliseconds;
+      if (existing && processExists(Number(existing.pid)) && fresh) return false;
+      const stalePath = `${leasePath}.stale.${process.pid}.${Date.now()}`;
+      try {
+        fs.renameSync(leasePath, stalePath);
+        try { fs.rmSync(stalePath, { force: true }); } catch { /* harmless */ }
+      } catch (renameError) {
+        if (!['ENOENT', 'EACCES', 'EPERM'].includes(renameError?.code)) throw renameError;
+      }
+    }
+  }
+  return false;
+}
+
+function releaseLease() {
+  if (!leaseOwned) return;
+  const current = readLease();
+  if (current?.token === ownerToken) {
+    try { fs.rmSync(leasePath, { force: true }); } catch { /* next owner can reclaim stale lease */ }
+  }
+  leaseOwned = false;
+}
+
+function safeText(value) {
+  return String(value == null ? '' : value);
+}
+
+function profileIdentity(profile) {
+  return safeText(profile?.identity) || [
+    safeText(profile?.apiBaseUrl).replace(/\/+$/, ''),
+    safeText(profile?.osClient).trim(),
+    safeText(profile?.osClientType).trim(),
+    safeText(profile?.osClientNetwork).trim(),
+  ].join('|');
+}
+
+function workspaceSecretKey(baseKey, profileWorkspace) {
+  const normalized = path.resolve(profileWorkspace).toLowerCase();
+  const hash = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+  return `${baseKey}.workspace.${hash}`;
+}
+
+function credentialSecretKey(baseKey, profile, profileWorkspace) {
+  const apiBaseUrl = safeText(profile.apiBaseUrl).trim().replace(/\/+$/, '');
+  const osClient = safeText(profile.osClient).trim();
+  return workspaceSecretKey(`${baseKey}.${apiBaseUrl}|${osClient}`, profileWorkspace);
+}
+
+function validateProfile(raw) {
+  const profile = raw && typeof raw === 'object' ? raw : {};
+  const profileWorkspace = path.resolve(safeText(profile.workspaceRoot || workspaceRoot));
+  if (process.platform === 'win32') {
+    if (profileWorkspace.toLowerCase() !== workspaceRoot.toLowerCase()) throw new Error('Broker workspace mismatch');
+  } else if (profileWorkspace !== workspaceRoot) {
+    throw new Error('Broker workspace mismatch');
+  }
+  if (!/^https?:\/\//i.test(safeText(profile.apiBaseUrl))) throw new Error('Invalid Microi API URL');
+  const syncRoot = path.resolve(safeText(profile.syncRoot || path.join(profileWorkspace, 'Microi-V8-Engine')));
+  return {
+    identity: profileIdentity(profile),
+    name: safeText(profile.name || profile.osClient || 'microi'),
+    label: safeText(profile.label),
+    apiBaseUrl: safeText(profile.apiBaseUrl).replace(/\/+$/, ''),
+    osClient: safeText(profile.osClient).trim(),
+    osClientType: safeText(profile.osClientType).trim(),
+    osClientNetwork: safeText(profile.osClientNetwork).trim(),
+    workspaceRoot: profileWorkspace,
+    syncRoot,
+    tokenPath: path.resolve(safeText(profile.tokenPath || path.join(profileWorkspace, 'Microi-V8-Engine', '.microi-mcp-tokens.json'))),
+    applicationsDir: path.resolve(safeText(profile.applicationsDir || path.join(profileWorkspace, 'Microi-V8-Engine'))),
+    workspaceCredentialFilePath: path.join(syncRoot, '.microi-workspace-secrets.dpapi.json'),
+    workspaceCredentialUsernameKey: credentialSecretKey('microi.username', profile, profileWorkspace),
+    workspaceCredentialPasswordKey: credentialSecretKey('microi.password', profile, profileWorkspace),
+  };
+}
+
+function deviceId() {
+  const raw = `MCP:${os.hostname() || 'Unknown'}`;
+  if (/^[\x20-\x7E]{1,128}$/.test(raw)) return raw;
+  return `MCP-${crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16)}`;
+}
+
+class ChildMcp {
+  constructor(profile) {
+    this.profile = profile;
+    this.pending = new Map();
+    this.buffer = '';
+    this.stopping = false;
+    this.ready = this.start();
+  }
+
+  async start() {
+    if (!fs.existsSync(mcpServerPath)) throw new Error(`Microi MCP bundle does not exist: ${mcpServerPath}`);
+    this.child = childProcess.spawn(process.execPath, [mcpServerPath], {
+      cwd: this.profile.workspaceRoot,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        MICROI_API_URL: this.profile.apiBaseUrl,
+        MICROI_TOKEN_FILE: this.profile.tokenPath,
+        MICROI_AUTH_RECOVERY_DIR: `${this.profile.tokenPath}.recovery`,
+        MICROI_WORKSPACE_CREDENTIAL_FILE: this.profile.workspaceCredentialFilePath,
+        MICROI_WORKSPACE_USERNAME_KEY: this.profile.workspaceCredentialUsernameKey,
+        MICROI_WORKSPACE_PASSWORD_KEY: this.profile.workspaceCredentialPasswordKey,
+        MICROI_OS_CLIENT: this.profile.osClient,
+        MICROI_OS_CLIENT_TYPE: this.profile.osClientType,
+        MICROI_OS_CLIENT_NETWORK: this.profile.osClientNetwork,
+        MICROI_WORKSPACE_ROOT: this.profile.workspaceRoot,
+        MICROI_SYNC_ROOT: this.profile.syncRoot,
+        MICROI_AI_APPLICATIONS_DIR: this.profile.applicationsDir,
+        MICROI_LABEL_BASE64: Buffer.from(this.profile.label, 'utf8').toString('base64'),
+        MICROI_MCP_DID: deviceId(),
+        MICROI_TOOL_SOURCE: 'codex-broker',
+        MICROI_TOOL_VERSION: toolVersion,
+        MICROI_CODEX_MODE: '1',
+      },
+    });
+    this.child.stdout.on('data', chunk => this.onData(chunk));
+    this.child.stdin.on('error', error => this.rejectAll(error));
+    this.child.stderr.on('data', chunk => { testDiagnostic(`MCP stderr ${chunk}`); process.stderr.write(`[${this.profile.name}] ${chunk}`); });
+    this.child.on('error', error => this.rejectAll(error));
+    this.child.on('exit', code => {
+      testDiagnostic(`MCP child exit ${code}`);
+      this.rejectAll(new Error(`Microi MCP ${this.profile.name} exited (${code ?? 'unknown'})`));
+      if (!this.stopping && children.get(this.profile.identity) === this) children.delete(this.profile.identity);
+    });
+    await this.request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'microi-codex-shared-broker', version: toolVersion },
+    }, true);
+    this.notify('notifications/initialized', {});
+  }
+
+  onData(chunk) {
+    this.buffer += chunk.toString('utf8');
+    let newline;
+    while ((newline = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, newline).trim();
+      this.buffer = this.buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      if (message.id == null) continue;
+      const pending = this.pending.get(String(message.id));
+      if (!pending) continue;
+      this.pending.delete(String(message.id));
+      if (message.error) pending.reject(new Error(message.error.message || JSON.stringify(message.error)));
+      else pending.resolve(message.result);
+    }
+  }
+
+  rejectAll(error) {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+
+  write(message) {
+    if (!this.child || this.child.stdin.destroyed) throw new Error(`Microi MCP ${this.profile.name} is unavailable`);
+    this.child.stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  request(method, params, skipReady = false) {
+    return (async () => {
+      if (!skipReady) await this.ready;
+      const id = `broker-${process.pid}-${++requestSequence}`;
+      const response = new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
+      this.write({ jsonrpc: '2.0', id, method, params });
+      return response;
+    })();
+  }
+
+  notify(method, params) {
+    this.write({ jsonrpc: '2.0', method, params });
+  }
+
+  stop() {
+    this.stopping = true;
+    try { this.child?.stdin.end(); } catch { /* best effort */ }
+    try { this.child?.kill('SIGTERM'); } catch { /* best effort */ }
+    const child = this.child;
+    const forceTimer = setTimeout(() => {
+      if (child && child.exitCode === null) {
+        try { child.kill('SIGKILL'); } catch { /* best effort */ }
+      }
+    }, 2000);
+    forceTimer.unref();
+  }
+}
+
+function childFor(rawProfile) {
+  const profile = validateProfile(rawProfile);
+  const existing = children.get(profile.identity);
+  if (existing) return existing;
+  const child = new ChildMcp(profile);
+  children.set(profile.identity, child);
+  return child;
+}
+
+function send(socket, message) {
+  if (!socket.destroyed) socket.write(`${JSON.stringify(message)}\n`);
+}
+
+async function handleMessage(socket, message) {
+  const id = message?.id;
+  if (id == null) return;
+  if (message.auth !== ownerToken) {
+    send(socket, { id, error: 'Unauthorized local broker client' });
+    return;
+  }
+  try {
+    if (message.type === 'status') {
+      send(socket, {
+        id,
+        result: {
+          pid: process.pid,
+          workspaceRoot,
+          toolVersion,
+          clients: clients.size,
+          childCount: children.size,
+          childPids: [...children.values()].map(item => item.child?.pid).filter(Boolean),
+        },
+      });
+      return;
+    }
+    if (message.type !== 'request') throw new Error('Unsupported broker request');
+    const result = await childFor(message.profile).request(safeText(message.method), message.params || {});
+    send(socket, { id, result });
+  } catch (error) {
+    send(socket, { id, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+function cancelIdleShutdown() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = null;
+}
+
+function scheduleIdleShutdown(initial = false) {
+  cancelIdleShutdown();
+  if (clients.size > 0 || shuttingDown) return;
+  idleTimer = setTimeout(() => shutdown(0), initial ? initialClientGraceMilliseconds : idleMilliseconds);
+}
+
+function acceptClient(socket) {
+  testDiagnostic('client connected');
+  cancelIdleShutdown();
+  clients.add(socket);
+  socket.setEncoding('utf8');
+  let buffer = '';
+  socket.on('data', chunk => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); }
+      catch { send(socket, { id: null, error: 'Invalid broker JSON' }); continue; }
+      Promise.resolve(handleMessage(socket, message)).catch(() => { /* handled above */ });
+    }
+  });
+  const close = () => {
+    testDiagnostic('client disconnected');
+    clients.delete(socket);
+    scheduleIdleShutdown();
+  };
+  socket.once('close', close);
+  socket.once('error', close);
+}
+
+function removeUnixSocket() {
+  if (process.platform === 'win32') return;
+  try { if (fs.existsSync(endpoint)) fs.rmSync(endpoint, { force: true }); } catch { /* stale socket is reclaimable */ }
+}
+
+function shutdown(exitCode = 0) {
+  testDiagnostic(`shutdown ${exitCode}`);
+  if (shuttingDown) return;
+  shuttingDown = true;
+  cancelIdleShutdown();
+  if (heartbeatTimer) clearInterval(heartbeatTimer);
+  for (const socket of clients) {
+    try { socket.end(); } catch { /* best effort */ }
+  }
+  clients.clear();
+  for (const child of children.values()) child.stop();
+  children.clear();
+  const finish = () => {
+    releaseLease();
+    removeUnixSocket();
+    process.exit(exitCode);
+  };
+  if (server) {
+    try { server.close(finish); } catch { finish(); }
+    const forceTimer = setTimeout(finish, 2200);
+    forceTimer.unref();
+  } else {
+    finish();
+  }
+}
+
+const startedAtIso = new Date().toISOString();
+// Windows 命名管道无需目录；macOS/Linux 首次连接必须先创建 Unix socket 的父目录。
+// 在领取租约前完成，目录不可写时不会留下貌似存活的 Broker 租约。
+if (process.platform !== 'win32') fs.mkdirSync(path.dirname(endpoint), { recursive: true, mode: 0o700 });
+if (!acquireLease()) process.exit(0);
+
+removeUnixSocket();
+server = net.createServer(acceptClient);
+server.on('error', error => {
+  testDiagnostic(`server error ${error.message}`);
+  process.stderr.write(`[microi-codex-broker] ${error.message}\n`);
+  shutdown(1);
+});
+server.listen(endpoint, () => {
+  testDiagnostic(`server listening ${JSON.stringify(endpoint)}`);
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(endpoint, 0o600); } catch { /* best effort */ }
+  }
+  heartbeatTimer = setInterval(() => {
+    try { writeLeaseRecord(leaseRecord()); } catch (error) { testDiagnostic(`heartbeat failed ${error.message}`); shutdown(1); }
+  }, heartbeatMilliseconds);
+  scheduleIdleShutdown(true);
+});
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => shutdown(0));
+process.on('uncaughtException', error => {
+  testDiagnostic(`uncaught ${error?.stack || error}`);
+  process.stderr.write(`[microi-codex-broker] ${error?.stack || error}\n`);
+  shutdown(1);
+});
+process.on('exit', () => {
+  for (const child of children.values()) {
+    try { if (child.child?.exitCode === null) child.child.kill('SIGKILL'); } catch { /* best effort */ }
+  }
+  if (leaseOwned) {
+    releaseLease();
+    removeUnixSocket();
+  }
+});