@walkhi/code-relax 0.1.0-beta.1

package/dist/src/app-server-tasks.mjs

@@ -0,0 +1,355 @@
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { AppServerRpcError } from './app-server-client.mjs';
+
+const STORE_SCHEMA_VERSION = 1;
+
+export class AppServerTaskStore {
+  constructor(filePath) {
+    this.filePath = path.resolve(filePath);
+    this.records = new Map();
+    this.loadError = null;
+    this.load();
+  }
+
+  load() {
+    if (!fs.existsSync(this.filePath)) return;
+    try {
+      const value = JSON.parse(fs.readFileSync(this.filePath, 'utf8'));
+      if (value?.schemaVersion !== STORE_SCHEMA_VERSION || !Array.isArray(value.tasks)) {
+        throw new Error('任务归属文件格式不受支持。');
+      }
+      for (const task of value.tasks) {
+        if (!validTaskRecord(task)) continue;
+        this.records.set(task.id, { ...task, transport: 'app-server' });
+      }
+    } catch (error) {
+      this.loadError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+
+  ensureUsable() {
+    if (this.loadError) {
+      throw new Error(`无法读取 app-server 任务归属：${this.loadError.message}`);
+    }
+  }
+
+  has(threadId) {
+    return this.records.has(threadId);
+  }
+
+  get(threadId) {
+    return this.records.get(threadId) || null;
+  }
+
+  list() {
+    return [...this.records.values()].sort((left, right) => Number(right.updatedAt) - Number(left.updatedAt));
+  }
+
+  upsert(task) {
+    this.ensureUsable();
+    if (!validTaskRecord(task)) throw new Error('app-server 任务归属记录无效。');
+    const record = { ...task, transport: 'app-server' };
+    const existing = this.records.get(record.id);
+    if (existing && JSON.stringify(existing) === JSON.stringify(record)) return existing;
+    this.records.set(record.id, record);
+    this.save();
+    return record;
+  }
+
+  remove(threadId) {
+    this.ensureUsable();
+    if (!this.records.delete(threadId)) return false;
+    this.save();
+    return true;
+  }
+
+  save() {
+    this.ensureUsable();
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    const temporaryPath = `${this.filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const payload = `${JSON.stringify({
+      schemaVersion: STORE_SCHEMA_VERSION,
+      tasks: this.list(),
+    }, null, 2)}\n`;
+    try {
+      fs.writeFileSync(temporaryPath, payload, { encoding: 'utf8', flag: 'wx' });
+      fs.renameSync(temporaryPath, this.filePath);
+    } catch (error) {
+      try { fs.unlinkSync(temporaryPath); } catch {}
+      throw error;
+    }
+  }
+}
+
+export class AppServerTaskTransport extends EventEmitter {
+  constructor({ client, store }) {
+    super();
+    this.client = client;
+    this.store = store;
+    this.hydratedGeneration = 0;
+    this.loadedGenerations = new Map();
+    this.client.on('notification', record => this.handleNotification(record));
+    this.client.on('server-request', request => {
+      const threadId = request.params?.threadId || request.params?.conversationId || '';
+      if (threadId && this.owns(threadId)) this.emit('thread-event', { threadId, record: request });
+    });
+  }
+
+  owns(threadId) {
+    return this.store.has(threadId);
+  }
+
+  record(threadId) {
+    const record = this.store.get(threadId);
+    if (!record) throw new Error('该任务不属于独立 app-server 通道。');
+    return record;
+  }
+
+  async createTask({ cwd, projectId, title, input, model, effort }) {
+    if (!path.isAbsolute(cwd)) throw new Error('app-server 任务 cwd 必须是绝对路径。');
+    if (!Array.isArray(input) || !input.length) throw new Error('app-server 任务输入不能为空。');
+    this.store.ensureUsable();
+    await this.client.start();
+    const startParams = { cwd, ephemeral: false, projectId: projectId || null };
+    if (!projectId) startParams.runtimeWorkspaceRoots = [];
+    if (model) startParams.model = model;
+    const started = await this.client.request('thread/start', startParams, 60_000);
+    this.loadedGenerations.set(started.thread.id, this.client.generation);
+    const now = Math.floor(Date.now() / 1000);
+    const record = this.store.upsert({
+      id: started.thread.id,
+      title: title || started.thread.name || '新对话',
+      cwd,
+      projectId: projectId || null,
+      createdAt: Number(started.thread.createdAt) || now,
+      updatedAt: Number(started.thread.updatedAt) || now,
+      status: threadStatus(started.thread.status),
+      activeFlags: threadActiveFlags(started.thread.status),
+      model: model || started.model || started.thread.model || '',
+      effort: effort || started.reasoningEffort || started.thread.reasoningEffort || '',
+      transport: 'app-server',
+    });
+    if (title) try {
+      await this.client.request('thread/name/set', { threadId: record.id, name: title }, 15_000);
+    } catch {
+      // The persisted local title still keeps the task identifiable.
+    }
+
+    const turnParams = { threadId: record.id, input };
+    if (model) turnParams.model = model;
+    if (effort) turnParams.effort = effort;
+    const turn = await this.client.request('turn/start', turnParams, 60_000);
+    this.store.upsert({ ...record, status: 'active', activeFlags: [], updatedAt: Math.floor(Date.now() / 1000) });
+    return { thread: started.thread, turn: turn.turn, record: this.store.get(record.id) };
+  }
+
+  async listTasks() {
+    const records = this.store.list();
+    if (!records.length) return [];
+    await this.client.start();
+    if (this.hydratedGeneration === this.client.generation) {
+      return records.map(record => summaryFromRecord(record));
+    }
+    const results = await Promise.allSettled(records.map(record => this.readTask(record.id, { includeTurns: false })));
+    const summaries = results.map((result, index) => {
+      const record = records[index];
+      if (result.status === 'rejected') return summaryFromRecord(record, 'unknown');
+      const thread = result.value;
+      const updated = this.store.upsert({
+        ...record,
+        title: thread.name || record.title,
+        cwd: thread.cwd || record.cwd,
+        updatedAt: Number(thread.updatedAt) || record.updatedAt,
+        status: threadStatus(thread.status),
+        activeFlags: threadActiveFlags(thread.status),
+        model: thread.model || record.model,
+        effort: thread.reasoningEffort || record.effort,
+      });
+      return summaryFromThread(thread, updated);
+    });
+    if (results.every(result => result.status === 'fulfilled')) {
+      this.hydratedGeneration = this.client.generation;
+    }
+    return summaries;
+  }
+
+  async readTask(threadId, { includeTurns = true, turnLimit = 10 } = {}) {
+    this.record(threadId);
+    await this.client.start();
+    try {
+      const result = await this.readInitializedThread({ threadId, includeTurns });
+      if (includeTurns && Array.isArray(result.thread?.turns)) {
+        result.thread.turns = result.thread.turns.slice(-turnLimit);
+      }
+      return result.thread;
+    } catch (error) {
+      if (!includeTurns || !(error instanceof AppServerRpcError) || error.code !== -32601) throw error;
+      const [threadResult, turnsResult] = await Promise.all([
+        this.readInitializedThread({ threadId, includeTurns: false }),
+        this.client.request('thread/turns/list', {
+          threadId,
+          limit: turnLimit,
+          sortDirection: 'desc',
+        }, 30_000),
+      ]);
+      return { ...threadResult.thread, turns: [...(turnsResult.data || [])].reverse() };
+    }
+  }
+
+  async readInitializedThread(params) {
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await this.client.request('thread/read', params, 30_000);
+      } catch (error) {
+        const initializing = error instanceof AppServerRpcError
+          && error.method === 'thread/read'
+          && /rollout at .* is empty/i.test(error.message);
+        if (!initializing || attempt >= 3) throw error;
+        await delay(100 * (attempt + 1));
+      }
+    }
+  }
+
+  async startTurn(threadId, { input, model, effort }) {
+    const record = this.record(threadId);
+    await this.client.start();
+    await this.ensureResumed(threadId);
+    const params = { threadId, input };
+    if (model) params.model = model;
+    if (effort) params.effort = effort;
+    const result = await this.client.request('turn/start', params, 60_000);
+    this.store.upsert({
+      ...record,
+      status: 'active',
+      activeFlags: [],
+      updatedAt: Math.floor(Date.now() / 1000),
+      model: model || record.model,
+      effort: effort || record.effort,
+    });
+    return result;
+  }
+
+  async adoptTask(thread) {
+    this.store.ensureUsable();
+    await this.client.start();
+    let result;
+    try {
+      result = await this.client.request('thread/resume', { threadId: thread.id }, 60000);
+    } catch (error) {
+      if (error instanceof AppServerRpcError && /already has an active writer/.test(error.message)) {
+        throw new Error('Desktop 仍持有此聊天的写入权限，空闲不代表已释放。当前无法直接接管；此聊天仍由 Desktop 执行。');
+      }
+      throw error;
+    }
+    if (result.thread.id !== thread.id) throw new Error('恢复后的聊天 ID 不一致。');
+    const now = Math.floor(Date.now() / 1000);
+    const record = this.store.upsert({
+      id: thread.id, title: thread.title || result.thread.name || thread.id,
+      cwd: result.thread.cwd, projectId: thread.projectId || null,
+      createdAt: result.thread.createdAt || now, updatedAt: now,
+      status: threadStatus(result.thread.status), activeFlags: threadActiveFlags(result.thread.status),
+      origin: 'desktop', transport: 'app-server',
+    });
+    this.loadedGenerations.set(thread.id, this.client.generation);
+    return summaryFromRecord(record);
+  }
+
+  async ensureResumed(threadId) {
+    if (this.loadedGenerations.get(threadId) === this.client.generation) return;
+    await this.client.request('thread/resume', { threadId }, 60000);
+    this.loadedGenerations.set(threadId, this.client.generation);
+  }
+
+  async steerTurn(threadId, expectedTurnId, input) {
+    this.record(threadId);
+    await this.client.start();
+    return this.client.request('turn/steer', { threadId, expectedTurnId, input }, 60_000);
+  }
+
+  async interruptTurn(threadId, turnId) {
+    this.record(threadId);
+    await this.client.start();
+    return this.client.request('turn/interrupt', { threadId, turnId }, 60_000);
+  }
+
+  async deleteTask(threadId) {
+    this.record(threadId);
+    if (this.record(threadId).origin === 'desktop') throw new Error('接管的 Desktop 历史不允许通过此接口删除。');
+    await this.client.start();
+    await this.client.request('thread/delete', { threadId }, 30_000);
+    this.store.remove(threadId);
+  }
+
+  handleNotification(record) {
+    const threadId = notificationThreadId(record);
+    if (!threadId || !this.owns(threadId)) return;
+    const current = this.store.get(threadId);
+    if (current && ['thread/status/changed', 'turn/started', 'turn/completed', 'thread/name/updated'].includes(record.method)) {
+      const next = { ...current, updatedAt: Math.floor(Date.now() / 1000) };
+      if (record.method === 'thread/status/changed') {
+        next.status = threadStatus(record.params?.status);
+        next.activeFlags = threadActiveFlags(record.params?.status);
+      }
+      if (record.method === 'turn/started') { next.status = 'active'; next.activeFlags = []; }
+      if (record.method === 'turn/completed') { next.status = 'idle'; next.activeFlags = []; }
+      if (record.method === 'thread/name/updated' && record.params?.threadName) next.title = record.params.threadName;
+      this.store.upsert(next);
+    }
+    this.emit('thread-event', { threadId, record });
+  }
+}
+
+export function summaryFromRecord(record, status = record.status || 'unknown') {
+  return {
+    id: record.id,
+    kind: 'codex',
+    hostId: 'app-server',
+    title: record.title,
+    cwd: record.cwd,
+    projectId: record.projectId,
+    updatedAt: record.updatedAt,
+    status,
+    activeFlags: Array.isArray(record.activeFlags) ? record.activeFlags : [],
+    transport: 'app-server',
+  };
+}
+
+function summaryFromThread(thread, record) {
+  return {
+    ...summaryFromRecord(record, threadStatus(thread.status)),
+    activeFlags: threadActiveFlags(thread.status),
+    title: thread.name || record.title || thread.preview || thread.id,
+    cwd: thread.cwd || record.cwd,
+    updatedAt: Number(thread.updatedAt) || record.updatedAt,
+  };
+}
+
+function validTaskRecord(task) {
+  return task && typeof task.id === 'string' && task.id.length > 10
+    && typeof task.title === 'string' && typeof task.cwd === 'string' && path.isAbsolute(task.cwd)
+    && Number.isFinite(Number(task.createdAt)) && Number.isFinite(Number(task.updatedAt));
+}
+
+function delay(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+function threadStatus(value) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') return value.type || value.status || 'unknown';
+  return 'unknown';
+}
+
+function threadActiveFlags(value) {
+  return value && typeof value === 'object' && Array.isArray(value.activeFlags)
+    ? value.activeFlags.filter(flag => typeof flag === 'string')
+    : [];
+}
+
+function notificationThreadId(record) {
+  const params = record?.params || {};
+  return params.threadId || params.conversationId || params.thread?.id || '';
+}

package/dist/src/background-process.mjs

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { startWindowsProcess } from './platform/windows/background-process.mjs';
+
+export const processAlive = pid => {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { if (error.code === 'ESRCH') return false; throw error; }
+};
+export async function startBackground(executable, args, environment, logs = []) {
+  if (process.platform === 'win32') return startWindowsProcess(executable, args, environment, logs);
+  const descriptors = logs.map(file => fs.openSync(file, 'a'));
+  try {
+    const child = spawn(executable, args, { detached: true, env: environment,
+      stdio: ['ignore', descriptors[0] ?? 'ignore', descriptors[1] ?? 'ignore'] });
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+    child.unref(); return child.pid;
+  } finally { descriptors.forEach(fd => fs.closeSync(fd)); }
+}

package/dist/src/debug-ui.mjs

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { controlRequest } from './service-control.mjs';
+
+const script = fileURLToPath(import.meta.url);
+const bridgeRoot = path.resolve(path.dirname(script), '..');
+export const debugRecord = stateRoot => path.join(stateRoot, 'debug-ui-session.json');
+
+function enabledRecord(stateRoot) {
+  const record = readRecord(debugRecord(stateRoot));
+  return record?.enabled === true && Number.isInteger(record.port) && record.port > 0 && record.port < 65536
+    && typeof record.sourceRoot === 'string' ? record : null;
+}
+
+export function debugPort(stateRoot) {
+  return enabledRecord(stateRoot)?.port || null;
+}
+
+export async function activeDebugPort(stateRoot, expectedPort) {
+  const port = debugPort(stateRoot);
+  return expectedPort === undefined || port === expectedPort ? port : null;
+}
+
+function assetsFor(root) {
+  const web = path.join(root, 'web');
+  const packaged = path.join(web, 'resources.json');
+  const manifest = fs.existsSync(packaged)
+    ? JSON.parse(fs.readFileSync(packaged, 'utf8')).map(name => ({ name, source: path.join(web, name) }))
+    : JSON.parse(fs.readFileSync(path.join(root, '../packages/web-resources.json'), 'utf8')).common
+      .map(item => ({ name: item.name, source: path.resolve(root, '..', item.source) }));
+  const assets = new Map(manifest.map(item => ['/' + item.name, item.source]));
+  assets.set('/vendor/markdown-it.umd.min.js', path.join(web, 'vendor/markdown-it.umd.min.js'));
+  return { web, assets };
+}
+
+function send(response, status, mime, bytes) {
+  response.writeHead(status, {
+    ...(mime ? { 'Content-Type': mime } : {}),
+    'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff',
+    'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:",
+  });
+  response.end(bytes);
+}
+
+export function serveDebugResource(request, response, stateRoot, bridgePort) {
+  const record = enabledRecord(stateRoot);
+  if (!record || record.port !== bridgePort) return false;
+  if (request.method !== 'GET' && request.method !== 'HEAD') return false;
+  const url = new URL(request.url, 'http://localhost');
+  if (url.pathname.startsWith('/api/')) return false;
+  try {
+    const { web, assets } = assetsFor(record.sourceRoot);
+    let bytes, mime;
+    if (url.pathname === '/' || url.pathname === '/index.html') {
+      bytes = fs.readFileSync(path.join(web, 'index.html'), 'utf8')
+        .replace('<body class="page-loading">', url.searchParams.get('client') === 'harmony'
+          ? '<body class="page-loading silent-page-loading">' : '<body class="page-loading">')
+        .replace('<script', '<script src="debug-config.js"></script>\n<script');
+      mime = 'text/html; charset=utf-8';
+    } else if (url.pathname === '/debug-config.js') {
+      bytes = 'if(globalThis.codexNative){globalThis.codexLanConfig=JSON.parse(globalThis.codexNative.lanConnection());}else{globalThis.codexLanConfig={address:location.origin};}';
+      mime = 'text/javascript; charset=utf-8';
+    } else if (assets.has(url.pathname)) {
+      bytes = fs.readFileSync(assets.get(url.pathname));
+      mime = url.pathname.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8';
+    } else {
+      send(response, 404); return true;
+    }
+    send(response, 200, mime, request.method === 'HEAD' ? undefined : bytes);
+  } catch {
+    send(response, 500, 'text/plain; charset=utf-8', 'Debug resource unavailable');
+  }
+  return true;
+}
+
+// Small harness for the same request handler used by Bridge.
+export function createDebugServer(root, bridgePort) {
+  const stateRoot = fs.mkdtempSync(path.join(path.dirname(root), '.debug-state-'));
+  writeRecord(debugRecord(stateRoot), { enabled: true, port: bridgePort, sourceRoot: root });
+  const server = http.createServer((request, response) => {
+    if (!serveDebugResource(request, response, stateRoot, bridgePort)) response.writeHead(404).end();
+  });
+  server.once('close', () => fs.rmSync(stateRoot, { recursive: true, force: true }));
+  return server;
+}
+
+async function bridgeSession(stateRoot) {
+  const session = readRecord(path.join(stateRoot, 'bridge-session.json'));
+  if (!session?.port) throw new Error('Bridge 未运行，请先执行 relax start。');
+  try { await controlRequest(session); }
+  catch { throw new Error('Bridge 未运行，请先执行 relax start。'); }
+  return session;
+}
+
+async function stopLegacyWorker(record) {
+  if (!record?.controlPort || !record?.controlSecret || !record?.instanceId) return;
+  try { await controlRequest(record, 'POST'); }
+  catch (error) { if (error.code !== 'ECONNREFUSED') throw error; }
+}
+
+export async function debugUi(command, stateRoot) {
+  const recordPath = debugRecord(stateRoot);
+  const previous = readRecord(recordPath);
+  if (command === 'dev-stop') {
+    await stopLegacyWorker(previous);
+    fs.rmSync(recordPath, { force: true });
+    return { stopped: true, message: 'Bridge 调试页面已关闭；Bridge 继续运行。' };
+  }
+  let session;
+  try { session = await bridgeSession(stateRoot); }
+  catch (error) {
+    if (command === 'dev-status') return { running: false, integrated: true, port: null, sourceRoot: null };
+    throw error;
+  }
+  const current = enabledRecord(stateRoot);
+  if (command === 'dev-status') return {
+    running: Boolean(current && current.port === session.port),
+    integrated: true,
+    port: current?.port === session.port ? session.port : null,
+    sourceRoot: current?.port === session.port ? current.sourceRoot : null,
+  };
+  await stopLegacyWorker(previous);
+  const value = { enabled: true, integrated: true, port: session.port, sourceRoot: bridgeRoot };
+  writeRecord(recordPath, value);
+  return { running: true, ...value };
+}

package/dist/src/desktop-launcher.mjs

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { ManagedAppServer, managedAppServerUrl as sharedUrl, managedPortAvailable as portAvailable } from './managed-app-server.mjs';
+export { portAvailable };
+export async function launchDesktop(mode, { stateRoot, host, environment = process.env, available = portAvailable, wait = delay, timeout = 30000, recoveryId, progress = () => {} }) {
+  if (!['shared', 'ordinary'].includes(mode)) throw new Error('无效的 Desktop 启动模式。');
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const recovery = readRecord(path.join(stateRoot, 'shared-recovery.lock'));
+  if (recovery && recovery.operationId !== recoveryId) throw new Error('完整控制正在启动，请先查看 shared-recovery-status。');
+  const lock = path.join(stateRoot, 'desktop-launch.lock');
+  let descriptor;
+  let managed;
+  try { descriptor = fs.openSync(lock, 'wx'); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error('另一个 Desktop 启动操作正在进行；若上次异常退出，请确认没有启动器运行后移除 desktop-launch.lock。');
+    throw error;
+  }
+  try {
+    const info = await host.inspect();
+    const connected = await host.sharedServiceUrl();
+    if (info.running) {
+      if ((mode === 'shared') === Boolean(connected)) {
+        writeRecord(path.join(stateRoot, 'execution-mode.json'), { mode });
+        return { reused: true, mode };
+      }
+      throw new Error('请先保存任务并完全退出 Codex Desktop，再切换模式；不会自动结束正在运行的任务。');
+    }
+    const childEnv = { ...environment };
+    for (const key of ['CODEX_APP_SERVER_WS_URL', 'CODEX_APP_SERVER_FORCE_CLI', 'CODEX_APP_TOOLS_PIPE_PATH']) delete childEnv[key];
+    if (mode === 'shared') {
+      progress('starting-app-server');
+      managed = new ManagedAppServer({ stateRoot, host, environment, available, wait, timeout });
+      if (!await managed.start()) throw new Error(managed.snapshot().error || '受管 app-server 未就绪。');
+      childEnv.CODEX_APP_SERVER_WS_URL = sharedUrl;
+    }
+    // Ordinary Desktop must not terminate a shared server that may still be executing tasks.
+    progress('starting-desktop');
+    await host.start(info.desktop, [], childEnv, []);
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const ready = mode === 'shared' ? await host.sharedServiceUrl() : (await host.inspect()).running;
+      if (ready) break;
+      if (Date.now() >= deadline) throw new Error('Desktop 尚未按所选模式就绪，未启动 Bridge。请查看 Desktop 窗口后重试。');
+      await wait(500);
+    }
+    writeRecord(path.join(stateRoot, 'execution-mode.json'), { mode });
+    return { reused: false, mode };
+  } finally { managed?.close(); fs.closeSync(descriptor); fs.rmSync(lock, { force: true }); }
+}

package/dist/src/execution-health.mjs

@@ -0,0 +1,26 @@
+// Execution availability is sampled in the background. Health requests may
+// join the current sample so a reconnect cannot cache an initial false state.
+// Only connections are retried, not work.
+export class ExecutionHealth {
+  constructor(read, interval = 3000) { this.read = read; this.interval = interval; this.state = { state: 'checking', ready: false }; }
+  start() { this.stopped = false; void this.tick(); }
+  stop() { this.stopped = true; clearTimeout(this.timer); }
+  refresh() {
+    if (this.work) return this.work;
+    this.work = this.sample().finally(() => { this.work = null; });
+    return this.work;
+  }
+  async sample() {
+    try {
+      const result = await this.read();
+      this.state = result && typeof result === 'object'
+        ? { ...result, ready: Boolean(result.ready), checkedAt: new Date().toISOString() }
+        : { state: result ? 'ready' : 'unavailable', ready: Boolean(result), checkedAt: new Date().toISOString() };
+    } catch (error) { this.state = { state: 'unavailable', ready: false, error: error.message, checkedAt: new Date().toISOString() }; }
+    return this.state;
+  }
+  async tick() {
+    await this.refresh();
+    if (!this.stopped) { this.timer = setTimeout(() => this.tick(), this.interval); this.timer.unref?.(); }
+  }
+}