@walkhi/code-relax 0.1.0-beta.1

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

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { decode, loopbackUrl, relayAddress, send } from './wire.mjs';
+import { createP2pProbe, validProbeSignal } from './p2p-probe.mjs';
+import { createWindowsRouteHelper } from './windows-route-helper.mjs';
+
+// Reuse the actual LAN dispatcher, including its normal/shared capability boundary.
+// The LAN token never travels to the relay. No requests are replayed after a close.
+export function connectBridgeRelay({ relayUrl, hostKey, bridgeUrl, bridgeToken, identity, bridgeConnection, hostName = 'Codex-PC', lanCandidates = [], p2pProbe = false, iceServers = [], p2pWindowsRouteHelper = false, p2pWindowsRouteHelperToken = '' }) {
+  relayAddress(relayUrl); loopbackUrl(bridgeUrl, '/api/socket');
+  if (!bridgeToken) throw new Error('Bridge token required');
+  const events = new EventEmitter();
+  const remote = new WebSocket(relayUrl, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: {
+    serverNoContextTakeover: true, clientNoContextTakeover: true,
+    threshold: 1024, zlibDeflateOptions: { level: 3 },
+  } });
+  const locals = new Map();
+  let heartbeat, operation, lastClose;
+  const alive = () => { clearTimeout(heartbeat); heartbeat = setTimeout(() => remote.terminate(), 75000); };
+  remote.on('open', alive); remote.on('ping', alive); remote.on('message', alive);
+  function dropLocal(session) {
+    const current = locals.get(session);
+    if (!current) return;
+    locals.delete(session); clearTimeout(current.timer); current.socket?.terminate();
+    current.probe?.then(probe => probe.close());
+  }
+  function dropLocals() {
+    for (const session of [...locals.keys()]) dropLocal(session);
+  }
+  const ready = new Promise((resolve, reject) => {
+    let registered = false;
+    const timer = setTimeout(() => { reject(new Error('Relay registration timeout')); remote.terminate(); }, 5000);
+    remote.on('open', () => send(remote, { type: 'host', key: hostKey, hostName, lanCandidates, p2pProbe: p2pProbe ? 1 : 0, p2pProbeRepeat: true,
+      ...(identity ? { deviceId: identity.id, deviceSecret: identity.secret } : {}) }));
+    remote.on('error', error => { reject(error); events.emit('diagnostic', error.message); });
+    remote.on('close', (code, reason) => {
+      clearTimeout(timer); clearTimeout(heartbeat); dropLocals();
+      const error = lastClose = Object.assign(new Error(`Relay closed (${code}): ${reason.toString()}`), { code });
+      if (!registered) reject(error);
+      if (operation) { clearTimeout(operation.timer); operation.reject(error); operation = undefined; }
+      events.emit('disconnected', { code, reason: reason.toString() });
+    });
+    remote.on('message', (bytes, binary) => {
+      try {
+        const message = decode(bytes, binary);
+        if (message.type === 'registered' && !registered) { registered = true; clearTimeout(timer); resolve(message); return; }
+        if (!registered) throw new Error('Relay not registered');
+        if (message.type === 'pair-code' || message.type === 'revoked' || message.type === 'status') {
+          if (operation && message.commandId === operation.id && message.type === operation.responseType) {
+            clearTimeout(operation.timer); const pending = operation; operation = undefined;
+            message.error ? pending.reject(new Error(message.error)) : pending.resolve(message);
+          }
+          return;
+        }
+        if (message.type === 'authorization-changed' && Array.isArray(message.clients) && Number.isSafeInteger(message.revision)) {
+          events.emit('authorization-changed', { clients: message.clients, revision: message.revision }); return;
+        }
+        if (message.type === 'attach') {
+          events.emit('attached', { session: message.session, clientId: message.clientId });
+          dropLocal(message.session);
+          const current = { socket: undefined, ready: false, timer: undefined, p2pProbe: p2pProbe && message.p2pProbe === 1 };
+          locals.set(message.session, current);
+          let connection;
+          try {
+            connection = bridgeConnection?.() || { url: bridgeUrl, token: bridgeToken };
+            loopbackUrl(connection.url, '/api/socket');
+          } catch {
+            send(remote, { type: 'detach', session: message.session }); dropLocal(message.session); events.emit('detached', { session: message.session });
+            events.emit('diagnostic', 'Local Bridge connection not ready'); return;
+          }
+          const socket = current.socket = new WebSocket(connection.url, { maxPayload: 64 * 1024 * 1024, perMessageDeflate: false });
+          current.timer = setTimeout(() => socket.terminate(), 5000);
+          socket.on('open', () => send(socket, { type: 'auth', token: connection.token }));
+          socket.on('error', error => events.emit('diagnostic', `Local Bridge: ${error.message}`));
+          socket.on('close', () => {
+            if (locals.get(message.session)?.socket !== socket) return;
+            send(remote, { type: 'detach', session: message.session }); dropLocal(message.session); events.emit('detached', { session: message.session });
+          });
+          socket.on('message', (data, isBinary) => {
+            if (locals.get(message.session)?.socket !== socket) return;
+            try {
+              const response = decode(data, isBinary);
+              if (!current.ready) {
+                if (response.type !== 'ready') throw new Error('Local Bridge authentication failed');
+                clearTimeout(current.timer); current.ready = true; send(remote, { type: 'ready', session: message.session });
+              } else send(remote, { type: 'data', session: message.session, payload: data.toString() });
+            } catch (error) { events.emit('diagnostic', error.message); socket.terminate(); }
+          });
+        } else if (message.type === 'p2p-probe' && locals.has(message.session)) {
+          const current = locals.get(message.session);
+          if (!current.ready || !current.p2pProbe || !validProbeSignal(message)) throw new Error('Invalid probe signal');
+          if (message.kind === 'start' && current.probeId !== message.probeId) {
+            void current.probe?.then(probe => probe.close());
+            current.probeId = message.probeId;
+            current.routeSignals = Promise.resolve();
+            const probeId = message.probeId;
+            current.routeHelper = createWindowsRouteHelper({ enabled: p2pWindowsRouteHelper, token: p2pWindowsRouteHelperToken, iceServers,
+              report: (event, details) => events.emit('diagnostic', `${event};count=${details.count}`) });
+            current.probe = current.routeHelper.prepare().then(() => createP2pProbe({ iceServers,
+              signal: signal => {
+                if (locals.get(message.session) === current && current.probeId === probeId) send(remote, { type: 'p2p-probe', session: message.session,
+                  version: 1, probeId, ...signal });
+              }, report: (state, diagnostic) => events.emit('p2p-probe', { state, diagnostic })
+            })).catch(() => {
+              events.emit('diagnostic', p2pWindowsRouteHelper ? 'Windows RTC 路由辅助不可用' : 'WebRTC probe initialization failed');
+              return { receive() {}, close() {} };
+            });
+          } else if (current.probe && current.probeId === message.probeId) {
+            const pending = current.probe;
+            current.routeSignals ||= Promise.resolve();
+            current.routeSignals = current.routeSignals.then(async () => {
+              await current.routeHelper?.include(message);
+              const probe = await pending;
+              if (locals.get(message.session) === current && current.probeId === message.probeId) probe.receive(message);
+            });
+            void current.routeSignals
+              .catch(() => { events.emit('diagnostic', 'WebRTC probe negotiation failed'); void pending.then(probe => probe.close()); });
+          }
+        } else if (message.type === 'detach' && locals.has(message.session)) { dropLocal(message.session); events.emit('detached', { session: message.session }); }
+        else if (message.type === 'data' && locals.has(message.session)) {
+          const current = locals.get(message.session);
+          if (!current.ready) { send(remote, { type: 'detach', session: message.session }); dropLocal(message.session); return; }
+          const request = decode(message.payload, false);
+          if (!['request', 'subscribe', 'unsubscribe'].includes(request.type)) throw new Error('Unsupported LAN message');
+          send(current.socket, request);
+        }
+      } catch (error) { events.emit('diagnostic', error.message); remote.close(1008, 'Invalid relay message'); }
+    });
+  });
+  return { ready, events,
+    assertConnected() { if (remote.readyState !== WebSocket.OPEN) throw lastClose || new Error('Relay disconnected during registration'); },
+    command(type, details = {}) {
+      if (operation) return Promise.reject(new Error('已有设备管理操作正在执行'));
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { operation = undefined; reject(new Error('设备管理请求超时，结果未确认；未自动重发')); }, 7000);
+        const id = randomUUID();
+        operation = { resolve, reject, timer, id, responseType: type === 'revoke' ? 'revoked' : type };
+        if (!send(remote, { type, commandId: id, ...details })) { clearTimeout(timer); operation = undefined; reject(new Error('中继未连接')); }
+      });
+    },
+    updateLanCandidates(candidates) {
+      if (!send(remote, { type: 'lan-candidates', candidates })) throw new Error('中继未连接');
+    },
+    close() { clearTimeout(heartbeat); dropLocals(); remote.terminate(); }
+  };
+}

package/dist/src/self-relay/debug-allowlist.mjs

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { validId } from './device-store.mjs';
+
+export function readDebugAllowlist(file) {
+  if (!file || !fs.existsSync(file)) return { version: 1, devices: [] };
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (value.version !== 1 || !Array.isArray(value.devices) || value.devices.some(entry => !validId(entry.deviceId))) {
+    throw new Error('Invalid debug allowlist');
+  }
+  return value;
+}
+
+export function debugAllowed(allowlist, deviceId, client) {
+  return Boolean(client && allowlist.devices.some(entry => entry.deviceId === deviceId));
+}
+
+// Administrator-only file; never invoked by the relay wire protocol or Desktop CLI.
+export function updateDebugAllowlist(file, deviceId, enabled) {
+  if (!validId(deviceId)) throw new Error('Invalid debug device');
+  const value = readDebugAllowlist(file);
+  const previous = fs.existsSync(file) ? fs.statSync(file) : null;
+  value.devices = value.devices.filter(entry => entry.deviceId !== deviceId);
+  if (enabled) value.devices.push({ deviceId });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + '\n', { mode: 0o640, flag: 'wx' });
+    if (previous && process.platform !== 'win32') fs.chownSync(temporary, previous.uid, previous.gid);
+    fs.renameSync(temporary, file);
+  } finally { fs.rmSync(temporary, { force: true }); }
+}

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

@@ -0,0 +1,38 @@
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { attachLanSocket } from '../lan-socket-server.mjs';
+import { startSelfRelay } from './server.mjs';
+import { connectBridgeRelay } from './connector.mjs';
+import { connectRelayClient } from './client.mjs';
+import { secret } from './wire.mjs';
+
+export async function startRelayDemo({ mode = 'lan-shared', pairingTtlMs, dispatch, remoteRelay, hostName = 'TEST-PC', lanCandidates = [] } = {}) {
+  if (!['lan-legacy', 'lan-shared'].includes(mode)) throw new Error('Invalid demo mode');
+  const token = secret(), calls = [];
+  const bridge = http.createServer((_request, response) => { response.writeHead(404); response.end(); });
+  const lan = attachLanSocket(bridge, { token, dispatch: async (request, reply) => {
+    calls.push(request);
+    if (dispatch) return dispatch(request, reply);
+    if (request.url === '/api/health') return reply.json(200, { ok: true, transportMode: mode, simulated: true });
+    if (request.url.split('?')[0] === '/api/threads/demo/events') {
+      reply.startEvents(); reply.event('update', { thread: { id: 'demo' }, simulated: true }); return;
+    }
+    if (request.url === '/api/demo/stop') return reply.json(mode === 'lan-shared' ? 200 : 409,
+      mode === 'lan-shared' ? { stopped: true, simulated: true } : { error: '基础控制不支持停止任务' });
+    reply.json(404, { error: '模拟 Bridge 不执行真实任务' });
+  } });
+  await new Promise(resolve => bridge.listen(0, '127.0.0.1', resolve));
+  const relay = remoteRelay ? { ...remoteRelay, async close() {} } : await startSelfRelay({ pairingTtlMs });
+  const bridgeUrl = `ws://127.0.0.1:${bridge.address().port}/api/socket`;
+  const identity = remoteRelay ? { id: randomUUID(), secret: secret() } : undefined;
+  const clientId = randomUUID(), credential = secret();
+  const connector = connectBridgeRelay({ identity, relayUrl: relay.url, hostKey: relay.hostKey, bridgeUrl, bridgeToken: token, hostName, lanCandidates });
+  let pairing;
+  try { pairing = await connector.ready; }
+  catch (error) { connector.close(); await relay.close(); lan.close(); await new Promise(resolve => bridge.close(resolve)); throw error; }
+  return {
+    relay, connector, pairing, bridgeUrl, calls,
+    connect(options = {}) { return connectRelayClient({ relayUrl: relay.url, room: pairing.room, code: pairing.code, ...(remoteRelay ? { clientId, credential } : {}), ...options }); },
+    async close() { if (remoteRelay) await connector.command('revoke'); connector.close(); await relay.close(); lan.close(); await new Promise(resolve => bridge.close(resolve)); },
+  };
+}

package/dist/src/self-relay/device-store.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const validId = value => typeof value === 'string' && /^[\w-]{16,128}$/.test(value);
+const hash = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export function deviceStore(file, { initialize = false } = {}) {
+  let devices = new Map();
+  function validate(record) {
+    if (!validId(record.id) || !hash(record.hostHash) || !['active', 'revoked'].includes(record.status) ||
+        !Number.isSafeInteger(record.revision) || record.revision < 0 ||
+        !Array.isArray(record.clients) || record.clients.length > 16 ||
+        record.clients.some(client => !validId(client.id) || !hash(client.hash) ||
+          !Number.isFinite(Date.parse(client.createdAt)) || !Number.isFinite(Date.parse(client.updatedAt))) ||
+        new Set(record.clients.map(client => client.id)).size !== record.clients.length ||
+        !Number.isFinite(Date.parse(record.createdAt)) || !Number.isFinite(Date.parse(record.updatedAt)) ||
+        !validOfficialComputer(record.officialComputer)) {
+      throw new Error('Invalid relay device record');
+    }
+  }
+  function write(next) {
+    if (!file) return;
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+      fd = fs.openSync(temporary, 'wx', 0o600);
+      fs.writeFileSync(fd, JSON.stringify({ version: 4, devices: [...next.values()] }));
+      fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+      fs.renameSync(temporary, file);
+      if (process.platform !== 'win32') {
+        const directory = fs.openSync(path.dirname(file), 'r');
+        try { fs.fsyncSync(directory); } finally { fs.closeSync(directory); }
+      }
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+      fs.rmSync(temporary, { force: true });
+    }
+  }
+  if (file) {
+    if (!fs.existsSync(file)) {
+      if (!initialize) throw new Error('Device store missing; explicit --init-state required for first installation');
+      fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 }); write(devices);
+    } else {
+      if (initialize) throw new Error('Device store already exists; initialization refused');
+      const saved = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (![2, 3, 4].includes(saved.version) || !Array.isArray(saved.devices)) throw new Error('Invalid relay device store version');
+      for (const source of saved.devices) {
+        const record = saved.version === 2 ? {
+          ...source,
+          clients: source.clientHash == null ? [] : [{
+            id: source.clientId,
+            hash: source.clientHash,
+            createdAt: source.updatedAt,
+            updatedAt: source.updatedAt,
+          }],
+        } : source;
+        delete record.clientHash; delete record.clientId;
+        validate(record);
+        if (devices.has(record.id)) throw new Error('Duplicate relay device identity');
+        devices.set(record.id, record);
+      }
+    }
+  }
+  return {
+    entries: () => [...devices.values()],
+    // Synchronous single-writer commit: publish only after durable replacement.
+    save(record) {
+      validate(record);
+      const next = new Map(devices); next.set(record.id, record); write(next); devices = next;
+    },
+  };
+}
+
+function validOfficialComputer(value) {
+  if (value === undefined) return true;
+  return value && typeof value === 'object' && plain(value.environmentId, 256, false) &&
+    plain(value.name, 80, true) && plain(value.hostname, 80, true) &&
+    Number.isFinite(Date.parse(value.updatedAt));
+}
+
+function plain(value, limit, empty) {
+  return typeof value === 'string' && (empty || value.trim().length > 0) &&
+    value.trim().length <= limit && !/[\u0000-\u001f\u007f]/.test(value);
+}

package/dist/src/self-relay/lan-authorizations.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { digest, matches } from './wire.mjs';
+import { validId } from './device-store.mjs';
+
+const recordPath = stateRoot => path.join(stateRoot, 'lan-device-authorizations.json');
+const validHash = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+
+export function saveLanAuthorizations(stateRoot, hostId, clients, revision) {
+  if (!validId(hostId) || !Array.isArray(clients) || clients.length > 16 ||
+      clients.some(client => !validId(client.id) || !validHash(client.hash)) ||
+      !Number.isSafeInteger(revision) || revision < 0) throw new Error('Invalid LAN device authorization state');
+  const file = recordPath(stateRoot), temporary = `${file}.${randomUUID()}.tmp`;
+  const record = { version: 1, hostId, revision, clients: clients.map(client => ({ id: client.id, hash: client.hash })) };
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(record), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally { fs.rmSync(temporary, { force: true }); }
+}
+export function authorizeLanDevice(stateRoot, clientId, credential) {
+  if (!validId(clientId)) return false;
+  let record;
+  try { record = JSON.parse(fs.readFileSync(recordPath(stateRoot), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  if (record?.version !== 1 || !validId(record.hostId) || !Array.isArray(record.clients)) return false;
+  const client = record.clients.find(item => item?.id === clientId && validHash(item.hash));
+  return Boolean(client && matches(credential, client.hash));
+}

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

@@ -0,0 +1,281 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { startBackground, processAlive } from '../background-process.mjs';
+import { promisify } from 'node:util';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { hostname } from 'node:os';
+import QRCode from 'qrcode';
+import { credentialStore } from '../platform/windows/credential-store.mjs';
+import { readRecord, writeRecord } from '../service-lifecycle.mjs';
+import { serviceHealth } from '../service-health.mjs';
+import { openControl, 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/windows/network-info.mjs';
+
+const exec = promisify(execFile);
+const script = fileURLToPath(import.meta.url);
+const recordPath = root => path.join(root, 'self-relay-session.json');
+
+async function loadConfig(stateRoot) {
+  const config = readRecord(path.join(stateRoot, 'self-relay-config.json')) || {};
+  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 || config.url;
+  if (!url) throw new Error('请先配置 self-relay-config.json 的 url 和 hostKeyFile（或 sshHost、sshKeyPath），详见自建中继文档。');
+  relayAddress(url);
+  const resolved = relayAddress(url);
+  const pairingUrl = config.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 };
+}
+async function registrationKey(config) {
+  const hostKeyFile = process.env.RELAY_HOST_KEY_FILE || config.hostKeyFile;
+  let hostKey;
+  if (hostKeyFile) hostKey = fs.readFileSync(hostKeyFile, 'utf8').trim();
+  else {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(config.sshHost || '') ||
+      !/^\/[a-zA-Z0-9/_.-]+$/.test(config.sshKeyPath || '')) throw new Error('中继注册凭据配置不完整或无效。');
+    try {
+      const result = await exec('ssh', ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', config.sshHost,
+        `sudo -n cat ${config.sshKeyPath}`], { encoding: 'utf8', timeout: 15000, windowsHide: true });
+      hostKey = result.stdout.trim();
+    } catch { throw new Error('无法通过已配置 SSH 读取中继注册凭据。'); }
+  }
+  if (!validSecret(hostKey)) throw new Error('中继注册凭据格式无效。');
+  return hostKey;
+}
+
+export async function selfRelay(command, stateRoot, requiredMode = '') {
+  const previous = readRecord(recordPath(stateRoot));
+  let current;
+  if (previous) {
+    try { current = await controlRequest(previous); }
+    catch (error) { if (error.code !== 'ECONNREFUSED') throw error; }
+  }
+  if (command === 'relay-status' && current) return controlRequest(previous, 'POST', 'inspect');
+  if (command === 'relay-status') return current || { running: false, displayText: '私有中继连接器未运行。' };
+  if (command === 'relay-stop') {
+    if (current) await controlRequest(previous, 'POST');
+    const deadline = Date.now() + 10000;
+    while (current && processAlive(previous.pid)) {
+      if (Date.now() >= deadline) throw new Error('私有中继未在 10 秒内退出，未继续恢复服务。');
+      await delay(100);
+    }
+    return { stopped: true, displayText: '私有中继连接器已停止；Bridge 和 Codex 保持运行。' };
+  }
+  if (current) {
+    if (requiredMode) {
+      const bridge = await serviceHealth(readRecord(path.join(stateRoot, 'bridge-session.json')));
+      if (bridge?.transportMode !== requiredMode) throw new Error('当前 Bridge 未启用完整控制；请先执行 shared-start。');
+    }
+    if (command === 'relay-revoke') return controlRequest(previous, 'POST', 'revoke');
+    if (command === 'relay-pair' || (current.relayConnected && !current.paired && !current.qrPath)) return controlRequest(previous, 'POST', 'pair');
+    if (command === 'relay-start' && current.relayConnected) return controlRequest(previous, 'POST', 'refresh-lan');
+    return current;
+  }
+  if (command === 'relay-revoke') throw new Error('请先启动连接器，再撤销手机授权。');
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const instanceId = randomUUID();
+  const log = path.join(stateRoot, 'self-relay.log');
+  const readyPath = path.join(stateRoot, `relay-ready-${instanceId}.json`);
+  const pid = await startBackground(process.execPath, [script, '--worker', stateRoot, instanceId,
+    command === 'relay-pair' ? 'pair' : '', requiredMode], process.env, [log, log]);
+  try {
+    const deadline = Date.now() + 25000;
+    while (true) {
+      const result = readRecord(readyPath);
+      if (result) {
+        if (result.pid !== pid || result.instanceId !== instanceId) throw new Error('私有中继启动实例不匹配。');
+        if (result.error) throw new Error(result.error);
+        return result.status;
+      }
+      if (!processAlive(pid)) throw new Error('私有中继启动失败，请查看 self-relay.log。');
+      if (Date.now() >= deadline) throw new Error('私有中继启动超时。');
+      await delay(100);
+    }
+  } catch (error) { if (processAlive(pid)) process.kill(pid); throw error; }
+  finally { fs.rmSync(readyPath, { force: true }); }
+}
+
+async function worker(stateRoot, instanceId, refresh = false, requiredMode = '') {
+  const config = await loadConfig(stateRoot);
+  const session = () => readRecord(path.join(stateRoot, 'bridge-session.json'));
+  let health = await serviceHealth(session());
+  if (health?.status !== 'ok') throw new Error('Bridge 尚未运行，请先执行 relax start --json。');
+  if (requiredMode && health.transportMode !== requiredMode) throw new Error('完整控制的 Code Relax 中继需要完整控制 Bridge，请先执行 relax shared-start --json。');
+  const legacyPath = path.join(stateRoot, 'self-relay-device.json');
+  const legacy = readRecord(legacyPath);
+  const stored = await credentialStore('load');
+  let identities = stored.record || legacy || { version: 1, servers: {} };
+  const validate = value => {
+    if (value?.version !== 1 || !value.servers || typeof value.servers !== 'object' || Array.isArray(value.servers)) throw new Error('本机设备身份损坏，未自动覆盖');
+    for (const [url, item] of Object.entries(value.servers)) {
+      relayAddress(url);
+      if (!validSecret(item.secret) || !/^[\w-]{16,128}$/.test(item.id)) throw new Error('本机设备身份损坏，未自动覆盖');
+    }
+  };
+  validate(identities);
+  if (legacy) {
+    validate(legacy);
+    if (stored.record && JSON.stringify(stored.record) !== JSON.stringify(legacy)) throw new Error('新旧设备身份冲突，未覆盖任何凭据');
+    if (!stored.record) {
+      const verified = await credentialStore('save', identities);
+      if (JSON.stringify(verified.record) !== JSON.stringify(identities)) throw new Error('凭据迁移校验失败');
+    }
+    fs.rmSync(legacyPath);
+  }
+  let identity = identities.servers[config.url];
+  if (!identity) {
+    identity = { id: randomUUID(), secret: randomBytes(32).toString('base64url'), registered: false };
+    identities.servers[config.url] = identity; await credentialStore('save', identities);
+  }
+  const hostKey = identity.registered ? undefined : await registrationKey(config);
+  let bridgeError = '';
+  async function refreshHealth() {
+    try { health = await serviceHealth(session()) || { transportMode: health.transportMode, status: 'offline', desktopConnected: false }; bridgeError = ''; }
+    catch (error) { bridgeError = error.message; health = { transportMode: health.transportMode, status: 'offline', desktopConnected: false }; }
+  }
+  const secret = randomBytes(32).toString('base64url');
+  let connector, control, 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' && Boolean(health.sharedAppServerConnected || health.desktopConnected), bridgeError,
+      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null,
+      ...(available ? { qrPath } : {}), mobileAccess: 'unverified', lastError,
+      displayText: `Code Relax 中继 · ${health.transportMode === 'lan-shared' ? '完整控制' : '基础控制'}\n${next}\n停止连接器保留授权：relax relay-stop --json。撤销全部移动设备：relax relay-revoke --json。` };
+  };
+  async function shutdown() {
+    if (closing) return;
+    closing = true; clearTimeout(retryTimer);
+    connector?.events.removeAllListeners(); connector?.close();
+    if (readRecord(recordPath(stateRoot))?.instanceId === instanceId) fs.rmSync(recordPath(stateRoot), { force: true });
+    await control?.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();
+      const lanCandidates = await currentLanCandidates();
+      connector?.events.removeAllListeners(); connector?.close();
+      const current = connector = connectBridgeRelay({ relayUrl: config.url, hostKey: identity.registered ? undefined : hostKey, identity,
+        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 (registration.protocolVersion !== 3 || 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.servers[config.url] = registeredIdentity;
+        await credentialStore('save', identities); identity = registeredIdentity;
+      }
+      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); audit('relay-connected', { paired });
+    } catch (error) {
+      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 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 };
+  }
+  try {
+    const freshStatus = async () => {
+      if (online) {
+        const remote = await connector.command('status'); paired = remote.paired;
+        await refreshHealth();
+      }
+      return status();
+    };
+    control = await openControl({ instanceId, secret, shutdown, status, actions: { pair, revoke, inspect: freshStatus, 'refresh-lan': refreshLan } });
+    writeRecord(recordPath(stateRoot), { pid: process.pid, instanceId, controlSecret: secret, controlPort: control.port });
+    await connect();
+    const result = refresh && online ? await pair() : status();
+    writeRecord(path.join(stateRoot, `relay-ready-${instanceId}.json`), { instanceId, pid: process.pid, status: { ...result, pid: process.pid } });
+  } catch (error) { await shutdown(); throw error; }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === script && process.argv[2] === '--worker') {
+  worker(process.argv[3], process.argv[4], process.argv[5] === 'pair', process.argv[6]).catch(error => {
+    writeRecord(path.join(process.argv[3], `relay-ready-${process.argv[4]}.json`), { instanceId: process.argv[4], pid: process.pid, error: error.message });
+    console.error(error.message); process.exitCode = 1;
+  });
+}