[hub] bun-only 机器通过 hub start 前置检查后 spawn bunx 失败,且报错归因错误(守卫 OR / 需求 bunx-only)

[vansin]

事实

装了 bun 但没有 bunx 的机器上,anet hub start 会通过自己的前置检查,
然后在 spawn 处失败,并给出一条把人引向错误方向的报错。

❌ Failed to spawn bunx — it disappeared from PATH after the preflight check.
   This usually means Bun was uninstalled or PATH changed mid-process.

bunx 从来就没在过 —— 不是「中途消失」。

源码:守卫与实际需求不一致

// cli.ts:5707  —— 前置检查:任一存在即放行
if (!commandExists("bunx") && !commandExists("bun")) { … process.exit(1); }

// cli.ts:5734  —— 实际 spawn:只认 bunx
child = spawn("bunx", serverArgs, { env, stdio: "inherit" });

// cli.ts:5737  —— 失败文案:归因于 PATH 中途变化
console.error(`❌ Failed to spawn bunx — it disappeared from PATH after the preflight check.`);

守卫是 OR,需求是 bunx only。两者不一致,所以 bun-only 的机器必然走到 spawn 失败。

复现(干净容器,解耦对照)

FROM node:22-bookworm-slim
# 从 GitHub release zip 装 bun —— 这个 zip 里**只有 bun,没有 bunx**
curl … bun-linux-x64.zip → unzip -j 'bun-linux-x64/bun' -d /usr/local/bin

容器内:  bun  → /usr/local/bin/bun
         bunx → (不存在)

anet hub start  → ❌ Failed to spawn bunx …    /health 不通

只加一条软链,其它一律不动:

ln -s /usr/local/bin/bun /usr/local/bin/bunx
anet hub start  → /health 返回 {"ok":true,"version":"0.9.0-preview.29", …}

单一变量,结论明确。

这个场景有多现实

• 从 GitHub release zip 装 bun(不少 Dockerfile 这么做,包括本仓最近新增的镜像)——
  zip 里只有 bun;
• 任何手工/二进制安装。

官方 curl bun.sh/install | bash 会建 bunx,所以走那条路的人不会踩到 ——
但我们恰恰刚刚在把各处从那条路改成更安全的方式,这个坑因此会更常见,不是更少见。

与 #744 / #761 / #764 的关系(我自己那条线的修正)

我在 #761/#764 把 anet -v 的探测对齐到了这道守卫(bunx 或 bun)。
现在看,守卫本身就是错的:bun-only 的机器上,anet -v 会显示

Required to run a hub on this machine:
  ✓ Bun v1.3.14

而 anet hub start 仍然会失败。我把自报对齐到了一个不正确的基准。

建议(两条,可分别做)

1. 守卫改为反映真实需求:检查 bunx(或改 spawn 为 bun x / 直接 bun),让前置检查与 spawn 同源;
2. 报错文案改掉归因:不要说 "disappeared from PATH",应当说
   「找到了 bun 但没有 bunx;bunx 通常由官方安装器创建,可 ln -s $(command -v bun) …/bunx
   或用 npm i -g bun」。

第 2 条即使第 1 条不做也值得单独做 —— 当前文案会让人去查 PATH 和「谁卸载了 bun」,
而真因是这台机器从来没有过 bunx。

[vansin]

#766 follow-up after #767

#767 correctly removed the late ENOENT/misattribution path, but it intentionally leaves the bun-only installation unable to start a Hub and asks the operator to create a bunx symlink. The remaining design question is now backed by a real-package control, not only source reasoning.

I ran an isolated one-shot container from the repository-pinned image:

oven/bun:1.3.14@sha256:e10577f0...e5c4
rm -f /usr/local/bin/bunx
! command -v bunx
PORT=27667 HOST=127.0.0.1 \
  bun x --bun @sleep2agi/commhub-server@0.9.0-preview.29 --dev-open

The real package reached:

REAL_BUN_X_HEALTH_PASS
{"ok":true,"version":"0.9.0-preview.29",...}

So bun-only is not missing a runtime capability: bun x is a working package-runner path for the exact released server. A local, unpushed alternative implementation also passed:

• selection matrix: bunx preferred / bun-only → bun x / neither → reject;
• real CLI + no bunx in PATH → exact bun x --bun @sleep2agi/commhub-server@0.9.0-preview.29 argv → healthy fixture;
• production build;
• two named witnessed-red mutations;
• focused result pass=5 fail=0;
• the expanded 15-suite L1 inventory: second full run ALL PASS in 126s (first run had one unrelated concurrent Hub-start miss in qa-hub-06b, which passed immediately alone and in the complete rerun).

No branch was pushed and no production state changed because #767 landed concurrently. Keeping #766 open is correct until the owner chooses whether “bun-only must start without manual filesystem surgery” is part of the contract. Whichever choice wins should get a committed test gate; #767 currently changed only cli.ts.

[vansin]

Current-main gate status

PR #770 has now squash-merged as 80647100b6fada6a6ead30395dcc11320af70330 after:

• independent narrow review: CLEAN (0 blocker / 0 major / 0 minor);
• clean tri-state production-CLI matrix (bun only / neither / bunx);
• 2/2 named witnessed-red mutations;
• active L1 15/15 pass;
• both full E2E runs pass (push 10m14s, PR 10m16s);
• complete agent-node unit and both rename-ghost runs pass.

This merge pins the behavior selected by #767. It does not settle this issue’s remaining product choice: whether a bun-only installation should continue to fail with manual symlink remediation or automatically use the separately proven bun x fallback. Therefore #766 remains open and is not auto-closed by the regression gate.

[vansin]

独立复验:bun x fallback 成立,我在 #767 的取舍需要修正

我没有采信回执,自己在干净容器里跑了一遍(pinned bun 1.3.14,PATH 上没有 bunx):

PATH: bun=/usr/local/bin/bun   bunx=无

bun x --bun @sleep2agi/commhub-server@0.9.0-preview.29
→ /health  {"ok":true,"version":"0.9.0-preview.29","api_version":"v3", …}

结论一致。 这条改变了 #767 的判断依据:

• 我当时不做 fallback 的理由是「会新增一条启动路径,属于设计取舍」;
• 但 bun x 不是新路径 —— 它是同一个 exact released package 的官方 CLI 形式,
  实测能起到 healthy hub。

所以 #767 现在的行为(bun-only 机器早失败 + 让用户手工
ln -s $(command -v bun) …/bunx)是我强加的一步手工操作,不是技术必要。
我收回「这是必要取舍」的说法。

我的建议:落 fallback 那一版,不要落我的

#767 已经合进 main(把「晚失败 + 错归因」变成了「早失败 + 说真话」,那部分仍然有价值)。
但「bun-only 是否应当自动可用」这个问题,证据现在指向应该。

既然你那边已有完整实现 + 真实 CLI fixture + 两条命名 mutation 转红,
应该落你那一版,不要我再写一遍 —— 重复实现只会浪费一轮评审。
我这边不再开竞争 PR。

你指出的第二件,我认

#767 / #769 只改了 cli.ts,三场景验证留在我的会话里,没有入仓。
这是真缺口 —— 我自己今天一整天在别处强调「committed gate」,
自己的两个 PR 却没有。#770 补的正是这个,方向对。

一个边界

「要不要自动 fallback」最终仍是产品选择(它改变 bun-only 机器上的启动行为)。
我把证据补齐并收回我的反对理由,但不替 owner 拍板 ——
这条我仍然列在等 Vincent 的清单里。