@walkhi/code-relax 0.1.0-beta.30 → 0.1.0-beta.31

package/dist/src/self-relay/lifecycle.mjs

@@ -1,250 +1,264 @@
-import path from 'node:path';
-import serviceEndpoints from '../../shared/service-endpoints.cjs';
-import { randomBytes, randomUUID } from 'node:crypto';
-import { hostname } from 'node:os';
-import QRCode from 'qrcode';
-import { credentialStore } from '../platform/credential-store.mjs';
-import { readRecord, writeRecord } from '../service-lifecycle.mjs';
-import { serviceHealth } from '../service-health.mjs';
-import { controlRequest } from '../service-control.mjs';
-import { connectBridgeRelay } from './connector.mjs';
-import { validProbeIceServers } from './p2p-probe.mjs';
-import { relayAddress, validSecret } from './wire.mjs';
-import { saveLanAuthorizations } from './lan-authorizations.mjs';
-import { lanNetworks } from '../platform/network-info.mjs';
-
-const officialConfig = { url: serviceEndpoints.relayUrl };
-
-async function loadConfig(stateRoot) {
-  const configPath = path.join(stateRoot, 'self-relay-config.json');
-  const stored = readRecord(configPath) || {};
-  const config = { ...officialConfig, ...stored };
-  if (!stored.url) writeRecord(configPath, config);
-  if (config.p2pIceServers !== undefined && !validProbeIceServers(config.p2pIceServers)) throw new Error('p2pIceServers 只接受最多 4 个 stun:主机:端口地址');
-  if (config.p2pWindowsRouteHelper !== undefined && typeof config.p2pWindowsRouteHelper !== 'boolean') throw new Error('p2pWindowsRouteHelper 必须是布尔值');
-  if (config.p2pWindowsRouteHelper && !/^[A-Za-z0-9_-]{32,128}$/.test(config.p2pWindowsRouteHelperToken || '')) throw new Error('p2pWindowsRouteHelperToken 无效');
-  const url = process.env.RELAY_URL || serviceEndpoints.resolveRelayUrl(config.url);
-  if (!url) throw new Error('请先配置 self-relay-config.json 的 url，详见自建中继文档。');
-  relayAddress(url);
-  const resolved = relayAddress(url);
-  const pairingUrl = config.pairingUrl || (resolved === serviceEndpoints.relayUrl ? serviceEndpoints.pairingUrl : `${resolved.startsWith('wss:') ? 'https:' : 'http:'}//${new URL(resolved).host}/pair`);
-  const pairing = new URL(pairingUrl);
-  if (!['https:', 'http:'].includes(pairing.protocol) || pairing.pathname !== '/pair' || pairing.search || pairing.hash || pairing.username || pairing.password ||
-      (pairing.protocol === 'http:' && pairing.hostname !== '127.0.0.1')) throw new Error('self-relay-config.json 的 pairingUrl 必须是 HTTPS /pair 地址。');
-  return { ...config, url: resolved, pairingUrl: pairing.href };
-}
-export async function selfRelay(command, stateRoot, details) {
-  const session = readRecord(path.join(stateRoot, 'bridge-session.json'));
-  if (!session) {
-    if (command === 'relay-status') return { running: false, displayText: '桌面服务未运行。' };
-    if (command === 'relay-stop') return { stopped: true, displayText: '中继连接已停止。' };
-    throw new Error('桌面服务尚未运行，请先执行 relax start。');
-  }
-  return controlRequest(session, 'POST', command, details);
-}
-
-async function createRelayRuntime(stateRoot) {
-  const config = await loadConfig(stateRoot);
-  const configPath = path.join(stateRoot, 'self-relay-config.json');
-  const session = () => readRecord(path.join(stateRoot, 'bridge-session.json'));
-  let health = await serviceHealth(session());
-  if (health?.status !== 'ok') throw new Error('桌面服务尚未运行，请先执行 relax start --json。');
-  const stored = await credentialStore('load');
-  const identities = stored.record || { version: 2, devices: {} };
-  const validIdentity = (id, item) => /^[\w-]{16,128}$/.test(id) && item?.id === id &&
-    validSecret(item.secret) && typeof item.registered === 'boolean';
-  if (identities.version !== 2 || !identities.devices || typeof identities.devices !== 'object' || Array.isArray(identities.devices) ||
-      Object.entries(identities.devices).some(([id, item]) => !validIdentity(id, item))) throw new Error('本机设备身份损坏，未自动覆盖');
-  if (!config.deviceId) {
-    const known = Object.values(identities.devices);
-    if (known.length > 1) throw new Error('存在多个工作站身份，请在 self-relay-config.json 中指定 deviceId。');
-    config.deviceId = known[0]?.id || randomUUID();
-  }
-  const createIdentity = config.deviceId === 'new';
-  if (createIdentity) config.deviceId = randomUUID();
-  if (!/^[\w-]{16,128}$/.test(config.deviceId)) throw new Error('self-relay-config.json 的 deviceId 无效。');
-  let identity = identities.devices[config.deviceId];
-  if (!identity) {
-    if (!createIdentity && Object.keys(identities.devices).length) throw new Error('找不到配置指定的工作站身份，未自动创建新身份。');
-    identity = { id: config.deviceId, secret: randomBytes(32).toString('base64url'), registered: false };
-    identities.devices[identity.id] = identity;
-    await credentialStore('save', identities);
-  }
-  const persistedConfig = readRecord(configPath) || {};
-  if (persistedConfig.deviceId !== identity.id) writeRecord(configPath, { ...persistedConfig, deviceId: identity.id });
-  let bridgeError = '';
-  async function refreshHealth() {
-    try { health = await serviceHealth(session()) || { transportMode: health.transportMode, status: 'offline' }; bridgeError = ''; }
-    catch (error) { bridgeError = error.message; health = { transportMode: health.transportMode, status: 'offline' }; }
-  }
-  let connector, qrPath, expiresAt = 0, paired = false, clientCount = 0, attachedCount = 0;
-  let closing = false, online = false, connecting = false, retryTimer, attempts = 0, lastError = '';
-  const audit = (event, details = {}) => console.log(JSON.stringify({ time: new Date().toISOString(), event, ...details }));
-  async function currentLanCandidates() {
-    try {
-      const bridge = session(), port = bridge?.port || 45831;
-      return (await lanNetworks()).map(network => ({ ...network, address: `http://${network.address}:${port}` }));
-    } catch (error) {
-      audit('lan-candidates-unavailable', { message: error.message }); return [];
-    }
-  }
-  const status = () => {
-    const available = online && !paired && qrPath && Date.now() < expiresAt;
-    const next = !online ? (lastError || '电脑连接器正在恢复中继连接，已保存授权。')
-      : paired ? '设备已授权，移动端可直接重连；网络断开不需要重新扫码。'
-        : available ? '用要添加的移动设备在有效期内扫描统一配对二维码。连接器在后台运行。'
-          : '尚未完成设备授权；调用 relax pair --json 生成配对二维码。';
-    return { running: !closing, relayConnected: online, mode: 'self-relay', transportMode: health.transportMode,
-      relayUrl: config.url, deviceId: identity.id, paired, clientCount, authorization: online ? (paired ? 'authorized' : 'unpaired') : 'unverified', phoneConnected: attachedCount > 0,
-      bridgeReady: health.status === 'ok' && health.execution?.ready === true && health.sharedAppServerConnected === true, bridgeError,
-      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null,
-      ...(available ? { qrPath } : {}), mobileAccess: 'unverified', lastError,
-      displayText: `Code Relax 中继 · ${health.transportMode === 'lan-shared' ? 'Codex 内核已就绪' : 'Codex 内核未就绪'}\n${next}` };
-  };
-  async function shutdown() {
-    if (closing) return;
-    closing = true; online = false; attachedCount = 0; clearTimeout(retryTimer);
-    connector?.events.removeAllListeners(); connector?.close();
-  }
-  async function saveInvitation(message) {
-    if (!message.code) return;
-    expiresAt = message.expires;
-    const link = new URL(config.pairingUrl);
-    link.searchParams.set('invite', message.code);
-    // Keep previously displayed files intact even when their invitation expires.
-    qrPath = path.join(stateRoot, `self-relay-qr-${randomUUID()}.png`);
-    await QRCode.toFile(qrPath, link.href, { width: 640, margin: 3 });
-  }
-  function scheduleRetry() {
-    if (closing || retryTimer) return;
-    const delay = Math.min(1000 * 2 ** Math.min(attempts++, 5), 30000) * (0.8 + Math.random() * 0.2);
-    retryTimer = setTimeout(() => { retryTimer = undefined; void connect(); }, delay);
-  }
-  async function connect() {
-    if (closing || connecting) return;
-    connecting = true;
-    let retryAfterAttempt = false;
-    try {
-      const bridge = session();
-      await refreshHealth();
-      if (closing) return;
-      const lanCandidates = await currentLanCandidates();
-      if (closing) return;
-      connector?.events.removeAllListeners(); connector?.close();
-      const current = connector = connectBridgeRelay({ relayUrl: config.url, identity,
-        usageCacheFile: path.join(stateRoot, 'relay-usage-tasks.json'),
-        bridgeUrl: `ws://127.0.0.1:${bridge?.port || 45831}/api/socket`, bridgeToken: bridge?.accessUrl ? new URL(bridge.accessUrl).searchParams.get('token') : 'unavailable',
-        bridgeConnection: () => { const latest = session(); return { url: `ws://127.0.0.1:${latest.port}/api/socket`, token: new URL(latest.accessUrl).searchParams.get('token') }; },
-        hostName: hostname(), lanCandidates, p2pProbe: config.p2pProbe === true, iceServers: config.p2pIceServers || [],
-        p2pWindowsRouteHelper: config.p2pWindowsRouteHelper === true, p2pWindowsRouteHelperToken: config.p2pWindowsRouteHelperToken || '' });
-      current.events.on('p2p-probe', result => audit('p2p-probe', result));
-      current.events.on('diagnostic', message => audit('transport-error', { message }));
-      current.events.on('attached', () => { paired = true; attachedCount++; audit('phone-attached', { attachedCount }); });
-      current.events.on('detached', () => { attachedCount = Math.max(0, attachedCount - 1); audit('phone-detached', { attachedCount }); });
-      current.events.on('authorization-changed', update => {
-        saveLanAuthorizations(stateRoot, identity.id, update.clients, update.revision);
-        paired = update.clients.length > 0; clientCount = update.clients.length;
-        audit('mobile-authorizations-updated', { clientCount, revision: update.revision });
-      });
-      current.events.once('disconnected', event => {
-        if (connector !== current || closing) return;
-        online = false; attachedCount = 0; lastError = `电脑与中继连接断开（${event.code}）：${event.reason}`; audit('relay-disconnected', event);
-        if (![1008, 4401, 4406, 4409, 4429].includes(event.code)) scheduleRetry();
-      });
-      const registration = await current.ready;
-      if (closing) return;
-      if (registration.protocolVersion !== 7 || registration.room !== identity.id) {
-        current.events.removeAllListeners(); current.close(); throw Object.assign(new Error('中继服务器尚未升级设备授权协议，未使用临时配对降级。'), { code: 4401 });
-      }
-      if (!identity.registered) {
-        const registeredIdentity = { ...identity, registered: true };
-        identities.devices[identity.id] = registeredIdentity;
-        await credentialStore('save', identities); identity = registeredIdentity;
-      }
-      if (closing) return;
-      current.assertConnected();
-      online = true; attempts = 0; paired = registration.paired; clientCount = registration.clientCount || 0; lastError = '';
-      saveLanAuthorizations(stateRoot, identity.id, registration.clients || [], registration.revision);
-      await saveInvitation(registration);
-      if (!closing) audit('relay-connected', { paired });
-    } catch (error) {
-      if (closing) return;
-      online = false; lastError = error.message; audit('connect-failed', { message: error.message });
-      if (![1008, 4401, 4406, 4409, 4429].includes(error.code)) retryAfterAttempt = true;
-      else { clearTimeout(retryTimer); retryTimer = undefined; }
-    } finally { connecting = false; if (retryAfterAttempt) scheduleRetry(); }
-  }
-  async function pair() {
-    if (!online || closing) throw new Error('中继尚未连接，设备授权保持不变。');
-    await saveInvitation(await connector.command('pair-code'));
-    // Each invitation adds or refreshes one mobile identity without revoking other devices.
-    return { ...status(), qrPath, expiresAt: new Date(expiresAt).toISOString(),
-      displayText: '用要添加的移动设备扫描此码。每台设备只需配对一次；已有设备授权保持不变。' };
-  }
-  async function revoke() {
-    if (!online || closing) throw new Error('中继尚未连接，未撤销授权。');
-    await connector.command('revoke'); paired = false; clientCount = 0; attachedCount = 0; qrPath = undefined; expiresAt = 0;
-    return { ...status(), displayText: '全部移动设备授权已撤销；重新添加请调用 relax pair --json。' };
-  }
-  async function invite(command, details) {
-    if (!online || closing) throw new Error('中继尚未连接，请先执行 relax start。');
-    const result = await connector.command(command, command === 'invite-create' ? { expires: details.expires } : command === 'invite-revoke' ? { id: details.id } : {});
-    if (command === 'invite-create') {
-      const link = new URL(config.pairingUrl);
-      link.searchParams.set('invite', result.code);
-      const inviteQrPath = path.join(stateRoot, `self-relay-long-qr-${result.id}.png`);
-      try { await QRCode.toFile(inviteQrPath, link.href, { width: 640, margin: 3 }); }
-      catch (error) { throw new Error(`二维码保存失败：${error.message}。邀请 ID：${result.id}；请执行 relax pair-revoke ${result.id} 废止。`); }
-      return { invitationId: result.id, deviceId: result.room, expiresAt: new Date(result.expires).toISOString(), qrPath: inviteQrPath,
-        displayText: `长期配对邀请已创建。邀请 ID：${result.id}\n截止：${new Date(result.expires).toISOString()}` };
-    }
-    if (command === 'invite-list') return { invitations: result.invitations,
-      displayText: result.invitations.length ? result.invitations.map(item => `${item.id}  ${new Date(item.expires).toISOString()}${Date.now() >= item.expires ? '（已过期）' : ''}`).join('\n') : '本工作站没有长期配对邀请。' };
-    return { invitationId: result.id, revoked: result.revoked, displayText: '长期邀请已废止；已配对手机的独立授权保持不变。' };
-  }
-  async function refreshLan() {
-    if (!online || closing) throw new Error('中继尚未连接，未更新局域网候选。');
-    await refreshHealth();
-    const candidates = await currentLanCandidates();
-    connector.updateLanCandidates(candidates);
-    audit('lan-candidates-updated', { count: candidates.length });
-    return { ...status(), lanCandidateCount: candidates.length };
-  }
-  const inspect = async () => {
-    if (online) {
-      const remote = await connector.command('status'); paired = remote.paired;
-      await refreshHealth();
-    }
-    return status();
-  };
-  try { await connect(); return { status, inspect, pair, revoke, invite, refreshLan, shutdown }; }
-  catch (error) { await shutdown(); throw error; }
-}
-
-export function createRelayManager(stateRoot) {
-  let current;
-  let operation = Promise.resolve();
-  const run = (command, details = {}) => {
-    const next = operation.then(async () => {
-      if (command === 'relay-status') return current ? current.inspect() : { running: false, displayText: '中继连接未运行。' };
-      if (command === 'relay-stop') {
-        await current?.shutdown(); current = undefined;
-        return { stopped: true, displayText: '中继连接已停止；桌面服务和 Codex 内核保持运行。' };
-      }
-      if (!current) {
-        if (command.startsWith('invite-')) throw new Error('请先执行 relax start 连接中继。');
-        if (command === 'relay-revoke') throw new Error('请先启动中继连接，再撤销移动端授权。');
-        current = await createRelayRuntime(stateRoot);
-        return command === 'relay-pair' && current.status().relayConnected ? current.pair() : current.status();
-      }
-      if (command.startsWith('invite-')) return current.invite(command, details);
-      if (command === 'relay-revoke') return current.revoke();
-      if (command === 'relay-pair' || (current.status().relayConnected && !current.status().paired && !current.status().qrPath)) return current.pair();
-      if (command === 'relay-start' && current.status().relayConnected) return current.refreshLan();
-      return current.status();
-    });
-    operation = next.catch(() => {});
-    return next;
-  };
-  return { run, close: () => run('relay-stop'), status: () => current?.status() || { running: false } };
-}
+import path from 'node:path';
+import serviceEndpoints from '../../shared/service-endpoints.cjs';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import QRCode from 'qrcode';
+import { credentialStore } from '../platform/credential-store.mjs';
+import { readRecord, writeRecord } from '../service-lifecycle.mjs';
+import { serviceHealth } from '../service-health.mjs';
+import { controlRequest } from '../service-control.mjs';
+import { connectBridgeRelay } from './connector.mjs';
+import { validProbeIceServers } from './p2p-probe.mjs';
+import { relayAddress, validSecret } from './wire.mjs';
+import { saveLanAuthorizations, onLanDeviceConnected, pendingLanConnections } from './lan-authorizations.mjs';
+import { lanNetworks } from '../platform/network-info.mjs';
+
+const officialConfig = { url: serviceEndpoints.relayUrl };
+
+async function loadConfig(stateRoot) {
+  const configPath = path.join(stateRoot, 'self-relay-config.json');
+  const stored = readRecord(configPath) || {};
+  const config = { ...officialConfig, ...stored };
+  if (!stored.url) writeRecord(configPath, config);
+  if (config.p2pIceServers !== undefined && !validProbeIceServers(config.p2pIceServers)) throw new Error('p2pIceServers 只接受最多 4 个 stun:主机:端口地址');
+  if (config.p2pWindowsRouteHelper !== undefined && typeof config.p2pWindowsRouteHelper !== 'boolean') throw new Error('p2pWindowsRouteHelper 必须是布尔值');
+  if (config.p2pWindowsRouteHelper && !/^[A-Za-z0-9_-]{32,128}$/.test(config.p2pWindowsRouteHelperToken || '')) throw new Error('p2pWindowsRouteHelperToken 无效');
+  const url = process.env.RELAY_URL || serviceEndpoints.resolveRelayUrl(config.url);
+  if (!url) throw new Error('请先配置 self-relay-config.json 的 url，详见自建中继文档。');
+  relayAddress(url);
+  const resolved = relayAddress(url);
+  const pairingUrl = config.pairingUrl || (resolved === serviceEndpoints.relayUrl ? serviceEndpoints.pairingUrl : `${resolved.startsWith('wss:') ? 'https:' : 'http:'}//${new URL(resolved).host}/pair`);
+  const pairing = new URL(pairingUrl);
+  if (!['https:', 'http:'].includes(pairing.protocol) || pairing.pathname !== '/pair' || pairing.search || pairing.hash || pairing.username || pairing.password ||
+      (pairing.protocol === 'http:' && pairing.hostname !== '127.0.0.1')) throw new Error('self-relay-config.json 的 pairingUrl 必须是 HTTPS /pair 地址。');
+  return { ...config, url: resolved, pairingUrl: pairing.href };
+}
+export async function selfRelay(command, stateRoot, details) {
+  const session = readRecord(path.join(stateRoot, 'bridge-session.json'));
+  if (!session) {
+    if (command === 'relay-status') return { running: false, displayText: '桌面服务未运行。' };
+    if (command === 'relay-stop') return { stopped: true, displayText: '中继连接已停止。' };
+    throw new Error('桌面服务尚未运行，请先执行 relax start。');
+  }
+  return controlRequest(session, 'POST', command, details);
+}
+
+async function createRelayRuntime(stateRoot) {
+  const config = await loadConfig(stateRoot);
+  const configPath = path.join(stateRoot, 'self-relay-config.json');
+  const session = () => readRecord(path.join(stateRoot, 'bridge-session.json'));
+  let health = await serviceHealth(session());
+  if (health?.status !== 'ok') throw new Error('桌面服务尚未运行，请先执行 relax start --json。');
+  const stored = await credentialStore('load');
+  const identities = stored.record || { version: 2, devices: {} };
+  const validIdentity = (id, item) => /^[\w-]{16,128}$/.test(id) && item?.id === id &&
+    validSecret(item.secret) && typeof item.registered === 'boolean';
+  if (identities.version !== 2 || !identities.devices || typeof identities.devices !== 'object' || Array.isArray(identities.devices) ||
+      Object.entries(identities.devices).some(([id, item]) => !validIdentity(id, item))) throw new Error('本机设备身份损坏，未自动覆盖');
+  if (!config.deviceId) {
+    const known = Object.values(identities.devices);
+    if (known.length > 1) throw new Error('存在多个工作站身份，请在 self-relay-config.json 中指定 deviceId。');
+    config.deviceId = known[0]?.id || randomUUID();
+  }
+  const createIdentity = config.deviceId === 'new';
+  if (createIdentity) config.deviceId = randomUUID();
+  if (!/^[\w-]{16,128}$/.test(config.deviceId)) throw new Error('self-relay-config.json 的 deviceId 无效。');
+  let identity = identities.devices[config.deviceId];
+  if (!identity) {
+    if (!createIdentity && Object.keys(identities.devices).length) throw new Error('找不到配置指定的工作站身份，未自动创建新身份。');
+    identity = { id: config.deviceId, secret: randomBytes(32).toString('base64url'), registered: false };
+    identities.devices[identity.id] = identity;
+    await credentialStore('save', identities);
+  }
+  const persistedConfig = readRecord(configPath) || {};
+  if (persistedConfig.deviceId !== identity.id) writeRecord(configPath, { ...persistedConfig, deviceId: identity.id });
+  let bridgeError = '';
+  async function refreshHealth() {
+    try { health = await serviceHealth(session()) || { transportMode: health.transportMode, status: 'offline' }; bridgeError = ''; }
+    catch (error) { bridgeError = error.message; health = { transportMode: health.transportMode, status: 'offline' }; }
+  }
+  let connector, qrPath, expiresAt = 0, paired = false, clientCount = 0, attachedCount = 0;
+  let closing = false, online = false, connecting = false, retryTimer, attempts = 0, lastError = '';
+  const audit = (event, details = {}) => console.log(JSON.stringify({ time: new Date().toISOString(), event, ...details }));
+  const stopWatchingDevices = onLanDeviceConnected(stateRoot, info => {
+    if (online && !closing) connector.reportDeviceConnection(info);
+  });
+  async function currentLanCandidates() {
+    try {
+      const bridge = session(), port = bridge?.port || 45831;
+      return (await lanNetworks()).map(network => ({ ...network, address: `http://${network.address}:${port}` }));
+    } catch (error) {
+      audit('lan-candidates-unavailable', { message: error.message }); return [];
+    }
+  }
+  const status = () => {
+    const available = online && !paired && qrPath && Date.now() < expiresAt;
+    const next = !online ? (lastError || '电脑连接器正在恢复中继连接，已保存授权。')
+      : paired ? '设备已授权，移动端可直接重连；网络断开不需要重新扫码。'
+        : available ? '用要添加的移动设备在有效期内扫描统一配对二维码。连接器在后台运行。'
+          : '尚未完成设备授权；调用 relax pair --json 生成配对二维码。';
+    return { running: !closing, relayConnected: online, mode: 'self-relay', transportMode: health.transportMode,
+      relayUrl: config.url, deviceId: identity.id, paired, clientCount, authorization: online ? (paired ? 'authorized' : 'unpaired') : 'unverified', phoneConnected: attachedCount > 0,
+      bridgeReady: health.status === 'ok' && health.execution?.ready === true && health.sharedAppServerConnected === true, bridgeError,
+      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null,
+      ...(available ? { qrPath } : {}), mobileAccess: 'unverified', lastError,
+      displayText: `Code Relax 中继 · ${health.transportMode === 'lan-shared' ? 'Codex 内核已就绪' : 'Codex 内核未就绪'}\n${next}` };
+  };
+  async function shutdown() {
+    if (closing) return;
+    closing = true; online = false; attachedCount = 0; clearTimeout(retryTimer);
+    stopWatchingDevices();
+    connector?.events.removeAllListeners(); connector?.close();
+  }
+  async function saveInvitation(message) {
+    if (!message.code) return;
+    expiresAt = message.expires;
+    const link = new URL(config.pairingUrl);
+    link.searchParams.set('invite', message.code);
+    // Keep previously displayed files intact even when their invitation expires.
+    qrPath = path.join(stateRoot, `self-relay-qr-${randomUUID()}.png`);
+    await QRCode.toFile(qrPath, link.href, { width: 640, margin: 3 });
+  }
+  function scheduleRetry() {
+    if (closing || retryTimer) return;
+    const delay = Math.min(1000 * 2 ** Math.min(attempts++, 5), 30000) * (0.8 + Math.random() * 0.2);
+    retryTimer = setTimeout(() => { retryTimer = undefined; void connect(); }, delay);
+  }
+  async function connect() {
+    if (closing || connecting) return;
+    connecting = true;
+    let retryAfterAttempt = false;
+    try {
+      const bridge = session();
+      await refreshHealth();
+      if (closing) return;
+      const lanCandidates = await currentLanCandidates();
+      if (closing) return;
+      connector?.events.removeAllListeners(); connector?.close();
+      const current = connector = connectBridgeRelay({ relayUrl: config.url, identity,
+        usageCacheFile: path.join(stateRoot, 'relay-usage-tasks.json'),
+        bridgeUrl: `ws://127.0.0.1:${bridge?.port || 45831}/api/socket`, bridgeToken: bridge?.accessUrl ? new URL(bridge.accessUrl).searchParams.get('token') : 'unavailable',
+        bridgeConnection: () => { const latest = session(); return { url: `ws://127.0.0.1:${latest.port}/api/socket`, token: new URL(latest.accessUrl).searchParams.get('token') }; },
+        hostName: hostname(), lanCandidates, p2pProbe: config.p2pProbe === true, iceServers: config.p2pIceServers || [],
+        p2pWindowsRouteHelper: config.p2pWindowsRouteHelper === true, p2pWindowsRouteHelperToken: config.p2pWindowsRouteHelperToken || '' });
+      current.events.on('p2p-probe', result => audit('p2p-probe', result));
+      current.events.on('diagnostic', message => audit('transport-error', { message }));
+      current.events.on('attached', () => { paired = true; attachedCount++; audit('phone-attached', { attachedCount }); });
+      current.events.on('detached', () => { attachedCount = Math.max(0, attachedCount - 1); audit('phone-detached', { attachedCount }); });
+      current.events.on('authorization-changed', update => {
+        saveLanAuthorizations(stateRoot, identity.id, update.clients, update.revision);
+        paired = update.clients.length > 0; clientCount = update.clients.length;
+        audit('mobile-authorizations-updated', { clientCount, revision: update.revision });
+      });
+      current.events.once('disconnected', event => {
+        if (connector !== current || closing) return;
+        online = false; attachedCount = 0; lastError = `电脑与中继连接断开（${event.code}）：${event.reason}`; audit('relay-disconnected', event);
+        if (![1008, 4401, 4406, 4409, 4429].includes(event.code)) scheduleRetry();
+      });
+      const registration = await current.ready;
+      if (closing) return;
+      if (registration.protocolVersion !== 7 || registration.room !== identity.id) {
+        current.events.removeAllListeners(); current.close(); throw Object.assign(new Error('中继服务器尚未升级设备授权协议，未使用临时配对降级。'), { code: 4401 });
+      }
+      if (!identity.registered) {
+        const registeredIdentity = { ...identity, registered: true };
+        identities.devices[identity.id] = registeredIdentity;
+        await credentialStore('save', identities); identity = registeredIdentity;
+      }
+      if (closing) return;
+      current.assertConnected();
+      online = true; attempts = 0; paired = registration.paired; clientCount = registration.clientCount || 0; lastError = '';
+      saveLanAuthorizations(stateRoot, identity.id, registration.clients || [], registration.revision);
+      for (const info of pendingLanConnections(stateRoot)) current.reportDeviceConnection(info);
+      await saveInvitation(registration);
+      if (!closing) audit('relay-connected', { paired });
+    } catch (error) {
+      if (closing) return;
+      online = false; lastError = error.message; audit('connect-failed', { message: error.message });
+      if (![1008, 4401, 4406, 4409, 4429].includes(error.code)) retryAfterAttempt = true;
+      else { clearTimeout(retryTimer); retryTimer = undefined; }
+    } finally { connecting = false; if (retryAfterAttempt) scheduleRetry(); }
+  }
+  async function pair() {
+    if (!online || closing) throw new Error('中继尚未连接，设备授权保持不变。');
+    await saveInvitation(await connector.command('pair-code'));
+    // Each invitation adds or refreshes one mobile identity without revoking other devices.
+    return { ...status(), qrPath, expiresAt: new Date(expiresAt).toISOString(),
+      displayText: '用要添加的移动设备扫描此码。每台设备只需配对一次；已有设备授权保持不变。' };
+  }
+  async function revoke() {
+    if (!online || closing) throw new Error('中继尚未连接，未撤销授权。');
+    await connector.command('revoke'); paired = false; clientCount = 0; attachedCount = 0; qrPath = undefined; expiresAt = 0;
+    return { ...status(), displayText: '全部移动设备授权已撤销；重新添加请调用 relax pair --json。' };
+  }
+  async function invite(command, details) {
+    if (!online || closing) throw new Error('中继尚未连接，请先执行 relax start。');
+    const result = await connector.command(command, command === 'invite-create' ? { expires: details.expires } : command === 'invite-revoke' ? { id: details.id } : {});
+    if (command === 'invite-create') {
+      const link = new URL(config.pairingUrl);
+      link.searchParams.set('invite', result.code);
+      const inviteQrPath = path.join(stateRoot, `self-relay-long-qr-${result.id}.png`);
+      try { await QRCode.toFile(inviteQrPath, link.href, { width: 640, margin: 3 }); }
+      catch (error) { throw new Error(`二维码保存失败：${error.message}。邀请 ID：${result.id}；请执行 relax pair-revoke ${result.id} 废止。`); }
+      return { invitationId: result.id, deviceId: result.room, expiresAt: new Date(result.expires).toISOString(), qrPath: inviteQrPath,
+        displayText: `长期配对邀请已创建。邀请 ID：${result.id}\n截止：${new Date(result.expires).toISOString()}` };
+    }
+    if (command === 'invite-list') return { invitations: result.invitations,
+      displayText: result.invitations.length ? result.invitations.map(item => `${item.id}  ${new Date(item.expires).toISOString()}${Date.now() >= item.expires ? '（已过期）' : ''}`).join('\n') : '本工作站没有长期配对邀请。' };
+    return { invitationId: result.id, revoked: result.revoked, displayText: '长期邀请已废止；已配对手机的独立授权保持不变。' };
+  }
+  async function refreshLan() {
+    if (!online || closing) throw new Error('中继尚未连接，未更新局域网候选。');
+    await refreshHealth();
+    const candidates = await currentLanCandidates();
+    connector.updateLanCandidates(candidates);
+    audit('lan-candidates-updated', { count: candidates.length });
+    return { ...status(), lanCandidateCount: candidates.length };
+  }
+  async function devices(command, details = {}) {
+    if (!online || closing) throw new Error('中继尚未连接，未读取或修改配对授权。');
+    const result = await connector.command(command, command === 'device-revoke' ? { id: details.id, confirmed: details.confirmed === true } : {});
+    return command === 'devices-list' ? { clients: result.clients, workstationOnline: result.workstationOnline,
+      displayText: result.clients.map(item => `${item.id}  ${item.platform || '平台未记录'}  ${item.deviceName || ''}  最后连接：${item.lastConnectedAt || '未记录'}`).join('\n') || '没有配对授权。' }
+      : { id: result.id, revoked: result.revoked, displayText: '指定配对授权已撤销；其他授权和长期邀请保持不变。' };
+  }
+  const inspect = async () => {
+    if (online) {
+      const remote = await connector.command('status'); paired = remote.paired;
+      await refreshHealth();
+    }
+    return status();
+  };
+  try { await connect(); return { status, inspect, pair, revoke, invite, devices, refreshLan, shutdown }; }
+  catch (error) { await shutdown(); throw error; }
+}
+
+export function createRelayManager(stateRoot) {
+  let current;
+  let operation = Promise.resolve();
+  const run = (command, details = {}) => {
+    const next = operation.then(async () => {
+      if (command === 'relay-status') return current ? current.inspect() : { running: false, displayText: '中继连接未运行。' };
+      if (command === 'relay-stop') {
+        await current?.shutdown(); current = undefined;
+        return { stopped: true, displayText: '中继连接已停止；桌面服务和 Codex 内核保持运行。' };
+      }
+      if (!current) {
+        if (['devices-list', 'device-revoke'].includes(command)) throw new Error('请先执行 relax start 连接中继。');
+        if (command.startsWith('invite-')) throw new Error('请先执行 relax start 连接中继。');
+        if (command === 'relay-revoke') throw new Error('请先启动中继连接，再撤销移动端授权。');
+        current = await createRelayRuntime(stateRoot);
+        return command === 'relay-pair' && current.status().relayConnected ? current.pair() : current.status();
+      }
+      if (command.startsWith('invite-')) return current.invite(command, details);
+      if (['devices-list', 'device-revoke'].includes(command)) return current.devices(command, details);
+      if (command === 'relay-revoke') return current.revoke();
+      if (command === 'relay-pair' || (current.status().relayConnected && !current.status().paired && !current.status().qrPath)) return current.pair();
+      if (command === 'relay-start' && current.status().relayConnected) return current.refreshLan();
+      return current.status();
+    });
+    operation = next.catch(() => {});
+    return next;
+  };
+  return { run, close: () => run('relay-stop'), status: () => current?.status() || { running: false } };
+}