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

package/README.md

@@ -1,89 +1,95 @@
-# Code Relax 工作站服务
-
-Windows 与 Mac 的统一 npm 分发源码已就绪：主包按操作系统和 CPU 自动安装对应原生组件，普通用户无需自行编译。此结构尚未发布，线上 beta.29 仍为 Windows 包；Mac 原生包需在测试机编译验收。开发者使用 `npm run pack:release -- --output <新的输出目录>` 生成统一主包与当前平台组件包，详见 [npm 分发](../docs/npm-distribution.md)。
-
-桌面服务让 HarmonyOS 客户端控制 Windows 上的Codex 内核。当前要求 Windows x64、Node >=22.12，以及已登录的 Codex Desktop 配套内核或独立 Codex CLI；npm 包不包含 Node，也不修改官方程序文件。
-
-## 安装
-
-公开 beta 已发布到 npm，安装或更新使用：
-
-```powershell
-npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax --foreground-scripts
-```
-
-首次安装前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。更新无需先停止正在运行的桌面服务；安装器会短暂停止、替换并恢复服务。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
-
-`setup` 立即启动桌面服务和固定 45839 Codex 内核，并启用当前用户登录自启；自启不打开 Codex。Codex 内核健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍未接入，安装器会关闭并重新打开 Desktop；安装前应保存工作。普通更新无接入或启动链迁移需求时复用现有内核。
-
-## Codex 内核
-
-```powershell
-relax start           # 启动/复用桌面服务、Codex 内核和已配置的 Code Relax 中继
-relax pair            # 启动/复用服务并打开配对二维码
-relax doctor          # 查看工作站是否正常及需要处理的问题
-relax diag        # 输出供客服或技术人员使用的详细诊断报告
-relax kernel-restart --confirm # 重启内核并启用已选更新，等待新内核就绪
-```
-
-Codex 内核由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和桌面服务均可连接；它只监听回环地址。桌面服务独立报告内核健康、Desktop 接入和手机可写状态；Desktop 退出后，手机仍可操作内核中的任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
-
-发现待启用内核更新时，手机“重启并更新”和 `relax kernel-restart --confirm` 复用同一受控停启流程：先验证候选，再停止旧内核，确认新内核协议就绪后恢复 Desktop，并按清单清理不再运行的旧版保留目录。手机工作站详情可确认让 Desktop 接入Codex 内核，独立进程逐步执行并保留桌面服务/中继连接，见[启用流程](../docs/shared-recovery.md)。本机恢复命令为 `relax desktop-recover --confirm`，查看恢复记录用 `relax diag`。桌面服务状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。
-
-Codex 内核通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。手机的项目、任务列表和新建任务均使用Codex 内核，不依赖 Desktop 工具管道；项目和任务 ID 保持原生值。
-
-Codex 内核未就绪时，手机停留在连接界面并显示“Codex 内核未就绪”；桌面服务保留健康和恢复接口，聊天请求返回错误。
-
-## Dots 委派任务
-
-`dots-tasks --json` 只读查询当前 ChatGPT 账号在托管 app-server 中的 Dots 委派任务及最近轮次状态。本机内核须已启动并登录 ChatGPT，凭据只用于工作站到官方主机的连接。任务合入 LAN 和 Code Relax 中继列表，按执行目录归入项目，标题旁显示云朵，委派正文与发送者分开显示。委派任务已接入发送/引导、停止、审批和实时事件；点点主聊天已接官方消息房间，保留独立正文与执行任务边界。当前实现与手机验证范围见 [Dots 接入](../docs/dots-integration.md)和[消息房间修复](../docs/dots-messaging-repair.md)。
-
-源码运行：
-
-```powershell
-node bridge/bin/codex-remote.mjs dots-tasks --json
-```
-
-构建产物使用 `node bridge/dist/bin/codex-remote.mjs dots-tasks --json`；已更新的本机全局 CLI 使用 `relax dots-tasks --json`，公共 npm 包尚未同步这项功能。任务目录归属与执行环境不同，本次托管任务携带 Windows 工作目录；协议与实读证据见 [Dots 接入](../docs/dots-integration.md)。
-
-## Code Relax 中继
-
-私有中继仍需要本机桌面服务：
-
-```powershell
-relax start --json
-relax pair --json
-```
-
-`start` 启动内核和桌面服务，并在桌面服务内恢复已配置中继。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。桌面服务把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。
-
-桌面服务的局域网端口仅提供鉴权 WebSocket，普通 HTTP 请求返回 404；手机聊天页面随 HAP 安装。
-
-## 更新与卸载
-
-更新固定服务：
-
-```powershell
-npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax --foreground-scripts
-```
-
-`setup` 先暂存并校验新版本，再短暂停止桌面服务/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前停止服务。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
-
-卸载：
-
-```powershell
-relax uninstall
-npm uninstall -g @walkhi/code-relax
-```
-
-`uninstall` 停止桌面服务后先核对并清理 Code Relax 所有的当前用户 `CODEX_APP_SERVER_WS_URL`；用户后来修改或不归属 Code Relax 的值会保留。随后删除固定程序和本包管理且未修改的 Skill；保留其他配置、Token、日志、长期设备凭据、附件和自定义 Skill。它不卸载 Node、Codex Desktop，也不强制结束完整控制的执行进程。
-
-## 发布边界
-
-registry 测试包使用 `@walkhi/code-relax@beta`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。安装摘要通过 `--foreground-scripts` 显示，首次安装或启动链迁移时干净重启 Desktop，分别报告已安装与实际运行版本；登录启动使用当前用户任务计划。通信协议仍为 7。详细规则见 [npm 分发](../docs/npm-distribution.md)。
-
-### CLI 输出（2026-10-15）
-
-安装和启动成功后只显示结果与 `relax pair` 入口；配对成功显示二维码文件。`relax doctor` 报告工作站健康及实际问题，独立的 `relax diag` 默认用可读文本输出系统、Node、服务进程、逐项检查和 Desktop 接入排障记录；常规命令不再提供 `--detail`；`--json` 保留给安装器等现有程序调用。服务未运行或内核未就绪判为失败；未连接局域网只提示，不阻断中继使用。手机连通性不作为 CLI 检查项，doctor 不创建配对邀请。
-
-`doctor` 默认逐项说明安装文件、工作站服务和 Codex 内核的当前状态，问题集中给出处理方法。上次 Desktop 接入记录仅由 `diag` 读取，并明确标注排障用途；常规 `doctor` 不读取该记录，不参与当前健康判定，不拼接互相矛盾的阶段消息与最终错误。
+# Code Relax 工作站服务
+
+Windows 与 Mac 的统一 npm 平台分发已随 beta.30 发布，普通用户无需编译原生组件。Linux x64/arm64 平台适配已加入源码，尚未随新版本发布；Ubuntu x64 的官方内核启动、依赖加载和构建已验证，真实桌面账号、钥匙环与手机收发待验收。详见 [跨平台工作站](../docs/workstation-platforms.md) 与 [npm 分发](../docs/npm-distribution.md)。
+
+工作站服务让 Android/HarmonyOS 客户端使用同一个 Codex 内核。要求 Node >=22.12；Linux 使用官方 ChatGPT 桌面版内置内核，不以独立 CLI 代替点点能力。npm 包不包含 Node 或官方桌面版，也不修改官方程序文件。
+
+## 安装
+
+公开 beta 已发布到 npm，安装或更新使用：
+
+```powershell
+npm i -g @walkhi/code-relax@latest --allow-scripts=@walkhi/code-relax --foreground-scripts
+```
+
+以下目录与环境变量配置说明适用于 Windows；Mac/Linux 见下方跨平台入口。首次安装前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。更新无需先停止正在运行的桌面服务；安装器会短暂停止、替换并恢复服务。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
+
+`setup` 立即启动桌面服务和固定 45839 Codex 内核，并启用当前用户登录自启；自启不打开 Codex。Codex 内核健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍未接入，安装器会关闭并重新打开 Desktop；安装前应保存工作。普通更新无接入或启动链迁移需求时复用现有内核。
+
+## Linux 源码测试
+
+公开 beta.30 尚不含 Linux，不能用上面的 registry 命令取得本轮修改。Linux 源码测试需要官方 ChatGPT 桌面版、Node >=22.12、`secret-tool` 和已解锁的 Secret Service；Ubuntu/Debian 的工具包为 `libsecret-tools`。以普通用户在图形桌面会话中安装，不使用 sudo 运行 npm/relax。
+
+数据与服务位于 XDG Data 下的 `CodexRemote`，状态位于 XDG State 下；登录启动使用 `~/.config/autostart/cn.walkhi.code-relax.desktop`（遵循 XDG_CONFIG_HOME）。只为启动的 Desktop 实例设置托管地址；普通应用菜单启动不会自动继承，需使用 `relax desktop-recover --confirm` 接入。目录、自定义 CODEX_HOME、运行时更新与验收边界见 [Linux 实现](../docs/workstation-platforms.md#linux-工作站2026-10-15)。Mac 的钥匙串/LaunchAgent 说明也在该文档。
+
+## Codex 内核
+
+```powershell
+relax start           # 启动/复用桌面服务、Codex 内核和已配置的 Code Relax 中继
+relax pair            # 启动/复用服务并打开配对二维码
+relax doctor          # 查看工作站是否正常及需要处理的问题
+relax diag        # 输出供客服或技术人员使用的详细诊断报告
+relax kernel-restart --confirm # 重启内核并启用已选更新，等待新内核就绪
+```
+
+Codex 内核由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和桌面服务均可连接；它只监听回环地址。桌面服务独立报告内核健康、Desktop 接入和手机可写状态；Desktop 退出后，手机仍可操作内核中的任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
+
+发现待启用内核更新时，手机“重启并更新”和 `relax kernel-restart --confirm` 复用同一受控停启流程：先验证候选，再停止旧内核，确认新内核协议就绪后恢复 Desktop，并按清单清理不再运行的旧版保留目录。手机工作站详情可确认让 Desktop 接入Codex 内核，独立进程逐步执行并保留桌面服务/中继连接，见[启用流程](../docs/shared-recovery.md)。本机恢复命令为 `relax desktop-recover --confirm`，查看恢复记录用 `relax diag`。桌面服务状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。
+
+Codex 内核通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。手机的项目、任务列表和新建任务均使用Codex 内核，不依赖 Desktop 工具管道；项目和任务 ID 保持原生值。
+
+Codex 内核未就绪时，手机停留在连接界面并显示“Codex 内核未就绪”；桌面服务保留健康和恢复接口，聊天请求返回错误。
+
+## Dots 委派任务
+
+`dots-tasks --json` 只读查询当前 ChatGPT 账号在托管 app-server 中的 Dots 委派任务及最近轮次状态。本机内核须已启动并登录 ChatGPT，凭据只用于工作站到官方主机的连接。任务合入 LAN 和 Code Relax 中继列表，按执行目录归入项目，标题旁显示云朵，委派正文与发送者分开显示。委派任务已接入发送/引导、停止、审批和实时事件；点点主聊天已接官方消息房间，保留独立正文与执行任务边界。当前实现与手机验证范围见 [Dots 接入](../docs/dots-integration.md)和[消息房间修复](../docs/dots-messaging-repair.md)。
+
+源码运行：
+
+```powershell
+node bridge/bin/codex-remote.mjs dots-tasks --json
+```
+
+构建产物使用 `node bridge/dist/bin/codex-remote.mjs dots-tasks --json`；已更新的本机全局 CLI 使用 `relax dots-tasks --json`，公共 npm 包尚未同步这项功能。任务目录归属与执行环境不同，本次托管任务携带 Windows 工作目录；协议与实读证据见 [Dots 接入](../docs/dots-integration.md)。
+
+## Code Relax 中继
+
+私有中继仍需要本机桌面服务：
+
+```powershell
+relax start --json
+relax pair --json
+```
+
+`start` 启动内核和桌面服务，并在桌面服务内恢复已配置中继。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。桌面服务把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。
+
+桌面服务的局域网端口仅提供鉴权 WebSocket，普通 HTTP 请求返回 404；手机聊天页面随 HAP 安装。
+
+## 更新与卸载
+
+更新固定服务：
+
+```powershell
+npm i -g @walkhi/code-relax@latest --allow-scripts=@walkhi/code-relax --foreground-scripts
+```
+
+`setup` 先暂存并校验新版本，再短暂停止桌面服务/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前停止服务。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
+
+卸载：
+
+```powershell
+relax uninstall
+npm uninstall -g @walkhi/code-relax
+```
+
+`uninstall` 停止桌面服务后先核对并清理 Code Relax 所有的当前用户 `CODEX_APP_SERVER_WS_URL`；用户后来修改或不归属 Code Relax 的值会保留。随后删除固定程序和本包管理且未修改的 Skill；保留其他配置、Token、日志、长期设备凭据、附件和自定义 Skill。它不卸载 Node、Codex Desktop，也不强制结束完整控制的执行进程。
+
+## 发布边界
+
+registry 默认安装使用 `@walkhi/code-relax@latest`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。安装摘要通过 `--foreground-scripts` 显示，首次安装或启动链迁移时干净重启 Desktop，分别报告已安装与实际运行版本；登录启动使用当前用户任务计划。通信协议仍为 7。详细规则见 [npm 分发](../docs/npm-distribution.md)。
+
+### CLI 输出（2026-10-15）
+
+安装和启动成功后只显示结果与 `relax pair` 入口；配对成功显示二维码文件。`relax doctor` 报告工作站健康及实际问题，独立的 `relax diag` 默认用可读文本输出系统、Node、服务进程、逐项检查和 Desktop 接入排障记录；常规命令不再提供 `--detail`；`--json` 保留给安装器等现有程序调用。服务未运行或内核未就绪判为失败；未连接局域网只提示，不阻断中继使用。手机连通性不作为 CLI 检查项，doctor 不创建配对邀请。
+
+`doctor` 默认逐项说明安装文件、工作站服务和 Codex 内核的当前状态，问题集中给出处理方法。上次 Desktop 接入记录仅由 `diag` 读取，并明确标注排障用途；常规 `doctor` 不读取该记录，不参与当前健康判定，不拼接互相矛盾的阶段消息与最终错误。

package/dist/bin/cleanup-accounts.mjs

@@ -1,63 +1,63 @@
-#!/usr/bin/env node
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { createHmac } from 'node:crypto';
-import mysql from 'mysql2/promise';
-import { relayDiagnostics } from '../src/self-relay/diagnostics.mjs';
-import { purgeCancelledAccounts } from '../src/self-relay/account-cleanup.mjs';
-
-const config = JSON.parse(await fs.readFile('/etc/codex-relay/mysql.json', 'utf8'));
-const account = JSON.parse(await fs.readFile('/etc/codex-relay/account.json', 'utf8'));
-if (typeof account.codePepper !== 'string' || account.codePepper.length < 32) throw new Error('Invalid account cleanup configuration');
-const pool = mysql.createPool({ ...config, connectionLimit: 1, dateStrings: true, timezone: 'Z' });
-const startedAt = Date.now();
-let stage = 'accounts';
-const diagnostics = relayDiagnostics(pool, () => console.error('Account cleanup diagnostic write failed'));
-const record = (event, detail) => diagnostics.record('account-cleanup', event, detail);
-let purged = 0;
-try {
-  await record('started', 'scheduled');
-  purged = await purgeCancelledAccounts(pool, value => createHmac('sha256', account.codePepper).update(value).digest('hex'));
-  await record('accounts-cleared', `count=${purged}`);
-  stage = 'backups';
-
-// Only deployment SQL snapshots; never follow symlinks or remove release directories.
-const root = '/opt/codex-relay/releases';
-if (await fs.realpath(root) !== root) throw new Error('Unexpected backup root');
-const files = [];
-for (const entry of await fs.readdir(root, { withFileTypes: true })) {
-  if (entry.isDirectory() && /^deploy-\d{8}T\d{6}Z$/.test(entry.name)) {
-    files.push(path.join(root, entry.name, 'database.sql'));
-  }
-}
-// Pre-deployment snapshots observed on this installation, before the release tool existed.
-for (const directory of ['before-email-20260925', 'before-usage-20260925']) {
-  files.push(path.join(root, directory, 'code_relax.sql'));
-}
-let backups = 0;
-for (const file of files) {
-  let stat;
-  try { stat = await fs.lstat(file); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
-  if (!stat.isFile() || stat.isSymbolicLink() || Date.now() - stat.mtimeMs < 86400000) continue;
-  if (await fs.realpath(file) !== file) throw new Error('Unexpected backup path');
-  await fs.unlink(file); backups++;
-}
-await record('backups-cleared', `count=${backups}`);
-stage = 'recovery-logs';
-// Rotate even on a quiet server so expired binlogs are actually purged.
-const maintenance = await mysql.createConnection({ user: 'root', socketPath: '/var/run/mysqld/mysqld.sock' });
-try {
-  const [settings] = await maintenance.query('SELECT @@GLOBAL.binlog_expire_logs_seconds AS seconds, @@GLOBAL.binlog_expire_logs_auto_purge AS autoPurge');
-  if (Number(settings[0].seconds) <= 0 || Number(settings[0].seconds) > 259200 || Number(settings[0].autoPurge) !== 1) {
-    throw new Error('MySQL recovery-log retention exceeds account cleanup policy');
-  }
-  await maintenance.query('FLUSH BINARY LOGS');
-} finally { await maintenance.end(); }
-await record('completed', `users=${purged};backups=${backups};ms=${Date.now() - startedAt}`);
-console.log(JSON.stringify({ event: 'account-cleanup', purged, expiredBackups: backups, recoveryLogsRotated: true }));
-} catch (error) {
-  // Codes and stage only: SQL errors may contain email addresses or credentials.
-  const code = String(error.code || 'operation-failed').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 32);
-  await record('failed', `stage=${stage};code=${code}`);
-  throw error;
-} finally { await pool.end(); }
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHmac } from 'node:crypto';
+import mysql from 'mysql2/promise';
+import { relayDiagnostics } from '../src/self-relay/diagnostics.mjs';
+import { purgeCancelledAccounts } from '../src/self-relay/account-cleanup.mjs';
+
+const config = JSON.parse(await fs.readFile('/etc/codex-relay/mysql.json', 'utf8'));
+const account = JSON.parse(await fs.readFile('/etc/codex-relay/account.json', 'utf8'));
+if (typeof account.codePepper !== 'string' || account.codePepper.length < 32) throw new Error('Invalid account cleanup configuration');
+const pool = mysql.createPool({ ...config, connectionLimit: 1, dateStrings: true, timezone: 'Z' });
+const startedAt = Date.now();
+let stage = 'accounts';
+const diagnostics = relayDiagnostics(pool, () => console.error('Account cleanup diagnostic write failed'));
+const record = (event, detail) => diagnostics.record('account-cleanup', event, detail);
+let purged = 0;
+try {
+  await record('started', 'scheduled');
+  purged = await purgeCancelledAccounts(pool, value => createHmac('sha256', account.codePepper).update(value).digest('hex'));
+  await record('accounts-cleared', `count=${purged}`);
+  stage = 'backups';
+
+// Only deployment SQL snapshots; never follow symlinks or remove release directories.
+const root = '/opt/codex-relay/releases';
+if (await fs.realpath(root) !== root) throw new Error('Unexpected backup root');
+const files = [];
+for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+  if (entry.isDirectory() && /^deploy-\d{8}T\d{6}Z$/.test(entry.name)) {
+    files.push(path.join(root, entry.name, 'database.sql'));
+  }
+}
+// Pre-deployment snapshots observed on this installation, before the release tool existed.
+for (const directory of ['before-email-20260925', 'before-usage-20260925']) {
+  files.push(path.join(root, directory, 'code_relax.sql'));
+}
+let backups = 0;
+for (const file of files) {
+  let stat;
+  try { stat = await fs.lstat(file); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink() || Date.now() - stat.mtimeMs < 86400000) continue;
+  if (await fs.realpath(file) !== file) throw new Error('Unexpected backup path');
+  await fs.unlink(file); backups++;
+}
+await record('backups-cleared', `count=${backups}`);
+stage = 'recovery-logs';
+// Rotate even on a quiet server so expired binlogs are actually purged.
+const maintenance = await mysql.createConnection({ user: 'root', socketPath: '/var/run/mysqld/mysqld.sock' });
+try {
+  const [settings] = await maintenance.query('SELECT @@GLOBAL.binlog_expire_logs_seconds AS seconds, @@GLOBAL.binlog_expire_logs_auto_purge AS autoPurge');
+  if (Number(settings[0].seconds) <= 0 || Number(settings[0].seconds) > 259200 || Number(settings[0].autoPurge) !== 1) {
+    throw new Error('MySQL recovery-log retention exceeds account cleanup policy');
+  }
+  await maintenance.query('FLUSH BINARY LOGS');
+} finally { await maintenance.end(); }
+await record('completed', `users=${purged};backups=${backups};ms=${Date.now() - startedAt}`);
+console.log(JSON.stringify({ event: 'account-cleanup', purged, expiredBackups: backups, recoveryLogsRotated: true }));
+} catch (error) {
+  // Codes and stage only: SQL errors may contain email addresses or credentials.
+  const code = String(error.code || 'operation-failed').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 32);
+  await record('failed', `stage=${stage};code=${code}`);
+  throw error;
+} finally { await pool.end(); }