dsh-mcp-panel 0.6.27 → 0.6.29

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.6.29] - 2026-10-19
+
+### Fixed
+
+- **An empty root `cordis.patch.yml` (`[]`) no longer produces invalid YAML after the first MCP server is added (issue #29).** The append writer removes the `[]` sentinel when the file contains only comments plus an empty root list, then appends the first operation. Real rows and comments are untouched; the fresh-file header no longer writes `[]`.
+
+## [0.6.28] - 2026-10-18
+
+### Fixed
+
+- **Build tooling and the subprocess seam are no longer installed twice.** `tsdown`/`typescript` moved to devDependencies, and `@deepseek-ai/dsh-subprocess` moved to peer+dev so the host copy is the only runtime copy. A single checker install no longer pulls a 47 MB build chain through this package.
+
 ## [0.6.27] - 2026-10-18
 
 ### Fixed

package/README-es.md

@@ -44,7 +44,7 @@ dsh plugin --profile <name> add dsh-mcp-panel
 
 Este plugin forma parte de la [familia de plugins DSH](https://github.com/PerryLink) (más de 40, todos Apache-2.0). Si te resulta útil, **dale una estrella**: no desbloquea nada, pero ayuda a que la siguiente persona lo encuentre antes.
 
-*English:* part of a 40+ plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
+*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
 
 ## What is dsh-mcp-panel?
 
@@ -62,7 +62,7 @@ Cliente oficial = puente, este plugin = consola: lee el estado por el seam `mcp/
 
 | Superficie | Estado |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (verificado el 2026-09-25): las dos reglas de typecheck en verde sobre la cara `0.1.6-alpha.2` (este repo es el canario de la familia: no aparecieron errores nuevos), 174 pruebas y la cadena completa de puertas (typecheck / typecheck:ci / test / build / verify / package). La re-verificación de `writePatch` se sostiene en esta línea. Línea base anterior: `dsh-v0.1.7-alpha.1` (verificado el 2026-09-16). |
+| Harness | DeepSeek Harness `dsh-v0.2.1-rc.2` (verificado 2026-10-18): `engines.dsh >=0.2.1-0 <0.3.0`; las rutas de compatibilidad P0 tienen pruebas de regresión. |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 | Plataformas | Web GUI (doble cara: host + navegador) |
 | Modelo | Cualquiera (el panel es de solo lectura; solo la salida de `/mcp` es legible por el modelo) |
@@ -335,7 +335,9 @@ Este proyecto es uno de los **87 plugins activamente mantenidos** de DeepSeek Ha
 
 </details>
 
-</details>## License
+</details>
+
+## License
 
 [Apache License 2.0](LICENSE) © 2026 colaboradores de dsh-mcp-panel
 

package/README-hi.md

@@ -42,9 +42,9 @@ dsh plugin --profile <name> add dsh-mcp-panel
 
 ## ⭐ 如果它帮到了你
 
-यह प्लगइन [DSH प्लगइन परिवार](https://github.com/PerryLink) का हिस्सा है (40+ प्लगइन, सभी Apache-2.0)। अगर यह उपयोगी लगे, तो **एक स्टार दें** — इससे कोई सुविधा अनलॉक नहीं होती, पर अगला व्यक्ति इसे खोज में आसानी से पा लेता है।
+यह प्लगइन [DSH प्लगइन परिवार](https://github.com/PerryLink) का हिस्सा है (95 प्लगइन, सभी Apache-2.0)। अगर यह उपयोगी लगे, तो **एक स्टार दें** — इससे कोई सुविधा अनलॉक नहीं होती, पर अगला व्यक्ति इसे खोज में आसानी से पा लेता है।
 
-*English:* part of a 40+ plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
+*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
 
 ## What is dsh-mcp-panel?
 
@@ -62,7 +62,7 @@ DeepSeek Harness के आधिकारिक MCP क्लाइंट क
 
 | सतह | स्थिति |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (2026-09-25 को सत्यापित): `0.1.6-alpha.2` dev/test फ़ेस पर दोनों typecheck रूलर हरे (यह रेपो परिवार का कैनरी है — कोई नई त्रुटि नहीं आई), 174 टेस्ट, और पूर्ण गेट शृंखला (typecheck / typecheck:ci / test / build / verify / package)। `writePatch` का पुनः-सत्यापन इस लाइन पर मान्य है। पिछली आधार रेखा: `dsh-v0.1.7-alpha.1` (2026-09-16 को सत्यापित)। |
+| हारनेस | DeepSeek Harness `dsh-v0.2.1-rc.2` (2026-10-18 सत्यापित): `engines.dsh >=0.2.1-0 <0.3.0`; P0 संगतता पथ के रिग्रेशन परीक्षण हैं। |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 | प्लेटफ़ॉर्म | Web GUI (दोहरा चेहरा: host + browser) |
 | मॉडल | कोई भी (पैनल रीड-ओनली है; केवल `/mcp` आउटपुट मॉडल-पठनीय है) |
@@ -335,7 +335,9 @@ pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build && pn
 
 </details>
 
-</details>## License
+</details>
+
+## License
 
 [Apache License 2.0](LICENSE) © 2026 dsh-mcp-panel योगदानकर्ता
 

package/README-pt.md

@@ -44,7 +44,7 @@ dsh plugin --profile <name> add dsh-mcp-panel
 
 Este plugin faz parte da [família de plugins DSH](https://github.com/PerryLink) (mais de 40, todos Apache-2.0). Se for útil, **deixe uma estrela**: não desbloqueia nada, mas ajuda a próxima pessoa a encontrá-lo.
 
-*English:* part of a 40+ plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
+*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
 
 ## What is dsh-mcp-panel?
 
@@ -62,7 +62,7 @@ Cliente oficial = ponte, este plugin = console: leia o status pelo seam `mcp/sta
 
 | Superfície | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (verificado em 2026-09-25): as duas réguas de typecheck verdes na face `0.1.6-alpha.2` (este repositório é o canário da família: nenhum erro novo apareceu), 174 testes e a cadeia completa de portas (typecheck / typecheck:ci / test / build / verify / package). A re-verificação do `writePatch` vale nesta linha. Linha de base anterior: `dsh-v0.1.7-alpha.1` (verificado em 2026-09-16). |
+| Harness | DeepSeek Harness `dsh-v0.2.1-rc.2` (verificado 2026-10-18): `engines.dsh >=0.2.1-0 <0.3.0`; os caminhos de compatibilidade P0 têm testes de regressão. |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 | Plataformas | Web GUI (duas faces: host + navegador) |
 | Modelo | Qualquer (o painel é somente leitura; só a saída de `/mcp` é legível pelo modelo) |
@@ -335,7 +335,9 @@ Este projeto é um dos **87 plugins ativamente mantidos** do DeepSeek Harness da
 
 </details>
 
-</details>## License
+</details>
+
+## License
 
 [Apache License 2.0](LICENSE) © 2026 contribuidores do dsh-mcp-panel
 

package/README-zh.md

@@ -44,9 +44,9 @@ dsh plugin --profile <name> add dsh-mcp-panel
 
 ## ⭐ 如果它帮到了你
 
-这个插件是 [DSH 插件家族](https://github.com/PerryLink)的一员（40+ 个，全部 Apache-2.0）。如果你在用，**给个 star** —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。
+这个插件是 [DSH 插件家族](https://github.com/PerryLink)的一员（95 个，全部 Apache-2.0）。如果你在用，**给个 star** —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。
 
-*English:* part of a 40+ plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
+*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
 
 ## What is dsh-mcp-panel?
 
@@ -64,7 +64,7 @@ dsh plugin --profile <name> add dsh-mcp-panel
 
 | 维度 | 状态 |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1`（2026-09-24 核验）：双 typecheck 尺子在 `0.1.6-alpha.2` dev/test 面上双绿（本仓是全族金丝雀，抬线未暴露新错误）、174 项测试、全量门禁链（typecheck / typecheck:ci / test / build / verify / package）。`writePatch` 的写入复验断言在该线上成立。上一基线：`dsh-v0.1.7-alpha.1`（2026-09-16 已核验）。 |
+| 宿主 | DeepSeek Harness `dsh-v0.2.1-rc.2`（2026-10-18 验证）：`engines.dsh >=0.2.1-0 <0.3.0`；P0 兼容路径已有回归测试。 |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 | 平台 | Web GUI（双面：Host + 浏览器） |
 | 模型 | 任意（面板只读；仅 `/mcp` 输出对模型可见） |
@@ -337,7 +337,9 @@ pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build && pn
 
 </details>
 
-</details>## License
+</details>
+
+## License
 
 [Apache License 2.0](LICENSE) © 2026 dsh-mcp-panel contributors
 

package/README.md

@@ -45,9 +45,9 @@ dsh plugin --profile <name> add dsh-mcp-panel
 
 ## ⭐ 如果它帮到了你
 
-这个插件是 [DSH 插件家族](https://github.com/PerryLink)的一员（40+ 个，全部 Apache-2.0）。如果你在用，**给个 star** —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。
+这个插件是 [DSH 插件家族](https://github.com/PerryLink)的一员（95 个，全部 Apache-2.0）。如果你在用，**给个 star** —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。
 
-*English:* part of a 40+ plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
+*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, **a star helps the next person find it** — nothing is gated behind it.
 
 
 ## What is dsh-mcp-panel?
@@ -66,7 +66,7 @@ Official client = bridge, this plugin = console: read status through the `mcp/st
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (verified 2026-09-25): dual typecheck rulers green on the `0.1.6-alpha.2` dev/test face (this repo is the family's canary — no new errors surfaced), 174 tests, and the full gate chain (typecheck / typecheck:ci / test / build / verify / package). The `writePatch` re-verification assertion stands on this line. Previous baseline: `dsh-v0.1.7-alpha.1` (verified 2026-09-16). |
+| Harness | DeepSeek Harness `dsh-v0.2.1-rc.2` (verified 2026-10-18): `engines.dsh >=0.2.1-0 <0.3.0`; the P0 compatibility paths have regression tests. |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 | Platforms | Web GUI (dual-face: host + browser) |
 | Model | Any (the panel is read-only; only `/mcp` output is model-readable) |

package/lib/index.js

@@ -842,7 +842,7 @@ const INITIALIZE_PROTOCOL_VERSION = "2024-11-05";
 * advertised version tracks the package version. */
 const PROBE_CLIENT_INFO = {
 	name: "dsh-mcp-panel",
-	version: "0.6.27"
+	version: "0.6.29"
 };
 /** Display cap for server-reported name/version fields in probe details. */
 const DISPLAY_LIMIT = 80;
@@ -1947,7 +1947,6 @@ const BACKUP_SUFFIX = ".bak-";
 /** Fresh-file header when the patch layer does not exist yet. */
 const FRESH_FILE_HEADER = `# dsh-mcp-panel managed patch layer (created by the MCP console).
 # Operations are APPEND-ONLY: the console never rewrites existing content.
-[]
 `;
 /**
 * Copy the current patch file to a timestamped backup, append one fragment,
@@ -1988,11 +1987,32 @@ async function appendPatchFragment(filePath, fragment, backupCount) {
 		bytes
 	};
 }
+/**
+* A patch layer that only contains an empty root list (`[]`) plus comments is
+* not a valid prefix for an appended operation: `[]` ends the YAML document.
+* Removing that one sentinel is the only rewrite this module performs; any
+* real row keeps the append-only guarantee.
+*/
+function stripEmptyRootList(content) {
+	const lines = content.split("\n");
+	let emptyRoot = false;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		if (trimmed === "[]") {
+			emptyRoot = true;
+			continue;
+		}
+		return content;
+	}
+	if (!emptyRoot) return content;
+	return lines.filter((line) => line.trim() !== "[]").join("\n");
+}
 /** Append one fragment with surrounding newlines, normalizing a trailing newline first. */
 async function appendFragment(filePath, fragment) {
-	const content = await readFile(filePath, "utf8");
-	const normalized = content.endsWith("\n") ? content : `${content}\n`;
-	const block = normalized.endsWith("\n\n") ? `${fragment}\n` : `\n${fragment}\n`;
+	const base = stripEmptyRootList(await readFile(filePath, "utf8"));
+	const normalized = base.endsWith("\n") ? base : `${base}\n`;
+	const block = normalized.endsWith("\n\n") || normalized === "" ? `${fragment}\n` : `\n${fragment}\n`;
 	await writeFile(filePath, `${normalized}${block}`, "utf8");
 	if (!(await readFile(filePath, "utf8")).includes(fragment)) throw new Error("dsh-mcp-panel: the appended patch fragment could not be read back — the write is suspect; inspect the file before retrying");
 	return Buffer.byteLength(block, "utf8");

package/lib/types/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBlE"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBlE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-panel",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "description": "MCP management console for the official DeepSeek Harness MCP client: /mcp command with health diagnostics and pipeline trial calls, a Settings MCP tab with server CRUD (append-only profile-patch fragments, approval-gated writes with automatic backups), a tool trial console over the official tool pipeline, connection status, reconnect counts and sanitized tool inventory, plus an optional Streamable HTTP probe.",
   "repository": {
     "type": "git",
@@ -133,7 +133,8 @@
     "@deepseek-ai/dsh-client-connection": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0",
     "@deepseek-ai/dsh-api-remotes": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0",
     "@deepseek-ai/dsh-client-locale": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0"
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0",
+    "@deepseek-ai/dsh-subprocess": ">=0.2.1-0 <0.3.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-client-connection": {
@@ -150,31 +151,28 @@
     }
   },
   "dependencies": {
-    "tsdown": "^0.23.0",
-    "typescript": "^7.0.0",
-    "zod": "^4.6.5",
-    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.1"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.5-alpha.1",
     "@deepseek-ai/cordis-plugin-include": "^1.0.10-alpha.1",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.6-alpha.1",
-    "@deepseek-ai/dsh-agent": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-api-remotes": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-connection": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-commands": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-home-paths": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-cmdline": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
     "@deepseek-ai/schemastery": "^3.18.5-alpha.1",
     "@types/node": "^22.20.3",
     "@types/react": "19.3.0",
@@ -183,7 +181,10 @@
     "oxlint": "1.83.0",
     "react": "19.3.0",
     "react-dom": "19.2.8",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.0",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-rc.2"
   },
   "scripts": {
     "build": "node scripts/prepare.mjs",

package/src/probe.ts

@@ -56,7 +56,7 @@ const INITIALIZE_PROTOCOL_VERSION = '2024-11-05'
 /** MCP clientInfo facts; protocol constants, not configuration. Exported so the
  * version-consistency tripwire (`tests/version.spec.ts`) can assert the
  * advertised version tracks the package version. */
-export const PROBE_CLIENT_INFO = { name: 'dsh-mcp-panel', version: '0.6.27' }
+export const PROBE_CLIENT_INFO = { name: 'dsh-mcp-panel', version: '0.6.29' }
 
 /** One settled probe: outcome status plus a sanitized one-line detail. */
 export interface ProbeOutcome {

package/src/write.ts

@@ -20,7 +20,6 @@ const BACKUP_SUFFIX = '.bak-'
 /** Fresh-file header when the patch layer does not exist yet. */
 const FRESH_FILE_HEADER = `# dsh-mcp-panel managed patch layer (created by the MCP console).
 # Operations are APPEND-ONLY: the console never rewrites existing content.
-[]
 `
 
 /**
@@ -63,11 +62,31 @@ export async function appendPatchFragment(
   return { backupPath, bytes }
 }
 
+/**
+ * A patch layer that only contains an empty root list (`[]`) plus comments is
+ * not a valid prefix for an appended operation: `[]` ends the YAML document.
+ * Removing that one sentinel is the only rewrite this module performs; any
+ * real row keeps the append-only guarantee.
+ */
+function stripEmptyRootList(content: string): string {
+  const lines = content.split('\n')
+  let emptyRoot = false
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    if (trimmed === '[]') { emptyRoot = true; continue }
+    return content
+  }
+  if (!emptyRoot) return content
+  return lines.filter(line => line.trim() !== '[]').join('\n')
+}
+
 /** Append one fragment with surrounding newlines, normalizing a trailing newline first. */
 async function appendFragment(filePath: string, fragment: string): Promise<number> {
   const content = await readFile(filePath, 'utf8')
-  const normalized = content.endsWith('\n') ? content : `${content}\n`
-  const block = normalized.endsWith('\n\n') ? `${fragment}\n` : `\n${fragment}\n`
+  const base = stripEmptyRootList(content)
+  const normalized = base.endsWith('\n') ? base : `${base}\n`
+  const block = normalized.endsWith('\n\n') || normalized === '' ? `${fragment}\n` : `\n${fragment}\n`
   await writeFile(filePath, `${normalized}${block}`, 'utf8')
   // Readback: the appended block must survive exactly as written — a partial
   // write would otherwise surface as a "written" success (issue #27 hardening).