@walkhi/code-relax 0.1.0-beta.10 → 0.1.0-beta.100

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

@@ -1,27 +1,20 @@
-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';
+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';
+import { connectionReporting } from './connection-reporting.mjs';
 
-const exec = promisify(execFile);
-const script = fileURLToPath(import.meta.url);
-const recordPath = root => path.join(root, 'self-relay-session.json');
-const officialConfig = { url: 'wss://api.uulife.site/relay' };
+const officialConfig = { url: serviceEndpoints.relayUrl };
 
 async function loadConfig(stateRoot) {
   const configPath = path.join(stateRoot, 'self-relay-config.json');
@@ -31,255 +24,255 @@ async function loadConfig(stateRoot) {
   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 地址。');
+  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 };
 }
-async function registrationKey(config) {
-  if (config.url === officialConfig.url) return undefined;
-  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 读取中继注册凭据。'); }
+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。');
   }
-  if (!validSecret(hostKey)) throw new Error('中继注册凭据格式无效。');
-  return hostKey;
+  return controlRequest(session, 'POST', command, details);
 }
-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('Codex 内核未就绪；请先执行 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('Codex 内核未就绪，请先执行 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];
+
+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', undefined, stateRoot);
+  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 (!stored.record && config.deviceId && config.deviceId !== 'new') {
+    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) {
-    identity = { id: randomUUID(), secret: randomBytes(32).toString('base64url'), registered: false };
-    identities.servers[config.url] = identity; await credentialStore('save', identities);
+    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, stateRoot);
   }
-  const hostKey = identity.registered ? undefined : await registrationKey(config);
+  const persistedConfig = readRecord(configPath) || {};
+  if (persistedConfig.deviceId !== identity.id) writeRecord(configPath, { ...persistedConfig, deviceId: identity.id });
   let bridgeError = '';
-  async function refreshHealth() {
+  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' }; }
-  }
-  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 ? '用要添加的移动设备在有效期内扫描统一配对二维码。连接器在后台运行。'
+  }
+  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);
+  });
+  const phoneReporting = connectionReporting(stateRoot);
+  const stopWatchingPhones = phoneReporting.watch(event => {
+    if (!online || closing) return;
+    try { connector.reportPhoneConnection(event); }
+    catch (error) { audit('phone-report-unavailable', { message: error.message }); }
+  });
+  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,
+    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}\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') }; },
+      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();
+    stopWatchingPhones();
+    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;
+      current.events.on('p2p-probe', result => audit('p2p-probe', result));
+      current.events.on('diagnostic', message => audit('transport-error', { message }));
+      current.events.on('phone-connection-ack', id => phoneReporting.acknowledge(id));
+      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.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;
+        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, stateRoot); 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);
+      for (const event of phoneReporting.pending()) current.reportPhoneConnection(event);
+      current.reportPhoneConnections(phoneReporting.snapshot());
+      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 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;
-  });
-}
+  }
+  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 } };
+}

package/dist/src/self-relay/long-pairing.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { validId } from './device-store.mjs';
+import { digest, matches, secret } from './wire.mjs';
+
+// Operator-owned file, separate from device state. Only hashes are retained here.
+export function longPairing(file) {
+  function read() {
+    if (!file || !fs.existsSync(file)) return [];
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (data.version !== 1 || !Array.isArray(data.invitations) || data.invitations.some(item =>
+      !validId(item.id) || !validId(item.room) || !/^[a-f0-9]{64}$/.test(item.hash) ||
+      !Number.isSafeInteger(item.expires))) throw new Error('Invalid long pairing invitations');
+    return data.invitations;
+  }
+  function write(invitations) {
+    if (!file) throw new Error('Long pairing file is not configured');
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      fs.writeFileSync(temporary, JSON.stringify({ version: 1, invitations }), { mode: 0o600, flag: 'wx' });
+      fs.renameSync(temporary, file);
+    } finally { fs.rmSync(temporary, { force: true }); }
+  }
+  return {
+    list: () => read().map(({ hash, ...item }) => item),
+    find: code => read().find(item => Date.now() < item.expires && matches(code, item.hash)),
+    create(room, expires) {
+      if (!validId(room) || !Number.isSafeInteger(expires) || expires <= Date.now()) throw new Error('Invalid invitation room or expiry');
+      const invitations = read(), code = secret();
+      const item = { id: randomUUID(), room, expires, hash: digest(code) };
+      write([...invitations, item]);
+      return { id: item.id, room, expires, code };
+    },
+    revoke(id) {
+      const invitations = read();
+      if (!invitations.some(item => item.id === id)) throw new Error('Invitation not found');
+      write(invitations.filter(item => item.id !== id));
+    },
+  };
+}