hermes-connect-services 1.0.0 → 1.1.0

package/README.md

@@ -19,7 +19,25 @@ node hermes-connect-services/bin/sync-hermes-config.mjs
 node hermes-connect-services/bin/sync-hermes-config.mjs --install-hooks
 ```
 
-两步可以合成一次带 `--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
+npm i zcode-trae-connect zcode-workbuddy-connect zcode-qoder-connect zcode-qwenwork-connect hermes-connect-services
+npx hermes-connect-sync --install-hooks
+```
+
+配置文件位置自动探测:
 
 | 平台 | 路径 |
 |---|---|
@@ -105,17 +123,33 @@ model:
 
 **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;换模型名后重跑同步脚本同步上下文窗口。
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-connect-services",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
   "files": [
     "bin",
     "src",
+    "tests",
     "README.md",
     "LICENSE"
   ],

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/services.mjs

@@ -15,12 +15,21 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { mkdir, appendFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-/** Suite root = parent of this directory; overridable for relocation/tests. */
+/**
+ * Suite root = the directory the sibling tools live in.
+ *
+ * In a git checkout that is the repo root; in an npm install the module sits
+ * at `<proj>/node_modules/hermes-connect-services/src/`, so one level up from
+ * `node_modules` is what we want — otherwise every path would gain a second
+ * `node_modules`.
+ */
+const PACKAGE_PARENT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 export const SUITE_ROOT = resolve(
-  process.env.AI_CONNECT_SUITE_ROOT ?? dirname(dirname(dirname(fileURLToPath(import.meta.url)))),
+  process.env.AI_CONNECT_SUITE_ROOT
+  ?? (basename(PACKAGE_PARENT) === 'node_modules' ? dirname(PACKAGE_PARENT) : PACKAGE_PARENT),
 );
 
 export const SERVICES = [
@@ -56,8 +65,39 @@ export const SERVICES = [
 
 export const HOME = process.env.USERPROFILE ?? process.env.HOME ?? '.';
 
-export const cliPath = (service) => join(SUITE_ROOT, service.tool, 'bin', 'cli.mjs');
-export const toolRoot = (service) => join(SUITE_ROOT, service.tool);
+const toolDirCache = new Map();
+
+/**
+ * Where a sibling tool actually lives.
+ *
+ * Three layouts have to work, because this module ships both as a git checkout
+ * and as an npm package:
+ *
+ *   <repo>/hermes-connect-services/ + <repo>/zcode-trae-connect/   (checkout)
+ *   <proj>/node_modules/zcode-trae-connect/                        (npm install)
+ *   <prefix>/node_modules/zcode-trae-connect/                      (npm -g)
+ *
+ * `AI_CONNECT_SUITE_ROOT` wins when set, which is the escape hatch for any
+ * layout not covered above.
+ */
+export function toolDir(service) {
+  const cached = toolDirCache.get(service.id);
+  if (cached) return cached;
+
+  const candidates = [
+    process.env.AI_CONNECT_SUITE_ROOT ? join(process.env.AI_CONNECT_SUITE_ROOT, service.tool) : null,
+    join(SUITE_ROOT, service.tool),
+    join(SUITE_ROOT, 'node_modules', service.tool),
+    join(dirname(SUITE_ROOT), service.tool),
+  ].filter(Boolean);
+
+  const resolved = candidates.find((dir) => existsSync(join(dir, 'bin', 'cli.mjs'))) ?? candidates[1];
+  toolDirCache.set(service.id, resolved);
+  return resolved;
+}
+
+export const cliPath = (service) => join(toolDir(service), 'bin', 'cli.mjs');
+export const toolRoot = (service) => toolDir(service);
 export const stateDir = (service) => join(HOME, service.state);
 
 /** Read `{token, port}` from the tool's state dir, falling back to its default port. */

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/test-yaml-patch.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Regressions for the YAML patcher — the one piece of this module that can
+ * corrupt a user's config, so it gets tests instead of good intentions.
+ *
+ * Run: node hermes-connect-services/tests/test-yaml-patch.mjs
+ */
+import assert from 'node:assert/strict';
+import { patchManagedBlock, readManagedBlock, readManagedChildren } from '../src/yaml-patch.mjs';
+
+const MARKER = 'zcode-ai-connect';
+const sample = [
+  'model:',
+  '  provider: nous',
+  'providers:',
+  '  xiaoxin:',
+  '    name: xiaoxin',
+  '    base_url: https://example.test',
+  'fallback_providers: []',
+  '',
+  '# trailing comment that must survive',
+  'display:',
+  '  language: zh',
+  '',
+].join('\n');
+
+let passed = 0;
+const check = (name, fn) => {
+  fn();
+  passed += 1;
+  console.log(`  ok  ${name}`);
+};
+
+console.log('test-yaml-patch');
+
+check('inserts a managed region inside an existing mapping', () => {
+  const { text, action } = patchManagedBlock(sample, 'providers', 'zc-trae:\n  base_url: "http://127.0.0.1:1/v1"', { marker: MARKER });
+  assert.equal(action, 'inserted');
+  assert.match(text, /providers:\n  xiaoxin:/);
+  assert.match(text, /# >>> zcode-ai-connect >>>\n {2}zc-trae:/);
+  assert.match(text, /fallback_providers: \[\]/);
+});
+
+check('replaces its own region and leaves foreign keys alone', () => {
+  const first = patchManagedBlock(sample, 'providers', 'zc-trae:\n  base_url: "a"', { marker: MARKER }).text;
+  const second = patchManagedBlock(first, 'providers', 'zc-trae:\n  base_url: "b"', { marker: MARKER }).text;
+  assert.match(second, /base_url: "b"/);
+  assert.match(second, /  xiaoxin:/);
+  assert.equal(readManagedChildren(second, 'providers', { marker: MARKER }).length, 1);
+});
+
+check('is idempotent: re-patching identical content writes no change', () => {
+  const once = patchManagedBlock(sample, 'providers', 'zc-trae:\n  base_url: "a"', { marker: MARKER }).text;
+  const twice = patchManagedBlock(once, 'providers', 'zc-trae:\n  base_url: "a"', { marker: MARKER });
+  assert.equal(twice.changed, false);
+  assert.equal(twice.text, once);
+});
+
+check('removal restores the original bytes exactly', () => {
+  const once = patchManagedBlock(sample, 'providers', 'zc-trae:\n  base_url: "a"', { marker: MARKER }).text;
+  const gone = patchManagedBlock(once, 'providers', '', { marker: MARKER }).text;
+  assert.equal(gone, sample);
+});
+
+check('creates the top-level key when it is missing', () => {
+  const { text, action } = patchManagedBlock(sample, 'model_overrides', 'zc-trae:\n  "id":\n    supports_tools: true', { marker: MARKER });
+  assert.equal(action, 'inserted');
+  assert.match(text, /\nmodel_overrides:\n {2}# >>> zcode-ai-connect >>>/);
+  assert.match(text, /display:\n {2}language: zh/);
+});
+
+check('never touches content outside its own mapping', () => {
+  const { text } = patchManagedBlock(sample, 'providers', 'zc-trae:\n  base_url: "a"', { marker: MARKER });
+  assert.equal(readManagedBlock(text, 'model', { marker: MARKER }), '');
+  assert.match(text, /model:\n {2}provider: nous/);
+});
+
+check('readManagedChildren round-trips every provider id', () => {
+  const body = [
+    'zc-trae:',
+    '  base_url: "http://127.0.0.1:39272/v1"',
+    '  models:',
+    '    "a": {}',
+    'zc-workbuddy:',
+    '  base_url: "http://127.0.0.1:39271/v1"',
+  ].join('\n');
+  const once = patchManagedBlock(sample, 'providers', body, { marker: MARKER }).text;
+  const children = readManagedChildren(once, 'providers', { marker: MARKER });
+  assert.deepEqual(children.map((c) => c.key), ['zc-trae', 'zc-workbuddy']);
+  assert.match(children[0].body, /models:\n {4}"a": \{\}/);
+  // Feeding them back unchanged must be a no-op — this is what keeps `--only`
+  // from silently deleting the providers it was not asked about.
+  const twice = patchManagedBlock(once, 'providers', children.map((c) => c.body).join('\n'), { marker: MARKER });
+  assert.equal(twice.text, once);
+});
+
+check('survives an unterminated marker (hand-edit gone wrong)', () => {
+  // A hand-edit that dropped the closing marker leaves an orphan inside the
+  // providers mapping — the next sync must repair it, not stack a second one.
+  const broken = sample.replace(
+    'fallback_providers: []',
+    `  # >>> ${MARKER} >>>\n  zc-trae:\n    base_url: "a"\nfallback_providers: []`,
+  );
+  const repaired = patchManagedBlock(broken, 'providers', 'zc-trae:\n  base_url: "a"', { marker: MARKER });
+  assert.equal(repaired.text.match(new RegExp(`# >>> ${MARKER} >>>`, 'g')).length, 1);
+  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`);