fix(portability): a bare $var before a non-ASCII byte breaks the installer on macOS's bash 3.2

[JasonJarvan]

症状:安装器在 macOS 上装不上

macOS 自带 /bin/bash 是 3.2.57(许可证原因,Apple 不升级)。bash 3.2 解析变量名时不认多字节字符:

name=ok; set -u; echo "x $name：y"     # 全角冒号 ：= U+FF1A = EF BC 9A
# bash 3.2 → line 3: name<EF>: unbound variable    ← 0xEF 被并入了变量名
# bash 5   → x ok：y

set -u 之下是硬失败。实测后果:adopt.sh 在 macOS 上 rc=1 ⇒ adopter 装不上这套 harness。 仓内 12 个测试在 setUpClass 就炸。

根因不是缺 bash4 特性 —— declare -A / mapfile / ${x,,} 实测命中均为 0。所以修法是加花括号,不是加版本门:版本门只会把「装不上」换成「明确拒绝装」,而这条其实能在 3.2 上正常工作。

它伪装成了别的东西

测试用 subprocess(..., text=True) 去解码 bash 吐的那个坏字节,于是失败呈现为 UnicodeDecodeError —— 看起来像测试框架的编码问题,而真实缺陷是安装器炸了。这是 guide 里「取证命令的三种伪装」中第三种(数据在通往解析器的路上被改写)的又一个实例。

回归门 tests/test_shell_multibyte_portability.py

• 形态式判据,不枚举变量名也不枚举字符:凡 $identifier 紧跟一个非 ASCII 字节即拒。
• 开火构造 + 反向构造(加了花括号就不该命中、$var 后跟 ASCII 不该命中)。
• 因果层:在 bash 3.x 上实证「裸形式 unbound variable、花括号形式 rc=0」。bash≥4 上跳过并说明理由 —— 前提在那里本就不成立,强行断言只会得到一条假绿。
• 覆盖自检:必须扫到 adopt.sh 与 harness_worktree_link.sh,否则「一个文件都没扫到」会假绿。

为什么必须由门守:写中文输出的仓,每写一行 echo "…$var:…" 都在重新引入它,而 CI 若跑在 bash 5 上永远不会报。正确写法与错误写法一样省事,错误只在别人机器上炸。

门一上线就抓到我漏的 2 处

我最初统计用手列 glob(overlay/** scripts/**)得出 13 处,漏了 skills/;门走整棵树,得出 15 处(adopt.sh 8 / harness_worktree_link.sh 5 / skills/arborist-sync/sync.sh 2)。

⇒ 又一次「枚举式弱于形态式」,而这次弱的是我的统计口径。

读数

• 红 8F + 12E → 6F + 0E。12 个 error 全消。
• 另 2 个 failure 是变异层护栏(test_the_unmutated_tree_is_green_for_the_same_tests / test_removing_each_gate_turns_one_of_its_tests_red),基线转绿后自动通过 —— 护栏双向都在正常工作。
• 全量 676 通过(含本 PR 新增 7 条)。
• 剩 6 处红是 macOS /var → /private/var 符号链接族(测试夹具拿未归一化路径比产品的 realpath 归一化值),另账,不在本 PR 范围。

🤖 Generated with Claude Code