fix(trust-local): stop by unloading the job, not by signalling it

[damonleelcx]

配套 PR：aikeylabs/ai-degrade-detector（plist 注释，说明为什么 KeepAlive 必须保持 <true/>）· aikeylabs/workflow（bugfix 文档）

问题

$ aikey service stop trust-local
aikey.trust-local: stop succeeded          ← 谎报

实测：launchd 约 10s 后拉起新 pid，t+20s 又在 8801 上服务了，launchd 自己的 runs 计数 40 → 41。

只影响 macOS。 Linux 不受影响（systemctl --user stop 同步，systemd 不重启被显式停掉的 unit）；Windows 的 windows_stop() 本来就有 survivor 校验。macOS 是唯一「stop 是谎话」的平台。

根因

两个各自都合理的决定凑在一起：

1. LaunchAgent 是无条件 KeepAlive=<true/> —— 崩溃自愈，私有化部署需要。
2. macOS stop 是 launchctl kill TERM —— 只发信号，不卸载 job。

launchd 尽职地把它拉回来，而 stop() 直接返回，不做任何校验。

为什么活这么久没被发现

trust-local 是 PyInstaller onefile，冷启动 ~20s 解包才 bind 8801。重启后那 20s 里服务确实不可达，所以任何短于启动耗时的 healthz 检查都会看到一次"干净的 stop"。诊断时我第一次用 15s 窗口测，6 行 listener=none，差点结案 —— 拆穿它的是 runs 计数器。

修法

停止语义由卸载 job 表达，而不是给进程发信号：

• stop → launchctl bootout gui/<uid>/<label>，launchd 没东西可重启。「服务未加载」视为成功（stop 幂等，调用方要的后置条件已成立）。
• start → 先 bootstrap（"已加载"错误忽略）再 kickstart -k，因为 stop 现在会把 job 移出 domain。
• plist 不改。无条件 KeepAlive 对「不是用户主动停」的每一种情况都恰好是对的 → 已安装机器无需 plist 迁移，修复面收敛在一个 CLI 二进制里。

被否掉的方案（记录下来免得有人再试）

把 plist 改成 KeepAlive={SuccessfulExit:false}（对齐 Linux 的 Restart=on-failure）不成立：改完之后 SIGTERM 照样触发重启（runs 1 → 2 → 3）。

原因：launchd 跟踪的是 PyInstaller bootloader 父进程，父进程收到信号是被信号终止而不是 exit 0 —— 在 launchd 眼里同样是 unsuccessful exit。这个策略在信号式 stop 面前根本区分不了「用户停的」和「它崩了」，采纳它只会白白削弱干净退出场景的自愈。理由已写进 ai-degrade-detector 的 plist 注释，防止后人"顺手改回去"。

(d) stop 后校验

对齐 windows_stop() 已有的做法。关键点：轮询 launchd 的 job 状态，不探 /healthz —— healthz 分不清「已停止」和「正在重启」，这正是 15s 窗口报假绿的原因。12s 预算盖过实测 ~10s 的 launchd 重启节流下限，不需要盖过 20s 启动耗时，因为 job 状态在 spawn 瞬间就翻转。

验收（plist 保持原样未改）

测试	结果
A. stop 后保持停止	30s 内 job 未加载、无 pid、无监听 ✅
B. bootout 之后还能 start	bootstrap→kickstart 生效，27s 后 healthz=200 ✅
C. 崩溃自愈未被破坏	kill -9 子进程 → launchd 重新拉起（68809→69013），t+25s 恢复，healthz=200 ✅

新二进制打在旧行为上会如实报错并 exit 1，不再谎报成功。

围栏：parse_launchd_pid 单测，样本取自真机 launchctl print 输出（cargo test --lib trust_local_service，5 passed）。危险方向是运行中的 job 解析不出 pid —— 那会让 stop 直接退回谎报成功，所以单测重点锁这一侧，外加 original pid = 999 这类邻近键不得被误判。

说明

• 本 PR 只有一个文件。从 origin/develop-v1.0.5 切出（本地 checkout 停在 fix/dgcheck-canonical-host-in-selfdesc，故走独立 worktree，未触碰）。
• 本 bug 是排查 Trust Check 页面无限 loading 时顺带挖出的，与那个 bug 没有因果关系：重启窗口里端口是关闭的，客户端会收到明确拒绝并正确显示离线横幅。

🤖 Generated with Claude Code