dsh-skill-hub 0.3.20 → 0.3.22

package/lib/index.js

@@ -333,13 +333,13 @@ function hydrateMigratedState(migrated) {
 			...typeof item.commitSha === "string" && item.commitSha !== "" ? { commitSha: item.commitSha } : {}
 		});
 	}
-	const trashByName = /* @__PURE__ */ new Map();
+	const trashByPath = /* @__PURE__ */ new Map();
 	if (Array.isArray(migrated.trash)) for (const entry of migrated.trash) {
 		const item = entry;
 		if (item !== null && typeof item === "object" && typeof item.name === "string" && typeof item.path === "string") {
 			const origin = item.origin;
 			const tagIds = item.tagIds;
-			trashByName.set(item.name, {
+			trashByPath.set(item.path, {
 				name: item.name,
 				path: item.path,
 				movedAt: typeof item.movedAt === "number" ? item.movedAt : 0,
@@ -430,7 +430,7 @@ function hydrateMigratedState(migrated) {
 		tagsById,
 		sourcesByRepo,
 		marketSources,
-		trashByName,
+		trashByPath,
 		skillStats,
 		marketStats,
 		collectionOrder,
@@ -691,7 +691,7 @@ var SkillHubStore = class {
 	tagsById = /* @__PURE__ */ new Map();
 	sourcesByRepo = /* @__PURE__ */ new Map();
 	marketSources = [];
-	trashByName = /* @__PURE__ */ new Map();
+	trashByPath = /* @__PURE__ */ new Map();
 	skillStats = void 0;
 	marketStats = void 0;
 	collectionOrder = [];
@@ -717,7 +717,7 @@ var SkillHubStore = class {
 				this.tagsById = state.tagsById;
 				this.sourcesByRepo = state.sourcesByRepo;
 				this.marketSources = state.marketSources;
-				this.trashByName = state.trashByName;
+				this.trashByPath = state.trashByPath;
 				this.skillStats = state.skillStats;
 				this.marketStats = state.marketStats;
 				this.collectionOrder = state.collectionOrder;
@@ -1095,23 +1095,33 @@ var SkillHubStore = class {
 	/** All trashed skills, newest first. */
 	async listTrash() {
 		await this.ensureLoaded();
-		return [...this.trashByName.values()].sort((a, b) => b.movedAt - a.movedAt);
+		return [...this.trashByPath.values()].sort((a, b) => b.movedAt - a.movedAt);
 	}
-	/** One trash entry by skill name (undefined when absent). */
+	/** One trash entry by skill name — the newest when a name has several. */
 	async getTrash(name) {
 		await this.ensureLoaded();
-		return this.trashByName.get(name);
+		let newest;
+		for (const entry of this.trashByPath.values()) {
+			if (entry.name !== name) continue;
+			if (newest === void 0 || entry.movedAt > newest.movedAt) newest = entry;
+		}
+		return newest;
 	}
-	/** Record a trashed skill. */
+	/**
+	* Record a trashed skill, keyed by its trashed path. Keying by name used to
+	* silently drop the previous record when the same name landed in the trash
+	* twice (a re-delete, or the two on-disk discovery forms), orphaning its
+	* directory with nothing left pointing at it.
+	*/
 	async addTrash(entry) {
 		await this.ensureLoaded();
-		this.trashByName.set(entry.name, entry);
+		this.trashByPath.set(entry.path, entry);
 		await this.persist();
 	}
-	/** Remove a trash record (after restore). */
-	async removeTrash(name) {
+	/** Remove a trash record by its trashed path (after restore or permanent clear). */
+	async removeTrash(path) {
 		await this.ensureLoaded();
-		if (!this.trashByName.delete(name)) return;
+		if (!this.trashByPath.delete(path)) return;
 		await this.persist();
 	}
 	/** The persisted usage-statistics checkpoint (undefined until first saved). */
@@ -1163,7 +1173,7 @@ var SkillHubStore = class {
 				...this.tagsById.size > 0 ? { tags: [...this.tagsById.values()] } : {},
 				...this.sourcesByRepo.size > 0 ? { sources: [...this.sourcesByRepo.values()] } : {},
 				...this.marketSources.length > 0 ? { marketSources: [...this.marketSources] } : {},
-				...this.trashByName.size > 0 ? { trash: [...this.trashByName.values()] } : {},
+				...this.trashByPath.size > 0 ? { trash: [...this.trashByPath.values()] } : {},
 				...this.skillStats !== void 0 ? { skillStats: this.skillStats } : {},
 				...this.marketStats !== void 0 ? { marketStats: this.marketStats } : {},
 				...this.collectionOrder.length > 0 ? { collectionOrder: [...this.collectionOrder] } : {},
@@ -1464,7 +1474,7 @@ async function scanDisabledRoot(base) {
 			try {
 				if ((await stat(candidate)).isFile()) paths.push(candidate);
 			} catch {}
-		} else if (name.endsWith(".md.disabled") && name !== "SKILL.md.disabled") paths.push(absolute);
+		} else if (name.endsWith(".md.disabled")) paths.push(absolute);
 	}
 	return paths.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
 }
@@ -1543,7 +1553,9 @@ async function findProjectRoot(cwd) {
 * a defect.
 */
 async function scanDiagnostics(root, home = dshHome()) {
-	return (await mapConcurrent(await listSkillEntries(root, home), 8, async (entry) => {
+	const entries = await listSkillEntries(root, home);
+	const discovered = [];
+	const perEntry = await mapConcurrent(entries, 8, async (entry) => {
 		const found = [];
 		let text;
 		try {
@@ -1575,6 +1587,10 @@ async function scanDiagnostics(root, home = dshHome()) {
 		});
 		const { value } = parsed;
 		const pathName = entry.kind === "directory" ? basename(entry.directory) : basename(entry.path, ".md");
+		discovered.push({
+			path: entry.path,
+			keys: [.../* @__PURE__ */ new Set([pathName, value.name])]
+		});
 		if (value.name !== pathName) found.push({
 			path: entry.path,
 			root,
@@ -1586,7 +1602,65 @@ async function scanDiagnostics(root, home = dshHome()) {
 			reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill`
 		});
 		return found;
-	})).flat();
+	});
+	const owners = /* @__PURE__ */ new Map();
+	for (const item of discovered) for (const key of item.keys) {
+		const list = owners.get(key);
+		if (list === void 0) owners.set(key, [item.path]);
+		else list.push(item.path);
+	}
+	const collisions = [];
+	for (const item of discovered) {
+		const shared = item.keys.filter((key) => (owners.get(key)?.length ?? 0) > 1);
+		if (shared.length === 0) continue;
+		collisions.push({
+			path: item.path,
+			root,
+			reason: `another skill in this root registers the same name (${shared.map((key) => "\"" + key + "\"").join(", ")}); the registry keeps only one of them, so this one is unreachable — delete or rename one of the two`
+		});
+	}
+	return [...perEntry.flat(), ...collisions];
+}
+/**
+* 某个名字在一个 root 下现存的禁用发现文件（两种形态都认），没有则 undefined。
+* 目录包形态优先（`<name>/SKILL.md.disabled`），其次扁平 `<name>.md.disabled`。
+* 单点定义「禁用态在磁盘上长什么样」，避免各处再拼一次路径（issue #16 类）。
+*/
+async function disabledOccupancyIn(base, name) {
+	return (await occupancyOf(base, name)).disabled[0];
+}
+/** stat 一次给出形态；不存在或不可读时 undefined。 */
+async function statKind(path) {
+	try {
+		return (await stat(path)).isDirectory() ? "directory" : "file";
+	} catch {
+		return;
+	}
+}
+/** 读一个名字在某个 skills root 下的全部占位。只读，不修改磁盘。 */
+async function occupancyOf(base, name) {
+	const bundleDir = join(base, name);
+	const bundleSkill = join(bundleDir, "SKILL.md");
+	const bundleDisabled = join(bundleDir, "SKILL.md.disabled");
+	const flatSkill = join(base, name + ".md");
+	const flatDisabled = join(base, name + ".md.disabled");
+	const [bundleSkillKind, bundleDisabledKind, flatSkillKind, flatDisabledKind, bundleDirKind] = await Promise.all([
+		statKind(bundleSkill),
+		statKind(bundleDisabled),
+		statKind(flatSkill),
+		statKind(flatDisabled),
+		statKind(bundleDir)
+	]);
+	const result = {
+		enabled: [],
+		disabled: []
+	};
+	if (bundleSkillKind === "file") result.enabled.push(bundleSkill);
+	if (flatSkillKind === "file") result.enabled.push(flatSkill);
+	if (bundleDisabledKind === "file") result.disabled.push(bundleDisabled);
+	if (flatDisabledKind === "file") result.disabled.push(flatDisabled);
+	if (bundleDirKind === "directory" && bundleSkillKind !== "file" && bundleDisabledKind !== "file") result.bareDir = bundleDir;
+	return result;
 }
 //#endregion
 //#region src/skillfs.ts
@@ -1668,14 +1742,25 @@ async function moveIntoTrash(source) {
 	};
 }
 /**
+* The filesystem entry behind a discovery file: a directory bundle is addressed
+* by its `SKILL.md` (or `SKILL.md.disabled`) and moved as a whole directory, a
+* flat `<name>.md` file is moved as itself. Single definition of that mapping —
+* delete, restore, sync-replace and placeholder retirement must all agree on it,
+* or one of them moves a bundle's discovery file and leaves an empty directory.
+*/
+function trashSourceOf(discoveryPath) {
+	const base = basename(discoveryPath);
+	return base === "SKILL.md" || base === "SKILL.md.disabled" ? dirname(discoveryPath) : discoveryPath;
+}
+/**
 * Move a skill (directory bundle or flat .md file) into the root's trash.
 * The skill stays recoverable: the source is renamed into
 * <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
-* SKILL.md path and moved as a whole directory.
+* SKILL.md (or SKILL.md.disabled) path and moved as a whole directory.
 * @returns the trashed path plus the original path that was moved.
 */
 async function trashSkill(sourcePath) {
-	return moveIntoTrash(basename(sourcePath) === "SKILL.md" ? dirname(sourcePath) : sourcePath);
+	return moveIntoTrash(trashSourceOf(sourcePath));
 }
 /** Restore a trashed skill (directory or flat file) to its original location. */
 async function restoreSkill(entry, home = dshHome()) {
@@ -2306,6 +2391,15 @@ function isLoopbackRequest(request) {
 		return false;
 	}
 }
+/**
+* Fallback fence for a host that mounts no Connection service (unit tests, and
+* any composition serving the webserver alone): the historical literal-loopback
+* check, so a missing service degrades to the previous behaviour instead of an
+* open or a dead route family.
+*/
+function loopbackOnlyFence(request) {
+	return isLoopbackRequest(request) ? void 0 : 403;
+}
 /** One JSON response. */
 function writeJson(res, status, body) {
 	const payload = JSON.stringify(body);
@@ -2778,17 +2872,24 @@ function toDetail(skill) {
 //#region src/routes/helpers.ts
 /**
 * Wrap one handler in the shared request fences. Order matches the
-* original per-handler prologue: loopback trust → HTTP method → master
+* original per-handler prologue: trust fence → HTTP method → master
 * switch → JSON body. The outer catch maps errors onto the JSON error
 * body (preserving RepoFetchError status codes).
+*
+* The trust fence is the host's `/api` model (`deps.fence`) whenever the
+* composition mounts Connection, so a reverse-proxied deployment is judged by
+* the same authorities dsh already trusts; without that service the historical
+* literal-loopback check stands in.
 */
 function createRoute(deps, spec) {
+	const fence = deps.fence ?? loopbackOnlyFence;
 	return {
 		kind: spec.kind ?? "exact",
 		path: spec.path,
 		handler: async (req, res) => {
-			if (!isLoopbackRequest(req)) {
-				writeError(res, 403, "forbidden: loopback-only");
+			const rejection = fence(req);
+			if (rejection !== void 0) {
+				writeError(res, rejection, rejection === 401 ? "unauthorized: browser session required" : "forbidden: untrusted authority");
 				return;
 			}
 			if (!spec.methods.includes(req.method)) {
@@ -2928,7 +3029,18 @@ function catalogRoutes(deps) {
 							writeError(res, 409, "disabled skill path is outside the hub writable roots");
 							return;
 						}
-						trashResult = await moveIntoTrash(disabled.path.endsWith("SKILL.md.disabled") ? dirname(disabled.path) : disabled.path);
+						if (!await pathExists(disabled.path)) {
+							await deps.store.removeDisabled(name);
+							await deps.store.removeSkillFromTags(name);
+							deps.invalidate?.();
+							writeJson(res, 200, {
+								ok: true,
+								name,
+								path: disabled.path
+							});
+							return;
+						}
+						trashResult = await trashSkill(disabled.path);
 					} else {
 						writeError(res, resolved.status, resolved.error);
 						return;
@@ -2979,11 +3091,23 @@ function catalogRoutes(deps) {
 						writeError(res, 404, "skill is not hub-disabled: " + name);
 						return;
 					}
+					let disabledPath = record.path;
+					if (!await pathExists(disabledPath)) {
+						const root = rootOfPath(disabledPath, homeOf(deps));
+						const occupancy = root === void 0 ? void 0 : await disabledOccupancyIn(rootPath(root, homeOf(deps)), name);
+						if (occupancy === void 0) {
+							await deps.store.removeDisabled(name);
+							deps.invalidate?.();
+							writeError(res, 409, "disabled record was stale (its file no longer exists); the record has been removed — retry now");
+							return;
+						}
+						disabledPath = occupancy;
+					}
 					try {
-						await enableSkill(record.path);
+						await enableSkill(disabledPath);
 					} catch (error) {
 						if (error.code === "ENOENT") {
-							writeError(res, 409, "disabled skill file is missing on disk: " + record.path);
+							writeError(res, 409, "disabled skill file is missing on disk: " + disabledPath);
 							return;
 						}
 						throw error;
@@ -3087,8 +3211,13 @@ function catalogRoutes(deps) {
 					writeError(res, 409, "skill name is disabled: re-enable it from the disabled list first");
 					return;
 				}
-				if (await pathExists(join(rootPath(root, homeOf(deps)), name))) {
-					writeError(res, 409, "skill directory already exists on disk: " + name + " (check the discovery diagnostics)");
+				const occupancy = await occupancyOf(rootPath(root, homeOf(deps)), name);
+				if (occupancy.enabled.length > 0) {
+					writeError(res, 409, "a skill file already occupies this name on disk: " + name + " (check the discovery diagnostics)");
+					return;
+				}
+				if (occupancy.disabled.length > 0 || occupancy.bareDir !== void 0) {
+					writeError(res, 409, "name is occupied by a disabled placeholder or an empty directory on disk: " + name + " (check the discovery diagnostics)");
 					return;
 				}
 				const path = await createSkill(root, name, readString(body, "description"), homeOf(deps));
@@ -3295,15 +3424,23 @@ function gcImportJobs() {
 		for (let i = 0; i < finished.length && importJobs.size > 100; i++) importJobs.delete(finished[i][0]);
 	}
 }
-/** Replace one skill directory with a fresh download; restores the old dir on failure. */
-async function replaceSkillDir(targetDir, download) {
-	const backup = join(dirname(targetDir), "." + basename(targetDir) + ".sync-bak-" + Date.now());
-	await rename(targetDir, backup);
+/**
+* Replace whatever currently occupies a skill slot with a fresh download;
+* restores the previous state on failure.
+*
+* `target` is the entry to move aside — a bundle **directory** or a flat
+* `<name>.md` file, whichever the download is replacing (the rename/rm below
+* are form-neutral). The backup is dot-prefixed (discovery skips dot entries),
+* so even a failed cleanup can never register as a duplicate skill.
+*/
+async function replaceInPlace(target, download) {
+	const backup = join(dirname(target), "." + basename(target) + ".sync-bak-" + Date.now());
+	await rename(target, backup);
 	try {
 		await download();
 	} catch (error) {
-		await rename(backup, targetDir).catch((rollbackError) => {
-			console.warn("[dsh-skill-hub] restoring " + targetDir + " from " + backup + " failed:", errorText(rollbackError));
+		await rename(backup, target).catch((rollbackError) => {
+			console.warn("[dsh-skill-hub] restoring " + target + " from " + backup + " failed:", errorText(rollbackError));
 		});
 		throw error;
 	}
@@ -3312,6 +3449,35 @@ async function replaceSkillDir(targetDir, download) {
 		force: true
 	});
 }
+/**
+* 让位：把一个名字下的「非启用态占位」移入回收站并清掉它的 sidecar 禁用记录。
+* 只动这两类，**启用的技能一律不碰**：
+* - 禁用发现文件（`<name>/SKILL.md.disabled` 或 `<name>.md.disabled`，两种形态都认）；
+* - 同名目录存在但既无 `SKILL.md` 也无 `SKILL.md.disabled`（导入中断/手工删除的空壳）。
+*
+* 回收站按名字索引，所以多形态只会记下最后一条的恢复指针；其余的那份会在
+* 「清空回收站」时被孤儿回收扫掉（见 sourceTrashClear）。
+*
+* @returns 被移入回收站的路径列表，没有可让位的东西时 undefined。
+*/
+async function retireNamePlaceholders(deps, base, name) {
+	const occupancy = await occupancyOf(base, name);
+	const sources = [.../* @__PURE__ */ new Set([...occupancy.disabled.map((path) => trashSourceOf(path)), ...occupancy.bareDir !== void 0 ? [occupancy.bareDir] : []])];
+	if (sources.length === 0) return void 0;
+	const trashed = [];
+	for (const source of sources) {
+		const moved = await moveIntoTrash(source);
+		await deps.store.addTrash({
+			name,
+			path: moved.path,
+			movedAt: Date.now(),
+			sourcePath: moved.source
+		});
+		trashed.push(moved.path);
+	}
+	await deps.store.removeDisabled(name);
+	return trashed;
+}
 //#endregion
 //#region src/routes/market.ts
 /**
@@ -3581,29 +3747,17 @@ function marketRoutes(deps) {
 * cancel 取消。从 routes.ts 原样搬出，handler 逻辑不变。
 */
 /**
-* 导入去重只认「已启用」的目录，但磁盘上仍可能躺着一个已禁用的同名占位 ——
-* 禁用只是把 SKILL.md 改名成 SKILL.md.disabled，目录本身还在。这种占位不该
-* 堵住真技能：把它连同禁用记录一起移入回收站让位（issue #16）。
+* 导入让位（issue #16）：磁盘上已有同名占位但**没有启用的技能**时，把占位移入
+* 回收站，把名字让给即将导入的真技能。占位有两种 —— 已禁用的发现文件（目录包或
+* 扁平，后者曾长期漏处理：`clearDisabledPlaceholder` 只认 `<name>` 这个目录，
+* 扁平占位占的是 `<name>.md.disabled`，判据为假，分支根本进不去）和没有 `SKILL.md`
+* 的空壳目录。判据统一走 `occupancyOf`，形态判断集中在 `retireNamePlaceholders`。
 *
-* 只有「禁用记录确实指向 `targetRoot/<name>` 的整目录禁用」才处理，且该目录
-* 必须已经没有 SKILL.md；其余不确定情形一律返回 false，交回原本的「跳过」。
+* 返回 false = 磁盘上有启用的同名技能（真货），一律不动，交回原本的「跳过」。
 */
 async function clearDisabledPlaceholder(deps, targetRoot, name) {
-	const record = await deps.store.getDisabled(name);
-	if (record === void 0) return false;
-	const dir = join(targetRoot, name);
-	const sourceToTrash = record.path.endsWith("SKILL.md.disabled") ? dirname(record.path) : record.path;
-	if (sourceToTrash !== dir) return false;
-	if (await pathExists(join(dir, "SKILL.md"))) return false;
-	const { path: target } = await moveIntoTrash(sourceToTrash);
-	await deps.store.addTrash({
-		name,
-		path: target,
-		movedAt: Date.now(),
-		sourcePath: sourceToTrash
-	});
-	await deps.store.removeDisabled(name);
-	return true;
+	if ((await occupancyOf(targetRoot, name)).enabled.length > 0) return false;
+	return await retireNamePlaceholders(deps, targetRoot, name) !== void 0;
 }
 /** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 function repoImportRoutes(deps) {
@@ -3733,7 +3887,8 @@ function repoImportRoutes(deps) {
 							job.done += 1;
 							continue;
 						}
-						if (await pathExists(join(targetRoot, entry.name))) {
+						const occupancy = await occupancyOf(targetRoot, entry.name);
+						if (occupancy.enabled.length > 0 || occupancy.disabled.length > 0 || occupancy.bareDir !== void 0) {
 							let cleared = false;
 							try {
 								cleared = await clearDisabledPlaceholder(deps, targetRoot, entry.name);
@@ -4145,13 +4300,21 @@ function sourceRoutes(deps) {
 							continue;
 						}
 						const targetDir = join(targetRoot, name);
-						const wasDisabled = await deps.store.getDisabled(name) !== void 0;
-						if (await pathExists(targetDir)) await replaceSkillDir(targetDir, async () => {
-							await downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot);
-						});
-						else await downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot);
-						if (wasDisabled) await rename(join(targetDir, "SKILL.md"), join(targetDir, "SKILL.md.disabled"));
-						else await deps.store.removeDisabled(name);
+						const record = await deps.store.getDisabled(name);
+						const occupancy = await occupancyOf(targetRoot, name);
+						const download = () => downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot);
+						await retireNamePlaceholders(deps, targetRoot, name);
+						const enabled = occupancy.enabled[0];
+						if (enabled !== void 0) await replaceInPlace(trashSourceOf(enabled), download);
+						else await download();
+						if (record !== void 0) {
+							const disabledPath = join(targetDir, "SKILL.md.disabled");
+							await rename(join(targetDir, "SKILL.md"), disabledPath);
+							await deps.store.addDisabled({
+								...record,
+								path: disabledPath
+							});
+						} else await deps.store.removeDisabled(name);
 						await deps.store.mergeSourceManifest(repo, skillManifest(tree, entry.dir), entry.dir);
 						synced.push(name);
 					} catch (error) {
@@ -4204,29 +4367,30 @@ function sourceRoutes(deps) {
 						});
 						continue;
 					}
-					const sourcePath = join(rootPath("user-dsh", home), name);
-					if (rootOfPath(sourcePath, home) === void 0) {
+					const occupancy = await occupancyOf(rootPath("user-dsh", home), name);
+					const existing = occupancy.enabled[0] ?? occupancy.disabled[0] ?? occupancy.bareDir;
+					if (existing === void 0) {
 						failed.push({
 							name,
-							error: "skill path is outside the hub writable roots"
+							error: "skill not found on disk"
 						});
 						continue;
 					}
-					if (!await pathExists(sourcePath)) {
+					if (rootOfPath(existing, home) === void 0) {
 						failed.push({
 							name,
-							error: "skill directory not found"
+							error: "skill path is outside the hub writable roots"
 						});
 						continue;
 					}
 					try {
 						const tagIds = (await deps.store.listTags()).filter((tag) => tag.skillNames.includes(name)).map((tag) => tag.id);
-						const { path } = await trashSkill(sourcePath);
+						const { path, source: trashSource } = await trashSkill(existing);
 						await deps.store.addTrash({
 							name,
 							path,
 							movedAt: Date.now(),
-							sourcePath,
+							sourcePath: trashSource,
 							origin: {
 								repo: source.repo,
 								root: source.root,
@@ -4279,7 +4443,7 @@ function sourceRoutes(deps) {
 				const path = await restoreSkill(entry, home);
 				if (entry.origin !== void 0) await deps.store.addSourceSkill(entry.origin.repo, entry.origin.root, entry.origin.commitSha, entry.origin.ref, name);
 				for (const tagId of entry.tagIds ?? []) await deps.store.addSkillToTag(tagId, name);
-				await deps.store.removeTrash(name);
+				await deps.store.removeTrash(entry.path);
 				deps.invalidate?.();
 				writeJson(res, 200, {
 					ok: true,
@@ -4295,33 +4459,109 @@ function sourceRoutes(deps) {
 				const home = homeOf(deps);
 				const entries = await deps.store.listTrash();
 				const deleted = [];
+				const removedPaths = [];
 				const failed = [];
 				for (const entry of entries) try {
 					await clearTrash(entry, home);
 					await deps.store.removeSkillFromTags(entry.name);
 					deleted.push(entry.name);
+					removedPaths.push(entry.path);
 				} catch (error) {
 					failed.push({
 						name: entry.name,
 						error: errorText(error)
 					});
 				}
-				for (const name of deleted) await deps.store.removeTrash(name);
-				if (deleted.length > 0) deps.invalidate?.();
+				for (const path of removedPaths) await deps.store.removeTrash(path);
+				const orphans = await sweepOrphanTrash(deps, home, failed);
+				if (deleted.length > 0 || orphans.length > 0) deps.invalidate?.();
 				writeJson(res, 200, {
 					ok: true,
 					deleted,
-					failed
+					failed,
+					...orphans.length > 0 ? { orphans } : {}
 				});
 			}
 		}
 	];
 }
+/**
+* 删除两个可写根 `.trash` 下不被任何回收站记录引用的残留目录。
+* 只扫 `.trash` 的直接子项、跳过点开头项，失败项并入 `failed`（保留可重试）。
+*/
+async function sweepOrphanTrash(deps, home, failed) {
+	const referenced = new Set((await deps.store.listTrash()).map((entry) => entry.path));
+	const orphans = [];
+	for (const root of WRITABLE_ROOTS) {
+		const trashDir = join(rootPath(root, home), ".trash");
+		let names;
+		try {
+			names = await readdir(trashDir);
+		} catch {
+			continue;
+		}
+		for (const name of names) {
+			if (name.startsWith(".")) continue;
+			const full = join(trashDir, name);
+			if (referenced.has(full)) continue;
+			try {
+				await rm(full, {
+					recursive: true,
+					force: true
+				});
+				orphans.push(full);
+			} catch (error) {
+				failed.push({
+					name,
+					error: errorText(error)
+				});
+			}
+		}
+	}
+	return orphans;
+}
 //#endregion
 //#region src/routes.ts
 /**
+* Build the family's trust fence from the host's `/api` model.
+*
+* `ctx.connection.requestRejection` is the documented hook for fencing another
+* Web route; with no Connection service (a webserver-only composition, or a
+* unit test) the literal-loopback check stands in, so the fallback is the old
+* behaviour rather than an open route family.
+*
+* The service is read **per request**, not once at mount: plugins start in
+* composition order, so a one-shot read at `apply()` time would latch the
+* fallback whenever this plugin happens to come up before Connection. A
+* persistent absence is almost certainly an upstream composition change rather
+* than a transient startup order, so the first miss fires `onMissing` once —
+* without that signal the fallback would silently reproduce issue #17 after
+* any future upstream rename of the service.
+* @param read - resolves `ctx.connection`, or `undefined` when absent.
+* @param onMissing - called once, the first time the service reads absent.
+* @returns the fence every route in this family runs first.
+*/
+function hostTrustFence(read, onMissing) {
+	let missingReported = false;
+	return (request) => {
+		const connection = read();
+		if (connection === void 0) {
+			if (!missingReported) {
+				missingReported = true;
+				onMissing?.();
+			}
+			return loopbackOnlyFence(request);
+		}
+		try {
+			return connection.requestRejection(request);
+		} catch {
+			return 403;
+		}
+	};
+}
+/**
 * Build every /api/skill-hub route.
-* @param deps - skill registry view + sidecar store.
+* @param deps - skill registry view + sidecar store + trust fence.
 * @returns the exact-path routes plus the family's 404 catch-all.
 */
 function makeRoutes(deps) {
@@ -4719,6 +4959,47 @@ async function reconcileDisabledSkills(store, home = dshHome()) {
 	}
 	return added;
 }
+/**
+* 反向对账：`reconcileDisabledSkills` 只处理「磁盘有 `.disabled`、sidecar 没记录」。
+* 反方向（sidecar 有记录、磁盘上那个文件已经不在了）以前永不清理，于是留下一条
+* 干掉不掉的记录：`/toggle` 启用会 rename 失败，`/create` 被 409 挡住，`/skill/delete`
+* 也 rename 失败 —— 名字被永久锁死（issue #16 类，实测 G5）。
+*
+* 两种处理，都不动启用态技能：
+* - 名字在该 root 下仍有 `.disabled` 占位（目录包或扁平形态）→ 把记录指向真实文件；
+* - 一个都没有 → 删记录，把名字还给用户。
+*
+* 只处理合法可写 root 的记录；root 值异常（历史损坏数据）时原样保留，不擅自删。
+*/
+async function pruneStaleDisabledSkills(store, home = dshHome()) {
+	const result = {
+		repaired: [],
+		removed: []
+	};
+	for (const record of await store.listDisabled()) {
+		let exists = false;
+		try {
+			exists = (await stat(record.path)).isFile();
+		} catch {
+			exists = false;
+		}
+		if (exists) continue;
+		if (!WRITABLE_ROOTS.includes(record.root)) continue;
+		const occupancy = await disabledOccupancyIn(rootPath(record.root, home), record.name);
+		if (occupancy === void 0) {
+			await store.removeDisabled(record.name);
+			result.removed.push(record.name);
+			continue;
+		}
+		const repaired = {
+			...record,
+			path: occupancy
+		};
+		await store.addDisabled(repaired);
+		result.repaired.push(repaired);
+	}
+	return result;
+}
 //#endregion
 //#region src/index.ts
 /** Stable cordis plugin name (matches cordis.patch.yml insert id). */
@@ -4786,7 +5067,7 @@ const CONFIG_FIELDS = [
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 152;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const SKILL_HUB_GUIDANCE = ["本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由仅回环可访问。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。", "The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → \"Skills\" is the management page; the plugin's configuration page (enable / announcement toggles, dot colors, GitHub token, stats window) is registered by the plugin itself on its own page in the Plugins manager (sidebar → 插件 → the plugin; collapsed until you expand the title). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with \"check all\" and \"update all\" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; routes are loopback-only. When the user mentions \"skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill\", this plugin is what they mean — collaborate accordingly."].join("\n\n");
+const SKILL_HUB_GUIDANCE = ["本机已安装 dsh-skill-hub 插件（DSH Web GUI 技能中枢）：设置 →「技能」分区为管理主页；本插件的配置页（启用/公告开关、圆点颜色、GitHub token、统计窗口）在插件管理页——侧边栏「插件」→ 本插件，是本插件自己注册的配置卡片（默认折叠，点标题展开）。能力：完整本地技能目录（项目/自定义/用户/内置全部来源，走官方 ctx.skills 注册表，含第三方 provider）；按来源与自定义分组浏览，分组/来源头部的滑动开关可一键启用/禁用整组（跨组冲突时询问）；市场：内置市场目录（精选仓库一键添加）加自定义仓库源，扫描后勾选安装，每个市场源行显示已装/可更新/上游已删数量，支持「检查全部」与「全部更新」；来源跟踪：从 GitHub 仓库（市场源或直接地址）导入的技能记录上游 repo/commit 快照，可检查更新、选择同步、上游删除时跟进删除（移入回收站可恢复，恢复后保留来源与场景归属）；个人技能（无来源记录）不跟踪；调用次数与最近使用时间统计；查看技能正文；发现诊断；新建技能向导（写入 ~/.dsh/skills 或 ~/.agents/skills）。限制：仅用户级技能（user-dsh/user-agents 根目录）可写，项目/内置/运行时技能只读展示；路由受 dsh 自身的 /api 信任栅栏保护（回环、监听器绑定地址、--trusted-host 声明的 authority，外加浏览器会话认证），因此反代部署下与 GUI 同一套放行规则。用户提到「技能管理 / 技能列表 / 技能开关 / 技能同步 / 技能市场 / 更新技能 / 新建技能」时即指本插件，请据此协作。", "The dsh-skill-hub plugin is installed (the DSH Web GUI skill hub): Settings → \"Skills\" is the management page; the plugin's configuration page (enable / announcement toggles, dot colors, GitHub token, stats window) is registered by the plugin itself on its own page in the Plugins manager (sidebar → 插件 → the plugin; collapsed until you expand the title). Capabilities: full local skill catalog (project / custom / user / bundled roots via the official ctx.skills registry, including third-party providers); browsing by source and custom groups, each group header carrying a sliding switch to enable/disable the whole group in one click (cross-group conflicts prompt the user); market: a built-in catalog of curated repos (one-click add) plus custom repo sources, scan-and-install import, per-source installed / updatable / deleted-upstream badges with \"check all\" and \"update all\" actions; upstream source tracking: skills imported from GitHub repos (market sources or direct URLs) record the repo/commit snapshot, support update checks, selective sync, and follow-up deletion when the upstream removes a skill (moves it into a restorable trash; restoring keeps the source and scene membership); personal skills (no source record) are never tracked; invocation counts and last-used times; skill body inspection; discovery diagnostics; new-skill wizard (writes to ~/.dsh/skills or ~/.agents/skills). Limits: only user-level skills (user-dsh/user-agents roots) are writable; project/bundled/runtime skills are read-only; the routes sit behind dsh's own /api trust fence (loopback, the listener's bind address, any --trusted-host authority, plus browser-session authentication), so a reverse-proxied deployment is judged exactly like the GUI around it. When the user mentions \"skill management / skill list / skill toggle / skill sync / skill market / update skills / new skill\", this plugin is what they mean — collaborate accordingly."].join("\n\n");
 /**
 * Mount the skill hub routes and announcement.
 * @param ctx - host plugin context carrying webServer/skills/systemPrompt/settings.
@@ -4877,6 +5158,7 @@ function apply(ctx, config) {
 			const disposers = makeRoutes({
 				skills: ctx.skills,
 				store,
+				fence: hostTrustFence(() => ctx.get("connection"), () => ctx.logger.warn("[dsh-skill-hub] Connection service absent: routes fall back to literal-loopback; reverse-proxy deployments will 403 until it mounts")),
 				invalidate: () => {
 					providerControl?.invalidate();
 				},
@@ -4906,6 +5188,12 @@ function apply(ctx, config) {
 		} catch (error) {
 			ctx.logger.warn("[dsh-skill-hub] startup disabled-skill reconcile failed", error);
 		}
+		try {
+			const pruned = await pruneStaleDisabledSkills(store, home);
+			if (pruned.repaired.length > 0 || pruned.removed.length > 0) ctx.logger.info(`[dsh-skill-hub] startup pruned disabled records: repaired ${pruned.repaired.length} (${pruned.repaired.map((entry) => entry.name).join(", ") || "-"}), removed ${pruned.removed.length} (${pruned.removed.join(", ") || "-"})`);
+		} catch (error) {
+			ctx.logger.warn("[dsh-skill-hub] startup disabled-record prune failed", error);
+		}
 	})();
 	(async () => {
 		try {