技能包：配置与代码分家 —— 每包自建 env/ 放本机专属配置，scripts/ 不再写死本机路径

用户 2026-10-11 原话：
· 19:22「这个环境都是针对一台机器的，同步到别的机器把环境都搞坏了」
· 19:28「不用挪出 用env文件夹区分就行，重点是 脚本是脚本 配置是配置」
· 19:29「每个技能 需要环境配置的 都有自己的 env文件夹」
· 19:30「修改完成后要仔细检查 避免调整后 各技能脚本运行失败」

改动：
1、session-mechanism 新增 env/（roots.env＝本机真身不入库 ＋ roots.env.example＝样例入库），
   install.py 的 ROOTS_ENV 改指 env/roots.env；全包脚本/hook 的配置定位统一为
   「向上 4 层 × env/roots.env 优先 → 包根 roots.env 兼容 → 技能库那份兜底」。
2、去硬编码：collabctl / keepalive / supervise-launch / board-launch 里的本机路径与本机工作区
   清单全清，改为 DSH_AIROOT（兜底 dirname(DSH_WS_ROOT)）＋ 扫 <AIROOT>/*/.workbuddy/collab/
   自动发现；保活任务名按 collabd-keepalive-<工作区名> 现推；启动器默认值改 ~/.workbuddy 形态。
3、browser-harness：bh_chrome_keepalive.py 默认值全部改 env 驱动，新增 env/bh.env.example。
4、.gitignore：env/ 下只放行 *.example（三行三种层级）＋ 兜住旧位置的包根 roots.env。
5、改包纪律.md 新增「四、包结构：脚本是脚本，配置是配置」，立为全仓通用规矩。
6、文档同步：SKILL.md / deploy.md（新增 §3b 配置层级、§6 换机器必查 6 件事）/ rules.md /
   pitfalls.md / supervise-persistence.md。

验收（本机）：py_compile 34 个 py 全过；selftest PASS 109 / FAIL 0；
逐文件实证 8 个 loader 命中 env/roots.env；preflight-lock.sh 同目录实测解出两个根；
install.py --manifest 77 份、语法失败 0。

异机验证（包拷成「新克隆」（只有 *.example）＋ 另造假工作区 ws-alpha/ws-beta）：
install.py --apply 自生成该机 env/roots.env；collabctl/keepalive 自动发现的确实是
ws-alpha/ws-beta、任务名现推（写死清单确已消除）；部署副本本地无 roots.env 时靠
CODEBUDDY_CONFIG_DIR 兜底读到技能库那份；整套 selftest 有宿主库时 PASS 108 / FAIL 1
（唯一 FAIL＝该区没有常驻心跳，环境所致；本机常驻在跑时同一套为 PASS 109 / FAIL 0）。

session-mechanism/scripts/lock/handoff-guard.sh

@@ -34,10 +34,15 @@
 # 退出码：0 = 放行；1 = 命中硬冲突/硬判定；2 = 环境错误
 set -uo pipefail
 
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] 环境配置外置（由 install.py 生成）；2026-10-11 起落在本包 `env/roots.env`
+#   首选 env/roots.env；并兼容旧的包根 roots.env（拷贝未同步时照旧能跑）。
 _SM_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 _SM_PKG="$(cd "$_SM_HERE/../.." && pwd)"
-[ -f "$_SM_PKG/roots.env" ] && . "$_SM_PKG/roots.env"
+if [ -f "$_SM_PKG/env/roots.env" ]; then
+  . "$_SM_PKG/env/roots.env"
+elif [ -f "$_SM_PKG/roots.env" ]; then
+  . "$_SM_PKG/roots.env"
+fi
 ROOT="${DSH_DOCS_ROOT:-$(cd "$_SM_HERE/.." && pwd)}"
 cd "$ROOT" || exit 2
 LOCKDIR="$ROOT/05-交接单/.doing-"

session-mechanism/scripts/lock/handoff-status.py

@@ -8,13 +8,19 @@
 
 用法：python 07-scripts/handoff-status.py
 """
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] roots.env 外置（由 install.py 生成 ⇒ `<包>/env/roots.env`）
+#   查找顺序：向上 4 层 × (env/roots.env 优先 → 包根 roots.env 兼容) → 技能库那份。
 def _sm_load_roots():
     import os as _os
     _here = _os.path.dirname(_os.path.abspath(__file__))
+    _cands = []
     for _up in range(4):
-        _p = _os.path.join(_here, *([".."] * _up), "roots.env")
-        _p = _os.path.normpath(_p)
+        _base = _os.path.normpath(_os.path.join(_here, *([".."] * _up)))
+        for _rel in (("env", "roots.env"), ("roots.env",)):
+            _cands.append(_os.path.join(_base, *_rel))
+    _conf = _os.environ.get("CODEBUDDY_CONFIG_DIR") or _os.path.expanduser("~/.workbuddy")
+    _cands.append(_os.path.join(_conf, "skills", "session-mechanism", "env", "roots.env"))
+    for _p in _cands:
         if _os.path.isfile(_p):
             try:
                 with open(_p, encoding="utf-8") as _f:

session-mechanism/scripts/lock/orphan-lock.py

@@ -44,9 +44,16 @@ from pathlib import Path
 
 # ── 根目录定位（与包内其它脚本同款：宿主 env > `roots.env` 兜底）────────────
 def _sm_load_roots() -> None:
+    """把本包 `env/roots.env` 以 setdefault 注入 env（宿主 env 优先，⛔ 不覆盖）。"""
     here = os.path.dirname(os.path.abspath(__file__))
+    cands = []
     for up in range(4):
-        p = os.path.normpath(os.path.join(here, *([".."] * up), "roots.env"))
+        base = os.path.normpath(os.path.join(here, *([".."] * up)))
+        for rel in (("env", "roots.env"), ("roots.env",)):
+            cands.append(os.path.join(base, *rel))
+    conf = os.environ.get("CODEBUDDY_CONFIG_DIR") or os.path.expanduser("~/.workbuddy")
+    cands.append(os.path.join(conf, "skills", "session-mechanism", "env", "roots.env"))
+    for p in cands:
         if os.path.isfile(p):
             try:
                 with open(p, encoding="utf-8") as f:

session-mechanism/scripts/lock/preflight-lock.sh

@@ -22,10 +22,11 @@ if [ -z "$ME" ] || [ $# -eq 0 ]; then
   exit 2
 fi
 
-# [session-mechanism] roots.env 外置（由 install.py 生成；缺失则回落到按位置推导）
+# [session-mechanism] roots.env 外置（由 install.py 生成 ⇒ `<包>/env/roots.env`；兼容包根旧位置）
 _SM_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 _SM_PKG="$(cd "$_SM_HERE/../.." && pwd)"
-[ -f "$_SM_PKG/roots.env" ] && . "$_SM_PKG/roots.env"
+if [ -f "$_SM_PKG/env/roots.env" ]; then . "$_SM_PKG/env/roots.env"
+elif [ -f "$_SM_PKG/roots.env" ]; then . "$_SM_PKG/roots.env"; fi
 DOCS_ROOT="${DSH_DOCS_ROOT:-$(cd "$_SM_HERE/.." && pwd)}"
 CODE_ROOT="${DSH_CODE_REPO:-${DOCS_ROOT%/*}}"   # ⛔ 不留盘符：代码库＝文档库的上一级（纯 bash 展开，⛔ 不调 dirname）
 WS_ROOT="${DSH_WS_ROOT:-$(pwd)}"                # ⛔ 不留盘符：默认＝当前工作目录（本文件内未被使用）