hermes-connect-services 1.0.1 → 1.2.0

package/README.md

@@ -21,6 +21,15 @@ node hermes-connect-services/bin/sync-hermes-config.mjs --install-hooks
 
 两步可以合成一次带 `--install-hooks` 的运行。
 
+`--install-hooks` 顺手把 hook 真正跑起来所需的两件东西一起办了(只写 config.yaml 是不够的):
+
+| 目标文件 | 写入内容 | 少了它会怎样 |
+|---|---|---|
+| `shell-hooks-allowlist.json` | `on_session_start` 的审批条目 | hook 每次会话都被跳过,端点从不启动 |
+| `.env` | 托管块 `NO_PROXY=127.0.0.1,…` | 代理软件会把回环调用吞掉 |
+
+写完**重启 hermes**:hook 只在网关启动时注册。
+
 也可以走 npm(四个端点包 + 本包装在同一项目里,脚本会自动在 `node_modules/` 找兄弟包):
 
 ```sh
@@ -109,34 +118,110 @@ model:
 | `… --no-reasoning` | 全部模型标 `supports_reasoning: false` |
 | `… --config <path>` | 指定配置文件 |
 | `node bin/ensure-services.mjs [--verbose]` | 单独执行懒启动(也是 hook 本体) |
+| `node bin/patch-hermes-stall-gate.mjs` | 给 hermes 补「宣布下一步却没动手」的续跑闸门 |
+| `… --check` | 只报告补丁状态(升级后跑一次看是否失效) |
+| `… --revert` | 撤销补丁,恢复到原始字节 |
+
+## 五、续跑闸门:模型说要做什么,然后就停了
+
+模型常见的收尾是「我先检查配置，再修改这里：」——宣布了下一步,零工具调用就结束这一轮。这不是完成,是卡住。
+
+ZCode / pi / dsh 三端各有一个官方钩子点可以兜住(Stop hook、`turn_end`、`agent/turn-stopping`)。**hermes 没有**:
+
+- `hermes_cli/plugins.py` 的 `VALID_HOOKS` 里没有任何「回合正常结束」事件(`agent_loop_stopped` 是 `/stop` 打断,不是收尾)。
+- 唯一能续跑的闸门是 `pre_verify`,但它的前置条件是 `if _edited and has_hook("pre_verify")` —— 本轮**写过文件**才触发。而「我先检查配置」这种收尾往往只读不写,或一个工具都没调,正好落在门控之外。
+- 内置的 `_dropped_toolcall_nudge` 只处理 `finish_reason == "tool_calls"` 但 `tool_calls` 为空 —— 协议层信号,精确但覆盖面窄。
+
+所以只能往宿主的收尾闸门链里加第 5 道。
+
+```sh
+node bin/patch-hermes-stall-gate.mjs            # 打补丁
+node bin/patch-hermes-stall-gate.mjs --check    # 看状态
+node bin/patch-hermes-stall-gate.mjs --revert   # 干净回退
+```
+
+改动面刻意压到最小 —— 宿主原有行一个字节不动:
+
+| 文件 | 改动 |
+|---|---|
+| `agent/turn_stop_gates.py` | 两个 marker 块:模块级判定函数 + 一处调用 |
+| `agent/stall_detector.py` | 新增,判定逻辑本体(与 JS 版逐条对齐) |
+
+`--revert` 会从首次打补丁时留下的快照还原 `turn_stop_gates.py`,实测与原始文件**逐字节相同**。
+
+### 生效方式
+
+**改完必须重启 hermes gateway** —— 已 import 的模块不会自动重载,不重启就等于没打。
+
+### hermes 升级会覆盖
+
+自更新会重置 `hermes-agent/` 下的源码,两块一起消失。表现是「续跑不再发生」而不是报错:模块级 import 包在 `try/except` 里,`stall_detector.py` 不在时闸门静默失效,不影响正常结束。升级后重跑一次脚本即可,`--check` 会告诉你当前状态。
 
-## 五、排障
+### 开关与防护
+
+```yaml
+agent:
+  stall_guard: false      # 或环境变量 HERMES_STALL_GUARD=0
+```
+
+- **同一段回复只续一次**:按文本 sha1 指纹去重,模型被提示后原样复读不会二次触发。
+- **一个会话上限 3 次**:与 ZCode 侧一致。连续 3 次都唤不醒,再提示也只是复读计划。
+- **本轮有工具调用就不判**:`_zc_tool_calls_this_turn()` 只看最后一条 user 消息之后的 `tool_calls`,`> 0` 一律跳过。
+- 闸门内部全部 fail-open:任何异常只写 debug 日志,绝不让一次正常收尾因为插件出错而崩。
+
+### 阈值不是「看到冒号就续跑」
+
+判定是打分制,否决规则先于肯定规则求值:问句收尾、把决定权交回用户、明确完成宣告 —— 一律不续跑。冒号只是加权项(说明性文字大量以冒号收尾)。规则表与 ZCode / pi / dsh 完全同源,`tests/test-detector-parity.mjs` 会拿同一批文本喂给 JS 与 Python 两份实现,逐字段比对 `verdict` / `score` / `signals` —— 任一边改了规则而另一边没跟上,这个测试就红。
+
+### 一个已知差异
+
+ZCode 的 Stop hook 由宿主保证「只在一轮零工具调用时执行」,所以那边按**每轮**计数。hermes 这边没有可靠的轮次标识(续跑本身会追加一条 user 消息),所以上限按**会话**计:同一会话累计续跑 3 次后不再触发。保守方向是一致的 —— 只能少续,不会多续。
+
+## 六、排障
 
 **401 / 模型不在了** — 端点 token 轮换或上游名册变了,重跑 `sync-hermes-config.mjs`。
 
-**hook 第一次不执行** — hermes 首次运行 hook 需要交互确认。非交互场景在 config.yaml 设:
+**hook 被静默跳过 —— 这是最常见的"provider temporarily unavailable"真因。** hermes 只运行 `(event, command)` 出现在 `shell-hooks-allowlist.json` 里的 hook;没列入的会被日志记一句 `not allowlisted … — skipped` 然后**永不执行**,于是四个端点从未启动,hermes 侧只看到 connection refused,一路重试到 5 个 cycle。
+
+`--install-hooks` 现在会自己把这一对写进 allowlist(位于 hermes home,与 config.yaml 同级),并保留你其他的 hook 审批。检查:
+
+```sh
+node bin/sync-hermes-config.mjs --install-hooks --verbose   # 应输出 hook allowlist: added|present
+grep -c allowlisted ~/AppData/Local/hermes/logs/agent.log   # 不该再增长
+```
+
+手工兜底(可选,范围更大):
 
 ```yaml
 hooks_auto_accept: true
 ```
 
-**连不上回环地址(`404 no such route` 带绝对 URL、**或 connection refused)** — hermes 是 Python + httpx,会读 `HTTP_PROXY` / `HTTPS_PROXY`。这些变量存在时本地请求会被送去代理,回环地址自然打不通。启动时带上 no_proxy:
+**改完必须重启 hermes** — hook 在网关启动时注册,已运行的会话不会补挂。
+
+**连不上回环地址(`404 no such route` 带绝对 URL,或 connection refused)** — hermes 是 Python + httpx,会读 `HTTP_PROXY` / `HTTPS_PROXY`。历史上这条会把手打回环的请求送去代理,`--install-hooks` 因此会在 hermes home 的 `.env` 里托管一段:
 
-```sh
-NO_PROXY=127.0.0.1,localhost   # PowerShell: $env:NO_PROXY="127.0.0.1,localhost"
 ```
+# >>> zcode-ai-connect >>>
+NO_PROXY=127.0.0.1,localhost,::1,0.0.0.0
+no_proxy=127.0.0.1,localhost,::1,0.0.0.0
+# <<< zcode-ai-connect <<<
+```
+
+实测 httpx + openai SDK 通常已自行放行 `127.0.0.1`,这段属于兜底:机器换代理软件、或代理换成强制拦截型时能少一次排查。(`.env` 是 `override=True` 载入的,所以它会顶掉系统里同名的 `NO_PROXY`;要在代理侧仍走别的例外host,把它们的域名补进这四行。)
 
 **Thoughts 太长被压缩** — `model_overrides` 里的 `context_window` 来自端点实时 roster;换模型名后重跑同步脚本同步上下文窗口。
 
 **思考档位** — hermes 全局 `agent.reasoning_effort` 默认 `ultra`,这些端点会原样转发 OpenAI 的 `reasoning_effort`。上游不认 `ultra` 时把它降到 `high`。不想让任何模型思考就加 `--no-reasoning`。
 
-## 六、测试
+## 七、测试
 
 ```sh
-node hermes-connect-services/tests/test-yaml-patch.mjs
+node tests/test-yaml-patch.mjs          # 托管块插入/替换/卸载、幂等、--only、孤儿标记自愈
+node ../tests/test-detector-parity.mjs  # JS ↔ Python 判定器逐字段对齐
+node tests/test-stall-gate.mjs          # 闸门行为(需要本机装有 hermes)
 ```
 
-覆盖的是最危险的那部分:托管块插入/替换/卸载、幂等性、`--only` 不删邻居、孤儿标记自愈。
+`test-stall-gate.mjs` 直接 import 宿主的 `apply_stop_gates`,让整条闸门链真实跑一遍 —— 不是 mock 一个函数名对得上就算过。
 
 ---
 

package/bin/patch-hermes-stall-gate.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * patch-hermes-stall-gate.mjs — 给 hermes 补一个「宣布下一步却没动手」的续跑闸门。
+ *
+ * ## 为什么这里必须打补丁，而 ZCode / pi / dsh 不用
+ *
+ * 另外三端各有一处「回合结束后仍可续跑」的官方钩子点：
+ *   ZCode  Stop hook（宿主保证只在一轮零工具调用时触发）
+ *   pi     turn_end 返回 {continue:true, entries:[...]}
+ *   dsh    agent/turn-stopping 里 agent.steer()
+ *
+ * hermes 没有。`hermes_cli/plugins.py` 的 VALID_HOOKS 里没有任何「回合正常结束」事件
+ * （`agent_loop_stopped` 是 /stop 打断，不是收尾）。唯一能续跑的闸门是 `pre_verify`，
+ * 但 `agent/turn_stop_gates.py` 里它的前置条件是 `if _edited and has_hook("pre_verify")`
+ * —— 本轮**写过文件**才触发。而「我先检查配置，再修改这里：」这种收尾往往一个工具都
+ * 没调，或者只读不写，正好落在门控之外。
+ *
+ * 所以只能往宿主的收尾闸门链里加第 5 道。改动面刻意压到最小：
+ *
+ *   agent/turn_stop_gates.py   两个托管块（模块级判定函数 + 一处调用），marker 包围
+ *   agent/stall_detector.py    新增文件，判定逻辑本体（从 shared/stall_detector.py 分发）
+ *
+ * 宿主自带的行一个字节不动，revert 时两条 marker 之间的内容整段删除即可。
+ *
+ * ## 升级会覆盖
+ *
+ * hermes 自更新会重置 hermes-agent/ 下的源码，这两个块会一起消失。表现是「续跑不再
+ * 发生」而不是报错（模块级 import 有 try/except，文件不在时 `_zc_detect_stall` 为 None，
+ * 闸门静默失效）。升级后重跑本脚本即可恢复 —— `--check` 会告诉你当前状态。
+ *
+ * @module patch-hermes-stall-gate
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(HERE, '..');
+const HOME = process.env.HOME ?? process.env.USERPROFILE ?? '';
+const MARKER = 'zcode-ai-connect stall-guard';
+const START = `# >>> ${MARKER} >>>`;
+const END = `# <<< ${MARKER} <<<`;
+
+const argv = process.argv.slice(2);
+const has = (name) => argv.includes(name);
+const valueOf = (name) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? undefined : argv[i + 1];
+};
+
+const options = {
+  check: has('--check'),
+  revert: has('--revert'),
+  dryRun: has('--dry-run'),
+  verbose: has('--verbose') || has('-v'),
+  home: valueOf('--home') ?? process.env.HERMES_HOME ?? null,
+};
+
+/** hermes 的 home：Windows 是 %LOCALAPPDATA%/hermes，其他地方是 ~/.hermes。 */
+function locateHome() {
+  const candidates = [
+    options.home,
+    process.env.HERMES_HOME,
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'hermes') : null,
+    join(HOME, '.hermes'),
+  ].filter(Boolean);
+  return candidates.find((p) => existsSync(join(p, 'config.yaml'))) ?? null;
+}
+
+/** 运行时的源码树。installs/<id>/environments/<id>/workspace 是项目沙箱副本，不是主进程加载的那份。 */
+function locateAgentRoot(home) {
+  const candidates = [
+    join(home, 'hermes-agent'),
+    join(HOME, '.hermes', 'hermes-agent'),
+  ];
+  return candidates.find((p) => existsSync(join(p, 'agent', 'turn_stop_gates.py'))) ?? null;
+}
+
+/** 找 hermes 自带的解释器，用来做语法检查。 */
+function findPython(home) {
+  const candidates = [
+    process.env.HERMES_PYTHON,
+    join(home, 'tools', `python-3.14.9+20261021-win32-x64`, 'python.exe'),
+    'python',
+    'python3',
+  ].filter(Boolean);
+  for (const exe of candidates) {
+    const probe = spawnSync(exe, ['-c', 'print(1)'], { encoding: 'utf8', timeout: 15000 });
+    if (probe.status === 0 && probe.stdout.trim() === '1') return exe;
+  }
+  return null;
+}
+
+const MODULE_BLOCK = (source) => [
+  START,
+  '# 由 hermes-connect-services/bin/patch-hermes-stall-gate.mjs 写入 —— 勿手改。',
+  '#',
+  '# 第 5 道收尾闸：模型只宣布下一步、本轮零工具调用就结束，追加一条 user 提示把本轮续上。',
+  '# 判定逻辑在 agent/stall_detector.py，与 ZCode / pi / dsh 三端同一套规则。',
+  'import hashlib as _zc_hashlib',
+  '',
+  '# 一个会话内最多续跑几次。与三端一致：连续 3 次都唤不醒，再提示也只是复读计划。',
+  '_ZC_STALL_MAX_NUDGES = 3',
+  '',
+  'try:',
+  '    from agent.stall_detector import detect_stall as _zc_detect_stall',
+  'except Exception:  # 升级后 stall_detector.py 可能不在：静默降级，绝不阻断正常结束',
+  '    _zc_detect_stall = None',
+  '',
+  '',
+  'def _zc_stall_guard_enabled() -> bool:',
+  '    env = os.environ.get("HERMES_STALL_GUARD")',
+  '    if env is not None:',
+  '        return env.strip().lower() not in {"0", "false", "off", "no", "disabled"}',
+  '    try:',
+  '        from hermes_cli.config import load_config_readonly',
+  '',
+  '        cfg = (load_config_readonly() or {}).get("agent") or {}',
+  '    except Exception:',
+  '        return True',
+  '    value = cfg.get("stall_guard", True)',
+  '    if isinstance(value, bool):',
+  '        return value',
+  '    return str(value).strip().lower() not in {"0", "false", "off", "no", "disabled"}',
+  '',
+  '',
+  'def _zc_tool_calls_this_turn(messages) -> int:',
+  '    """本轮（最后一条 user 消息之后）发出的 tool_call 总数。',
+  '',
+  '    与 ZCode 侧的 toolCallCount 同义：> 0 就不存在「只说不做」。',
+  '    """',
+  '    start = 0',
+  '    for i in range(len(messages) - 1, -1, -1):',
+  '        msg = messages[i]',
+  '        if isinstance(msg, dict) and msg.get("role") == "user":',
+  '            start = i + 1',
+  '            break',
+  '    total = 0',
+  '    for msg in messages[start:]:',
+  '        if not isinstance(msg, dict):',
+  '            continue',
+  '        calls = msg.get("tool_calls")',
+  '        if isinstance(calls, list):',
+  '            total += len(calls)',
+  '    return total',
+  '',
+  '',
+  'def _zc_stall_guard_nudge(agent, messages, final_response):',
+  '    """命中则返回要回灌的提示，否则 None。',
+  '',
+  '    收尾闸门里抛异常会打断本轮的正常结束，所以整个函数是 fail-open 的。',
+  '    """',
+  '    try:',
+  '        if _zc_detect_stall is None or not _zc_stall_guard_enabled():',
+  '            return None',
+  '        text = final_response if isinstance(final_response, str) else ""',
+  '        if not text.strip():',
+  '            return None',
+  '        digest = _zc_hashlib.sha1(text.encode("utf-8", "ignore")).hexdigest()',
+  '        seen = getattr(agent, "_zc_stall_guard_seen", None)',
+  '        if not isinstance(seen, list):',
+  '            seen = []',
+  '        if digest in seen or len(seen) >= _ZC_STALL_MAX_NUDGES:',
+  '            return None',
+  '        verdict = _zc_detect_stall(text, _zc_tool_calls_this_turn(messages))',
+  '        if not isinstance(verdict, dict) or not verdict.get("stall"):',
+  '            return None',
+  '        agent._zc_stall_guard_seen = seen + [digest]',
+  '        logger.debug(',
+  '            "stall-guard matched (verdict=%s score=%s signals=%s)",',
+  '            verdict.get("verdict"), verdict.get("score"), verdict.get("signals"),',
+  '        )',
+  '        return verdict.get("prompt")',
+  '    except Exception:',
+  '        logger.debug("stall-guard check failed", exc_info=True)',
+  '        return None',
+  END,
+].join('\n');
+
+const CALL_BLOCK = [
+  `    ${START}`,
+  '    # 放在最后一道：前面的闸门（late-LSP / verify-on-stop / pre_verify / kanban）',
+  '    # 已经各自 return 了，走到这里说明没有别的理由继续这一轮。',
+  '    _zc_nudge = _zc_stall_guard_nudge(agent, messages, final_response)',
+  '    if _zc_nudge:',
+  '        final_msg["finish_reason"] = "stall_guard_continue"',
+  '        _append_interim_answer(',
+  '            agent, final_msg, messages, conversation_history, "stall-guard interim flush failed"',
+  '        )',
+  '        logger.debug(',
+  '            "stall-guard nudge issued (%d/%d)",',
+  '            len(getattr(agent, "_zc_stall_guard_seen", []) or []),',
+  '            _ZC_STALL_MAX_NUDGES,',
+  '        )',
+  '        return _continue(_zc_nudge, "_zc_stall_guard_synthetic")',
+  `    ${END}`,
+].join('\n');
+
+/**
+ * 删掉**所有** marker 块。
+ *
+ * 必须按整行删除：调用块是缩进在函数体里的，若只从 `#` 开始切，会留下那 4 个
+ * 空格残行，导致结果变成 `            return StopGateVerdict(`（12 空格）—— 语法
+ * 合法但缩进错误，Python 会把它当缩进块的一部分。所以按行首/行尾切。
+ */
+function stripBlock(text) {
+  let lines = text.split('\n');
+  for (;;) {
+    const s = lines.findIndex((line) => line.includes(START));
+    if (s === -1) break;
+    let e = lines.findIndex((line, i) => i > s && line.includes(END));
+    if (e === -1) break;
+    lines.splice(s, e - s + 1);
+    // 块两侧原本各有一个空行分隔；删完如果两边都是空行，会多出一个。
+    if (lines[s - 1] !== undefined && lines[s] !== undefined
+      && lines[s - 1].trim() === '' && lines[s].trim() === '') {
+      lines.splice(s, 1);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** 锚点必须唯一，否则宁可报错也不猜。 */
+function assertUniqueAnchor(text, anchor, label) {
+  const first = text.indexOf(anchor);
+  if (first === -1) throw new Error(`找不到插入锚点: ${label}`);
+  if (text.indexOf(anchor, first + 1) !== -1) throw new Error(`插入锚点不唯一: ${label}`);
+  return first;
+}
+
+function main() {
+  const home = locateHome();
+  if (!home) {
+    console.error('找不到 hermes home（可设 HERMES_HOME 或用 --home 指定）');
+    process.exit(1);
+  }
+  const agentRoot = locateAgentRoot(home);
+  if (!agentRoot) {
+    console.error(`找不到 ${join(home, 'hermes-agent')}/agent/turn_stop_gates.py`);
+    process.exit(1);
+  }
+
+  const gatePath = join(agentRoot, 'agent', 'turn_stop_gates.py');
+  const detectorPath = join(agentRoot, 'agent', 'stall_detector.py');
+  const sourceDetector = join(PKG_ROOT, 'lib', 'stall_detector.py');
+
+  if (!existsSync(sourceDetector)) {
+    console.error(`包里缺 lib/stall_detector.py —— 先在仓库根跑 node scripts/sync-stall-guard.mjs`);
+    process.exit(1);
+  }
+
+  let gate = readFileSync(gatePath, 'utf8');
+  const patched = gate.includes(START);
+  const detectorPresent = existsSync(detectorPath);
+
+  if (options.check) {
+    console.log(`home:       ${home}`);
+    console.log(`gate file:  ${gatePath}`);
+    console.log(`patched:    ${patched ? 'yes' : 'no'}`);
+    console.log(`detector:   ${detectorPresent ? 'yes' : 'no'}`);
+    if (patched && detectorPresent) {
+      const same = readFileSync(detectorPath, 'utf8') === readFileSync(sourceDetector, 'utf8');
+      console.log(`detector in sync: ${same ? 'yes' : 'NO (重跑本脚本)'}`);
+      if (!same) process.exit(2);
+    } else {
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (options.revert) {
+    if (!patched && !detectorPresent) {
+      console.log('没有需要撤销的改动');
+      return;
+    }
+    if (options.dryRun) {
+      console.log(`--dry-run: 会移除 ${gatePath} 的托管块${detectorPresent ? ' 与 stall_detector.py' : ''}`);
+      return;
+    }
+    const bakPath = `${gatePath}.bak-zcode-stall-guard`;
+    // 首次打补丁时留下的原始快照优先 —— 它比"按 marker 反删"更能保证零字节还原。
+    const bakIsPristine = existsSync(bakPath) && !readFileSync(bakPath, 'utf8').includes(START);
+    if (bakIsPristine) {
+      copyFileSync(bakPath, gatePath);
+      console.log(`  从原始快照恢复 ${bakPath}`);
+    } else {
+      writeFileSync(gatePath, stripBlock(gate), 'utf8');
+    }
+    if (detectorPresent) {
+      const current = readFileSync(detectorPath, 'utf8');
+      if (current === readFileSync(sourceDetector, 'utf8')) {
+        unlinkSync(detectorPath);
+      } else {
+        console.log(`stall_detector.py 已被改动过，保留不删: ${detectorPath}`);
+      }
+    }
+    console.log(`已撤销${bakIsPristine ? '' : `（备份: ${bakPath}）`}`);
+    return;
+  }
+
+  // ── 应用补丁（幂等：先清旧块再按锚点插新块） ─────────────────────────────
+  gate = stripBlock(gate);
+
+  const moduleAnchor = '\ndef _verify_on_stop_nudge(agent) -> Optional[str]:';
+  const callAnchor = '\n    return StopGateVerdict(\n        continue_turn=False, final_response=final_response,';
+
+  const moduleAt = assertUniqueAnchor(gate, moduleAnchor, 'def _verify_on_stop_nudge');
+  gate = `${gate.slice(0, moduleAt)}\n${MODULE_BLOCK()}\n${gate.slice(moduleAt)}`;
+
+  const callAt = assertUniqueAnchor(gate, callAnchor, 'return StopGateVerdict(continue_turn=False');
+  gate = `${gate.slice(0, callAt)}\n${CALL_BLOCK}\n${gate.slice(callAt)}`;
+
+  if (options.dryRun) {
+    console.log(`--dry-run: 会给 ${gatePath} 插入 ${START} / ${END} 两块`);
+    if (options.verbose) console.log(MODULE_BLOCK().split('\n').slice(0, 4).join('\n'));
+    return;
+  }
+
+  // 只有在文件还是原样时才留快照。重打补丁时覆盖快照，会让 --revert 失去干净的回退点。
+  if (!patched) copyFileSync(gatePath, `${gatePath}.bak-zcode-stall-guard`);
+  writeFileSync(gatePath, gate, 'utf8');
+  mkdirSync(dirname(detectorPath), { recursive: true });
+  writeFileSync(detectorPath, readFileSync(sourceDetector, 'utf8'), 'utf8');
+
+  // ── 语法检查：补丁后宿主必须仍然可 import ─────────────────────────────────
+  const python = findPython(home);
+  if (python) {
+    const check = spawnSync(python, ['-m', 'py_compile', gatePath, detectorPath], {
+      encoding: 'utf8', timeout: 60000, cwd: agentRoot,
+    });
+    if (check.status !== 0) {
+      copyFileSync(`${gatePath}.bak-zcode-stall-guard`, gatePath);
+      console.error('语法检查失败，已回滚:');
+      console.error((check.stderr || check.stdout || '').slice(0, 1200));
+      process.exit(1);
+    }
+    console.log(`  syntax ok (${python})`);
+  } else {
+    console.log('  (没找到 python，跳过语法检查)');
+  }
+
+  console.log(`  patched ${gatePath}`);
+  console.log(`  wrote   ${detectorPath}`);
+  console.log('');
+  console.log('生效需要重启 hermes gateway —— 已 import 的模块不会自动重载。');
+}
+
+main();

package/bin/sync-hermes-config.mjs

@@ -27,6 +27,7 @@ import { fileURLToPath } from 'node:url';
 import { SERVICES, HOME, SUITE_ROOT, ensure as ensureService } from '../src/services.mjs';
 import { loadRoster, describe } from '../src/roster.mjs';
 import { patchManagedBlock, readManagedBlock, readManagedChildren } from '../src/yaml-patch.mjs';
+import { allowHook, revokeHooks, ensureNoProxy, removeNoProxy } from '../src/hermes-home.mjs';
 
 const HERE = pathDirname(fileURLToPath(import.meta.url));
 const MARKER = 'zcode-ai-connect';
@@ -118,15 +119,20 @@ function overridesBlockYaml(service, models) {
 function hooksBlockYaml() {
   const nodeExe = process.execPath.replaceAll('\\', '/');
   const script = join(HERE, 'ensure-services.mjs').replaceAll('\\', '/');
+  // The raw string hermes shlex-splits into argv; also the key it matches
+  // against shell-hooks-allowlist.json, so the two must stay byte-identical.
+  const command = `"${nodeExe}" "${script}"`;
   // shlex.split + shell=False: the token that reaches Popen must keep both
   // paths quoted, so the whole value is single-quoted YAML rather than two
   // adjacent double-quoted scalars (which YAML rejects outright).
-  const command = `'${`"${nodeExe}" "${script}"`}'`;
-  return [
-    `on_session_start:`,
-    `  - command: ${command}`,
-    `    timeout: 30`,
-  ];
+  return {
+    command,
+    lines: [
+      `on_session_start:`,
+      `  - command: '${command}'`,
+      `    timeout: 30`,
+    ],
+  };
 }
 
 // --- collect rosters --------------------------------------------------------
@@ -192,6 +198,10 @@ if (options.remove) {
     const result = patchManagedBlock(text, key, '', { marker: MARKER });
     text = result.text;
   }
+  const HOME_DIR = pathDirname(CONFIG_PATH);
+  const revoked = revokeHooks(HOME_DIR, [hooksBlockYaml().command], { dryRun: options.dryRun });
+  if (revoked) console.log(`  hook allowlist: removed ${revoked}`);
+  if (removeNoProxy(HOME_DIR, { dryRun: options.dryRun })) console.log('  no_proxy: removed');
 } else {
   const providerUpdates = [];
   const overrideUpdates = [];
@@ -213,7 +223,8 @@ if (options.remove) {
   }
 
   if (options.installHooks) {
-    const body = hooksBlockYaml().join('\n');
+    const hook = hooksBlockYaml();
+    const body = hook.lines.join('\n');
     if (readManagedBlock(text, 'hooks', { marker: MARKER }).trim() !== '') {
       text = patchManagedBlock(text, 'hooks', body, { marker: MARKER }).text;
       changes.push('hooks: replaced');
@@ -226,6 +237,16 @@ if (options.remove) {
       text = result.text;
       changes.push(`hooks: ${result.action}`);
     }
+
+    // Writing the hook is only half of it: hermes refuses to run any
+    // (event, command) it has not approved, and silently skips it each session.
+    const HOME_DIR = pathDirname(CONFIG_PATH);
+    const allowed = allowHook(HOME_DIR, 'on_session_start', hook.command, { dryRun: options.dryRun });
+    changes.push(`hook allowlist: ${allowed}`);
+    // httpx honours HTTP_PROXY; without this the loopback calls die as
+    // "Provider temporarily unavailable".
+    const proxied = ensureNoProxy(HOME_DIR, { dryRun: options.dryRun });
+    changes.push(`no_proxy: ${proxied}`);
   }
   console.log(changes.map((line) => `  ${line}`).join('\n'));
 }
@@ -253,13 +274,11 @@ console.log(`  hermes --provider ${collected[0].service.id} --model <id>`);
 console.log('');
 console.log('Token 轮换(报 401)或上游名册变化时,重跑本脚本即可。');
 
-if (options.installHooks && !options.remove && !options.dryRun) {
-  const autoAccept = readFileSync(CONFIG_PATH, 'utf8').match(/^hooks_auto_accept:\s*(.+)$/m)?.[1]?.trim();
-  if (autoAccept !== 'true') {
-    console.log('');
-    console.log(`提示: 首次运行 hook 需要交互确认。非交互场景请在 ${CONFIG_PATH} 设置 hooks_auto_accept: true`);
-    console.log('      (当前值: ' + (autoAccept ?? '未设置') + ')');
-  }
+if (options.installHooks && !options.remove) {
+  console.log('');
+  console.log('⚠ 重启 hermes 让两件事生效:');
+  console.log('  1. on_session_start hook 重新注册(已写入 allowlist,不会再被跳过)');
+  console.log('  2. .env 里的 NO_PROXY(否则 127.0.0.1 的请求会被 HTTP_PROXY 吞掉)');
 }
 
 if (options.remove) {

package/lib/stall_detector.py

@@ -0,0 +1,256 @@
+"""stall_detector —— 「宣布了下一步却没调用工具」的启发式判定（Python 版）。
+
+与 ``shared/stall-detector.mjs`` 逐条对齐，供 hermes 的回合结束闸门使用。
+**两份实现必须同步**：改任意一份都要跑 ``node tests/test-detector-parity.mjs``，
+它会把同一批用例喂给两边的实现并逐字段比对（verdict / score / signals）。
+
+设计约束与 JS 版一致：
+
+ 1. 这是启发式，不是判定器。宁可漏掉一次续跑，也不要打断一条正常收尾的回复。
+ 2. 否决（veto）规则先于肯定（cue）规则求值。
+ 3. 冒号只是加权项，不足以独立触发。
+ 4. 零依赖、纯函数、无 IO —— 会被复制进宿主包，不能 import 本项目其他模块。
+
+与 JS 版的唯一刻意差异：返回值是 dict 而不是对象字面量。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict
+
+__all__ = ["detect_stall", "CONTINUE_PROMPT"]
+
+# 上限：只看最后两块 + 最多 600 字符。更早的内容是背景，不是收尾意图。
+TAIL_BLOCK_COUNT = 2
+TAIL_CHAR_LIMIT = 600
+
+# 低于这个（加权）长度的回复不判 —— 「好的。」「Done.」没有可续跑的动作。
+# 中日韩文字按 1.6 字计权：同样表达一个完整动作，中文比英文短得多。
+MIN_WEIGHTED_CHARS = 14.0
+
+# 请求用户裁决 / 提供输入的措辞。命中即否决。
+REQUEST_PATTERNS = [
+    # 中文：把决定权交回用户
+    r"请你?(?:确认|批准|授权|选择|决定|提供|粘贴|发送|告知|告诉)",
+    r"你(?:可以|需要|来)(?:确认|决定|选择|提供|先)",
+    r"需要你(?:确认|决定|操作|提供|回复|选择)",
+    r"(?:是否|要不要|需不需要|要不要我|需要我)(?:继续|执行|我|帮|先|再)?",
+    r"等你(?:确认|回复|决定|操作)",
+    r"告诉我(?:你|是否|要|结果|选择)",
+    r"让我知道",
+    r"由你(?:决定|来|选)",
+    r"你(?:先|来)(?:确认|决定|操作|选)",
+    r"确认后(?:我)?再",
+    r"(?:你|您)看(?:看|一下)?(?:是否|要不要|行不行)",
+    # English: handing the decision back
+    r"\blet me know\b",
+    r"\bwould you like\b",
+    r"\bdo you want\b",
+    r"\bshall i\b",
+    r"\bplease (?:confirm|advise|provide|choose)\b",
+    r"\byour call\b",
+    r"\bwhich (?:one|option|approach) (?:do you|would you)\b",
+    r"\bcan you (?:confirm|provide|share|tell)\b",
+    r"\bwaiting (?:for|on) your\b",
+]
+
+# 「已经做完」的收尾。命中且无未来标记时否决。
+DONE_PATTERNS = [
+    r"(?:已|已经)(?:经)?(?:完成|修好|改好|搞定|处理完|就绪|生效|上线|发布|通过)",
+    r"(?:全部|都)(?:完成|通过|搞定|就绪)",
+    r"(?:搞定|收工|完事)(?:了)?[。.!！]?$",
+    r"(?:到|就)这里(?:为止|结束)?",
+    r"(?:没有|无需)(?:其他|更多|别的)(?:改动|问题|需要)",
+    r"\b(?:all )?done\b",
+    r"\b(?:finished|completed|ready to go)\b",
+    r"\bnothing (?:else|more) (?:to do|needed)\b",
+    r"\ball (?:tests? )?pass(?:ed|ing)?\b",
+]
+
+# 强未来标记：明确宣布「我即将做」。单独出现即高置信。
+FUTURE_STRONG = [
+    # 「我先…」「我这就…」是中文里最典型的「宣布即将动手」，不必再跟动词。
+    r"我(?:先|这就|马上|立刻|接下来|现在)",
+    r"我(?:来|将|会|要|去)(?:先|先来)?",
+    r"先让我",
+    r"让(?:我们|我)先",
+    r"(?:接下来|下面|现在)我(?:来|将|会|要)",
+    r"开始(?:执行|处理|修改|实现|写|改|跑|检查)",
+    r"\blet me\b",
+    r"\bi'?ll\b",
+    r"\bi will\b",
+    r"\bi'?m going to\b",
+    r"\bnow i'?ll\b",
+    r"\blet'?s\b",
+]
+
+# 弱未来标记：推进语，但单独不足以说明「要动手」—— 也可能是继续讲解。
+FUTURE_WEAK = [
+    r"接下来",
+    r"下一步",
+    r"下面(?:我|我们)?",
+    r"然后(?:我|我们)?",
+    r"首先",
+    r"现在(?:我|我们)?",
+    r"\bnext,?\b",
+]
+
+# 动作动词：把「未来时」落到「要做一件具体的事」上。
+ACTION_VERB = [
+    r"(?:检查|查看|看看|查一下|读取|打开|搜索|定位)",
+    r"(?:修改|改成|改掉|编辑|写入|创建|新建|删除|移除|重写)",
+    r"(?:执行|运行|跑一下|启动|重启|安装|部署|发布|提交)",
+    r"(?:修复|实现|添加|增加|补充|更新|替换|迁移|重构)",
+    r"(?:验证|测试|校验|确认一下|跑通|编译)",
+    r"\b(?:check|read|open|inspect|look at|search|grep)\b",
+    r"\b(?:edit|write|create|add|remove|delete|rewrite|patch|update)\b",
+    r"\b(?:run|execute|install|deploy|build|start|restart|publish)\b",
+    r"\b(?:fix|implement|refactor|migrate|verify|test)\b",
+]
+
+# 尾部形态加权。冒号不足以独立触发。
+COLON_TAIL = re.compile(r"[:：]\s*\Z")
+ELLIPSIS_TAIL = re.compile(r"(?:\.{3,}|…)\s*\Z")
+QUESTION_TAIL = re.compile(r"[?？]\s*\Z")
+
+# 阈值。只有弱未来标记时必须靠额外信号才能过线。
+THRESHOLD_STRONG = 3.0
+THRESHOLD_WEAK_ONLY = 4.5
+
+_CJK_CHAR = re.compile(r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
+
+_COMPILED: Dict[str, list] = {}
+
+
+def _compile(group: str, patterns: list) -> list:
+    """每个模式组只编译一次，且大小写不敏感（与 JS 版逐条带 ``i`` 等价）。
+
+    注意：JS 版里只有英文模式带 ``i``，中文模式没有。这里统一用 IGNORECASE
+    是安全的 —— 中文模式不含字母，加不加都一样。
+    """
+    if group not in _COMPILED:
+        _COMPILED[group] = [re.compile(p, re.IGNORECASE) for p in patterns]
+    return _COMPILED[group]
+
+
+def _any_match(group: str, text: str) -> bool:
+    return any(rx.search(text) for rx in _compile(group, _PATTERN_GROUPS[group]))
+
+
+_PATTERN_GROUPS = {
+    "request": REQUEST_PATTERNS,
+    "done": DONE_PATTERNS,
+    "future_strong": FUTURE_STRONG,
+    "future_weak": FUTURE_WEAK,
+    "action_verb": ACTION_VERB,
+}
+
+
+def _strip_noise(text: str) -> str:
+    """去掉代码围栏/行内代码/标签 —— 代码里的冒号和动词不是模型的收尾意图。"""
+    text = re.sub(r"```[\s\S]*?```", " ", text)
+    text = re.sub(r"`[^`\n]*`", " ", text)
+    text = re.sub(r"</?[a-zA-Z][^>]{0,200}>", " ", text)
+    text = re.sub(r"\[[^\]]{0,80}\]\([^)]{0,300}\)", " ", text)
+    text = re.sub(r"[ \t]+", " ", text)
+    return text.strip()
+
+
+def _tail_of(text: str) -> str:
+    """最后两块非空段落，按字符上限截尾。"""
+    blocks = [b.strip() for b in re.split(r"\n{2,}", text) if b.strip()]
+    if not blocks:
+        return ""
+    joined = "\n".join(blocks[-TAIL_BLOCK_COUNT:]).strip()
+    return joined[-TAIL_CHAR_LIMIT:] if len(joined) > TAIL_CHAR_LIMIT else joined
+
+
+def _weighted_length(text: str) -> float:
+    """中日韩字符按 1.6 计权后的长度，见 MIN_WEIGHTED_CHARS。"""
+    return sum(1.6 if _CJK_CHAR.match(ch) else 1.0 for ch in text)
+
+
+def _result(verdict: str, score: float = 0.0, signals=None, stall: bool = False) -> Dict[str, Any]:
+    return {
+        "stall": stall,
+        "verdict": verdict,
+        "score": score,
+        "signals": list(signals or []),
+        "prompt": CONTINUE_PROMPT if stall else None,
+    }
+
+
+def detect_stall(raw_text: Any, tool_call_count: int = 0) -> Dict[str, Any]:
+    """判定一条 assistant 收尾文本是否「宣布了下一步却没动手」。
+
+    ``tool_call_count > 0`` 一律不判 —— 已经有工具调用的轮次不存在「只说不做」。
+    """
+    if tool_call_count > 0:
+        return _result("had-tools")
+
+    raw = "" if raw_text is None else str(raw_text).strip()
+    if raw == "":
+        return _result("empty")
+
+    text = _strip_noise(raw)
+    if _weighted_length(text) < MIN_WEIGHTED_CHARS:
+        return _result("too-short")
+
+    tail = _tail_of(text)
+
+    # ── 否决 ①：以问句收尾 ────────────────────────────────────────────────
+    if QUESTION_TAIL.search(raw):
+        return _result("question")
+
+    # ── 否决 ②：把决定权交回用户 ──────────────────────────────────────────
+    if _any_match("request", tail):
+        return _result("asked-user")
+
+    has_strong = _any_match("future_strong", tail)
+    has_weak = _any_match("future_weak", tail)
+
+    # ── 否决 ③：明确宣告完成且没有未来时 ──────────────────────────────────
+    if not has_strong and not has_weak and _any_match("done", tail):
+        return _result("already-done")
+
+    # ── 打分 ──────────────────────────────────────────────────────────────
+    score = 0.0
+    signals = []
+
+    if has_strong:
+        score += 2.0
+        signals.append("future-strong")
+    if has_weak:
+        score += 1.5
+        signals.append("future-weak")
+    if _any_match("action_verb", tail):
+        score += 1.0
+        signals.append("action-verb")
+    if COLON_TAIL.search(raw):
+        score += 1.5
+        signals.append("colon-tail")
+    if ELLIPSIS_TAIL.search(raw):
+        score += 0.5
+        signals.append("ellipsis-tail")
+
+    if not has_strong and not has_weak:
+        return _result("no-future-cue", score, signals)
+
+    threshold = THRESHOLD_STRONG if has_strong else THRESHOLD_WEAK_ONLY
+    if score < threshold:
+        return _result("weak-only", score, signals)
+
+    return _result("stall", score, signals, stall=True)
+
+
+# 回灌给模型的续跑提示。
+#
+# 刻意不命令「继续」，而是给出三个出口：执行 / 说明为何不需要执行 / 提出具体问题。
+# 只写「继续」会让模型重复一遍刚才那段计划。
+CONTINUE_PROMPT = "\n".join([
+    "你上一条回复宣布了下一步操作（例如「我先…」「接下来…」「Let me…」），但没有调用任何工具就结束了这一轮。",
+    "请直接执行这个操作。",
+    "如果它其实已经完成，或不需要执行，用一句话说明结论即可，不要重述计划。",
+    "如果需要用户先决定，提出一个具体的问题，不要继续描述待办。",
+])

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hermes-connect-services",
-  "version": "1.0.1",
-  "description": "Bring zcode-ai-connect's four loopback endpoints to hermes: lazy-start them on session start and sync them into hermes' config.yaml as OpenAI-compatible providers.",
+  "version": "1.2.0",
+  "description": "Bring zcode-ai-connect's four loopback endpoints to hermes, and add the missing turn-end gate that re-runs a turn when the model announces a next step but calls no tool.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -23,13 +23,15 @@
   "files": [
     "bin",
     "src",
+    "lib",
     "tests",
     "README.md",
     "LICENSE"
   ],
   "bin": {
     "hermes-connect-ensure": "bin/ensure-services.mjs",
-    "hermes-connect-sync": "bin/sync-hermes-config.mjs"
+    "hermes-connect-sync": "bin/sync-hermes-config.mjs",
+    "hermes-connect-stall-gate": "bin/patch-hermes-stall-gate.mjs"
   },
   "dependencies": {},
   "keywords": [
@@ -39,6 +41,8 @@
     "trae",
     "workbuddy",
     "qoder",
-    "qwenwork"
+    "qwenwork",
+    "stall-guard",
+    "hook"
   ]
 }

package/src/hermes-home.mjs

@@ -0,0 +1,122 @@
+/**
+ * hermes-home.mjs — the two side files a shell hook needs before it will run.
+ *
+ * `config.yaml` alone is not enough to make `hooks.on_session_start` fire:
+ *
+ *   1. shell-hooks-allowlist.json — hermes only runs a hook whose exact
+ *      (event, command) pair is approved. Without it the gateway logs
+ *      "not allowlisted ... — skipped" on every session and the endpoints are
+ *      never started. We append the pair, keeping other hooks' approvals.
+ *
+ *   2. .env NO_PROXY — the OpenAI SDK underneath hermes is httpx, which honours
+ *      HTTP_PROXY. A machine-wide proxy therefore swallows every 127.0.0.1 call
+ *      and the provider dies with ECONNREFUSED. The loopback endpoints must be
+ *      excluded from proxying.
+ */
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ALLOWLIST_FILENAME = 'shell-hooks-allowlist.json';
+const ENV_MARKER_START = '# >>> zcode-ai-connect >>>';
+const ENV_MARKER_END = '# <<< zcode-ai-connect <<<';
+const LOOPBACK = '127.0.0.1,localhost,::1,0.0.0.0';
+
+function readJson(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : { approvals: [] };
+  } catch {
+    return { approvals: [] };
+  }
+}
+
+/**
+ * Approve one (event, command) pair. Idempotent: an identical pair is left
+ * alone so the approved_at timestamp does not churn on every sync.
+ *
+ * @returns {'added' | 'present' | 'skipped-dry-run'}
+ */
+export function allowHook(homeDir, event, command, { dryRun = false } = {}) {
+  const path = join(homeDir, ALLOWLIST_FILENAME);
+  const data = readJson(path);
+  const approvals = Array.isArray(data.approvals) ? data.approvals : [];
+  if (approvals.some((e) => e && e.event === event && e.command === command)) return 'present';
+  if (dryRun) return 'skipped-dry-run';
+
+  if (existsSync(path)) copyFileSync(path, `${path}.bak`);
+  data.approvals = [...approvals, {
+    event,
+    command,
+    approved_at: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    script_mtime_at_approval: null,
+  }];
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  return 'added';
+}
+
+/** Drop our own approvals (used by --remove). Other hooks stay approved. */
+export function revokeHooks(homeDir, commands, { dryRun = false } = {}) {
+  const path = join(homeDir, ALLOWLIST_FILENAME);
+  if (!existsSync(path)) return 0;
+  const data = readJson(path);
+  const approvals = Array.isArray(data.approvals) ? data.approvals : [];
+  const kept = approvals.filter((e) => !(e && commands.includes(e.command)));
+  const removed = approvals.length - kept.length;
+  if (removed === 0 || dryRun) return removed;
+  copyFileSync(path, `${path}.bak`);
+  data.approvals = kept;
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  return removed;
+}
+
+/**
+ * Make sure the loopback hosts bypass the machine proxy. The managed block is
+ * rewritten in place so repeated runs stay byte-stable.
+ *
+ * @returns {'wrote' | 'updated' | 'present' | 'skipped-dry-run'}
+ */
+export function ensureNoProxy(homeDir, { dryRun = false } = {}) {
+  const path = join(homeDir, '.env');
+  const body = [
+    ENV_MARKER_START,
+    `NO_PROXY=${LOOPBACK}`,
+    `no_proxy=${LOOPBACK}`,
+    ENV_MARKER_END,
+  ].join('\n');
+
+  const text = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const start = text.indexOf(ENV_MARKER_START);
+  const end = text.indexOf(ENV_MARKER_END);
+
+  if (start !== -1 && end !== -1 && end > start) {
+    const current = text.slice(start, end + ENV_MARKER_END.length);
+    if (current === body) return 'present';
+    if (dryRun) return 'skipped-dry-run';
+    copyFileSync(path, `${path}.bak`);
+    writeFileSync(path, text.slice(0, start) + body + text.slice(end + ENV_MARKER_END.length), 'utf8');
+    return 'updated';
+  }
+
+  if (dryRun) return 'skipped-dry-run';
+  if (existsSync(path)) copyFileSync(path, `${path}.bak`);
+  const prefix = text === '' ? '' : (text.endsWith('\n') ? '\n' : '\n\n');
+  writeFileSync(path, `${text}${prefix}${body}\n`, 'utf8');
+  return 'wrote';
+}
+
+/** Remove the managed NO_PROXY block (used by --remove). */
+export function removeNoProxy(homeDir, { dryRun = false } = {}) {
+  const path = join(homeDir, '.env');
+  if (!existsSync(path)) return false;
+  const text = readFileSync(path, 'utf8');
+  const start = text.indexOf(ENV_MARKER_START);
+  const end = text.indexOf(ENV_MARKER_END);
+  if (start === -1 || end === -1) return false;
+  if (dryRun) return true;
+  copyFileSync(path, `${path}.bak`);
+  const before = text.slice(0, start).replace(/\n+$/, '\n');
+  const after = text.slice(end + ENV_MARKER_END.length).replace(/^\n+/, '');
+  writeFileSync(path, `${before}${after}`, 'utf8');
+  return true;
+}

package/src/roster.mjs

@@ -16,22 +16,31 @@ import { readEndpoint } from './services.mjs';
  * @returns {Promise<{ baseUrl: string, token: string, port: number, rows: Array<object> }>}
  * @throws when the endpoint is unreachable or answers non-200.
  */
-export async function loadRoster(service, { timeoutMs = 5000 } = {}) {
+export async function loadRoster(service, { timeoutMs = 5000, attempts = 3, delayMs = 1500 } = {}) {
   const { token, port } = await readEndpoint(service);
-  const response = await fetch(`http://127.0.0.1:${port}/v1/models`, {
-    headers: token === '' ? {} : { Authorization: `Bearer ${token}` },
-    signal: AbortSignal.timeout(timeoutMs),
-  });
-  if (!response.ok) {
-    throw new Error(`/v1/models -> ${response.status} (端点没跑?先 serve)`);
+  // A sidecar that `ensure` just spawned answers /healthz before its roster is
+  // populated; reading once here writes a provider with zero models and hermes
+  // then shows nothing under it. Retry the empty answer, not the error.
+  let last = { baseUrl: `http://127.0.0.1:${port}/v1`, token, port, rows: [] };
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const response = await fetch(`http://127.0.0.1:${port}/v1/models`, {
+      headers: token === '' ? {} : { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+      throw new Error(`/v1/models -> ${response.status} (端点没跑?先 serve)`);
+    }
+    const json = await response.json();
+    last = {
+      baseUrl: `http://127.0.0.1:${port}/v1`,
+      token,
+      port,
+      rows: Array.isArray(json?.data) ? json.data : [],
+    };
+    if (last.rows.length > 0 || attempt === attempts) break;
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
   }
-  const json = await response.json();
-  return {
-    baseUrl: `http://127.0.0.1:${port}/v1`,
-    token,
-    port,
-    rows: Array.isArray(json?.data) ? json.data : [],
-  };
+  return last;
 }
 
 /**

package/src/yaml-patch.mjs

@@ -19,6 +19,8 @@
 
 const START = (marker) => `# >>> ${marker} >>>`;
 const END = (marker) => `# <<< ${marker} <<<`;
+/** A child key this suite owns — used to find an orphaned region's real start. */
+const OWNS_CHILD = /^\s{0,4}zc-[A-Za-z0-9._-]+\s*:\s*$/;
 
 /**
  * Replace the managed region inside one top-level mapping key.
@@ -156,6 +158,18 @@ function mappingRegion(lines, keyIndex) {
   return { start: keyIndex + 1, end };
 }
 
+/**
+ * Locate the managed region inside one mapping.
+ *
+ * `orphan` covers the case that actually bites in the field: hermes rewrites
+ * config.yaml from its own model (GUI model switch, `hermes config set`, …) and
+ * drops the opening marker comment while keeping the body and the closing one.
+ * Treating that as "no region" makes the next sync insert a second copy of every
+ * provider — duplicate top-level keys, and PyYAML silently keeps the last. So an
+ * orphan is claimed from its first owned child (`zc-*`) to the stray end marker
+ * and rewritten whole. Starting at the child—not at the mapping—is deliberate:
+ * a hand-written provider above ours must never be swallowed.
+ */
 function findManagedRegion(lines, region, startToken, endToken) {
   let start = -1;
   for (let i = region.start; i < region.end; i += 1) {
@@ -164,7 +178,14 @@ function findManagedRegion(lines, region, startToken, endToken) {
       break;
     }
   }
-  if (start === -1) return null;
+  if (start === -1) {
+    const endIndex = lines.findIndex((line, i) => i >= region.start && i < region.end && line.trim() === endToken);
+    if (endIndex === -1) return null;
+    for (let i = region.start; i < endIndex; i += 1) {
+      if (OWNS_CHILD.test(lines[i])) return { start: i, end: endIndex, orphan: true };
+    }
+    return null;
+  }
   for (let i = start; i < region.end; i += 1) {
     if (lines[i].trim() === endToken) return { start, end: i };
   }

package/tests/probe_stall_gate.py

@@ -0,0 +1,73 @@
+"""给 tests/test-stall-gate.mjs 调用的探针：在宿主进程里跑真实闸门链。
+
+输出 JSON 行，一行一个用例，便于 Node 侧断言。找不到 hermes 时由调用方 SKIP，
+这里不做探测。
+"""
+import json
+import sys
+
+agent_root = sys.argv[1]
+sys.path.insert(0, agent_root)
+
+from agent.turn_stop_gates import _ZC_STALL_MAX_NUDGES, apply_stop_gates  # noqa: E402
+
+
+class FakeAgent:
+    def __init__(self):
+        self._session_messages = []
+        self._turn_file_mutation_paths = set()
+        self.platform = "cli"
+        self.session_id = "stall-gate-test"
+        self.model = "test/model"
+
+    def _interim_content_was_streamed(self, text):
+        return True
+
+    def _emit_interim_assistant_message(self, msg):
+        pass
+
+    def _flush_messages_to_session_db(self, messages, history):
+        pass
+
+    def _emit_diagnostic_status(self, text):
+        pass
+
+
+def run(text, tools=0):
+    agent = FakeAgent()
+    messages = [{"role": "user", "content": "帮我看看那个配置文件"}]
+    for i in range(tools):
+        messages.append({
+            "role": "assistant", "content": "",
+            "tool_calls": [{"id": f"c{i}", "type": "function",
+                            "function": {"name": "read_file", "arguments": "{}"}}],
+        })
+        messages.append({"role": "tool", "content": "ok", "tool_call_id": f"c{i}"})
+    verdict = apply_stop_gates(
+        agent, {"role": "assistant", "content": text},
+        final_response=text, messages=messages, conversation_history=[],
+        pending_verification_response=None, pending_verification_response_previewed=False,
+    )
+    return {
+        "continue_turn": bool(verdict.continue_turn),
+        "nudge_role": messages[-1].get("role") if isinstance(messages[-1], dict) else None,
+        "nudge": messages[-1].get("content") if verdict.continue_turn else None,
+        "fallback": verdict.pending_verification_response,
+    }
+
+
+CASES = [
+    {"name": "announce+colon", "text": "我先检查配置，再修改这里：", "tools": 0, "expect": True},
+    {"name": "done", "text": "已完成全部修改，测试通过。", "tools": 0, "expect": False},
+    {"name": "question", "text": "需要我先确认一下端口状态吗？", "tools": 0, "expect": False},
+    {"name": "handed-back", "text": "接下来需要你决定用哪个方案，我再动手。", "tools": 0, "expect": False},
+    {"name": "had-tools", "text": "我先检查配置，再修改这里：", "tools": 2, "expect": False},
+    {"name": "english", "text": "Let me check the config first, then patch the providers block:", "tools": 0, "expect": True},
+]
+
+print(json.dumps({"max_nudges": _ZC_STALL_MAX_NUDGES}))
+for case in CASES:
+    result = run(case["text"], case["tools"])
+    result["name"] = case["name"]
+    result["expect"] = case["expect"]
+    print(json.dumps(result, ensure_ascii=False))

package/tests/test-stall-gate.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * hermes 侧续跑闸门的回归测试。
+ *
+ * 直接 import 宿主的 `apply_stop_gates`,让**整条闸门链**真实跑一遍 —— late-LSP /
+ * verify-on-stop / pre_verify / kanban 四道闸都会执行,只是触发条件不成立。这比
+ * mock 一个函数名对得上要有说服力:它证明我们的闸门插在了正确的位置,而且返回值
+ * 形状能让 turn loop 接受。
+ *
+ * 本机没装 hermes 时 SKIP(不判失败),这样 CI 上也能通过。
+ *
+ * Run: node hermes-connect-services/tests/test-stall-gate.mjs
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HOME_DIR = process.env.HOME ?? process.env.USERPROFILE ?? '';
+
+console.log('test-stall-gate (hermes)');
+
+function locateAgentRoot() {
+  const homes = [
+    process.env.HERMES_HOME,
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'hermes') : null,
+    join(HOME_DIR, '.hermes'),
+  ].filter(Boolean);
+  for (const home of homes) {
+    const root = join(home, 'hermes-agent');
+    if (existsSync(join(root, 'agent', 'turn_stop_gates.py'))) return { home, root };
+  }
+  return null;
+}
+
+function findPython(home) {
+  const candidates = [
+    process.env.HERMES_PYTHON,
+    join(home, 'tools', 'python-3.14.9+20261021-win32-x64', 'python.exe'),
+    'python',
+    'python3',
+  ].filter(Boolean);
+  for (const exe of candidates) {
+    const probe = spawnSync(exe, ['-c', 'print(1)'], { encoding: 'utf8', timeout: 15000 });
+    if (probe.status === 0 && probe.stdout.trim() === '1') return exe;
+  }
+  return null;
+}
+
+const located = locateAgentRoot();
+if (!located) {
+  console.log('  SKIP 本机没有 hermes（找过 HERMES_HOME / LOCALAPPDATA / ~/.hermes）');
+  process.exit(0);
+}
+
+const gatePath = join(located.root, 'agent', 'turn_stop_gates.py');
+const patched = existsSync(gatePath)
+  && spawnSync(process.execPath, ['-e', `process.exit(require('fs').readFileSync(${JSON.stringify(gatePath)},'utf8').includes('zcode-ai-connect stall-guard')?0:1)`]).status === 0;
+if (!patched) {
+  console.log('  SKIP 补丁未打（先跑 bin/patch-hermes-stall-gate.mjs）');
+  process.exit(0);
+}
+
+const python = findPython(located.home);
+if (!python) {
+  console.log('  SKIP 找不到 Python 解释器');
+  process.exit(0);
+}
+
+const probe = spawnSync(python, [join(HERE, 'probe_stall_gate.py'), located.root], {
+  encoding: 'utf8', timeout: 60000, cwd: located.root,
+});
+if (probe.status !== 0) {
+  console.log(`  FAIL 探针执行失败（status=${probe.status}）`);
+  console.log((probe.stderr || probe.stdout || '').slice(0, 1500));
+  process.exit(1);
+}
+
+const lines = probe.stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+let passed = 0;
+let failed = 0;
+
+const meta = JSON.parse(lines[0]);
+console.log(`  max nudges = ${meta.max_nudges}`);
+
+for (const line of lines.slice(1)) {
+  const r = JSON.parse(line);
+  const ok = r.continue_turn === r.expect;
+  if (ok) {
+    passed += 1;
+    const extra = r.continue_turn ? ` nudge→${r.nudge_role} fallback=${r.fallback ? 'kept' : 'LOST'}` : '';
+    console.log(`  ok   ${r.name} → continue_turn=${r.continue_turn}${extra}`);
+    // 续跑时必须把候选答案留作 fallback,否则预算耗尽时用户什么都看不到
+    if (r.continue_turn && !r.fallback) {
+      failed += 1;
+      passed -= 1;
+      console.log(`       FAIL ${r.name}: pending_verification_response 丢了`);
+    }
+  } else {
+    failed += 1;
+    console.log(`  FAIL ${r.name} → continue_turn=${r.continue_turn} (expect ${r.expect})`);
+  }
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/test-yaml-patch.mjs

@@ -106,4 +106,30 @@ check('survives an unterminated marker (hand-edit gone wrong)', () => {
   assert.match(repaired.text, /# <<< zcode-ai-connect <<</);
 });
 
+check('reclaims an orphaned region whose opening marker hermes ate', () => {
+  // Real-world shape: hermes rewrote config.yaml from its own model and kept the
+  // body plus the closing marker, losing only the opening one. A naive patcher
+  // reads "no region" and inserts a second copy of every provider — duplicate
+  // top-level keys that PyYAML silently collapses.
+  const orphan = [
+    'providers:',
+    '  xiaoxin:',
+    '    name: xiaoxin',
+    '  zc-trae:',
+    '    base_url: "a"',
+    `  # <<< ${MARKER} <<<`,
+    'fallback_providers: []',
+    '',
+  ].join('\n');
+  const fixed = patchManagedBlock(orphan, 'providers', 'zc-trae:\n  base_url: "b"', { marker: MARKER });
+  assert.equal(fixed.action, 'replaced');
+  assert.equal(fixed.text.match(new RegExp(`# >>> ${MARKER} >>>`, 'g')).length, 1);
+  assert.equal(fixed.text.match(new RegExp(`# <<< ${MARKER} <<<`, 'g')).length, 1);
+  // The hand-written provider above ours survives; ours is rewritten.
+  assert.match(fixed.text, / {2}xiaoxin:\n {4}name: xiaoxin/);
+  assert.match(fixed.text, /base_url: "b"/);
+  // And it is stable from now on.
+  assert.equal(patchManagedBlock(fixed.text, 'providers', 'zc-trae:\n  base_url: "b"', { marker: MARKER }).changed, false);
+});
+
 console.log(`\n${passed} passed`);