dsh-skill-hub 0.3.20 → 0.3.21

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()) {
@@ -2928,7 +3013,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 +3075,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 +3195,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 +3408,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 +3433,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 +3731,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 +3871,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 +4284,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 +4351,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 +4427,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,28 +4443,67 @@ 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
 /**
@@ -4719,6 +4906,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). */
@@ -4906,6 +5134,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 {

package/lib/types/protocol/sources.d.ts

@@ -134,6 +134,11 @@ export interface SourceTrashClearResponse {
         name: string;
         error: string;
     }>;
+    /**
+     * `.trash` 里没有对应记录的残留目录（同名技能先后两次入站时，旧记录被覆盖，
+     * 目录却留了下来）。清空回收站时一并回收，这里上报它们的路径；没有则省略。
+     */
+    orphans?: string[];
 }
 /** 项目级技能来源（它们有 workspace 归属，不属于「个人」组）。 */
 export declare function isProjectSource(source: string): boolean;

package/lib/types/reconcile.d.ts

@@ -15,6 +15,10 @@ export interface DisabledReconcileStore {
     listDisabled(): Promise<DisabledSkill[]>;
     addDisabled(entry: DisabledSkill): Promise<void>;
 }
+/** Narrow store view used by the reverse reconcile (adds record removal). */
+export interface DisabledPruneStore extends DisabledReconcileStore {
+    removeDisabled(name: string): Promise<void>;
+}
 /**
  * Add sidecar disabled records for every `.disabled` discovery file that has
  * none yet. Existing records (matched by path or by name) win, so this never
@@ -22,3 +26,23 @@ export interface DisabledReconcileStore {
  * in the diagnostics scan instead). Returns the records added.
  */
 export declare function reconcileDisabledSkills(store: DisabledReconcileStore, home?: string): Promise<DisabledSkill[]>;
+/** 反向对账的结果：修好路径的记录 + 被清掉的死记录。 */
+export interface DisabledPruneResult {
+    /** 记录还在、但 path 指向的文件已不在：已改指向现存的 `.disabled` 文件。 */
+    repaired: DisabledSkill[];
+    /** 文件与禁用占位都已不存在：记录已删除，名字被释放。 */
+    removed: string[];
+}
+/**
+ * 反向对账：`reconcileDisabledSkills` 只处理「磁盘有 `.disabled`、sidecar 没记录」。
+ * 反方向（sidecar 有记录、磁盘上那个文件已经不在了）以前永不清理，于是留下一条
+ * 干掉不掉的记录：`/toggle` 启用会 rename 失败，`/create` 被 409 挡住，`/skill/delete`
+ * 也 rename 失败 —— 名字被永久锁死（issue #16 类，实测 G5）。
+ *
+ * 两种处理，都不动启用态技能：
+ * - 名字在该 root 下仍有 `.disabled` 占位（目录包或扁平形态）→ 把记录指向真实文件；
+ * - 一个都没有 → 删记录，把名字还给用户。
+ *
+ * 只处理合法可写 root 的记录；root 值异常（历史损坏数据）时原样保留，不擅自删。
+ */
+export declare function pruneStaleDisabledSkills(store: DisabledPruneStore, home?: string): Promise<DisabledPruneResult>;

package/lib/types/routes/route-state.d.ts

@@ -54,5 +54,25 @@ export declare const importJobs: Map<string, ImportJob>;
 export declare const IMPORT_JOB_TTL_MS: number;
 export declare const IMPORT_JOB_MAX = 100;
 export declare function gcImportJobs(): void;
-/** Replace one skill directory with a fresh download; restores the old dir on failure. */
-export declare function replaceSkillDir(targetDir: string, download: () => Promise<void>): Promise<void>;
+/**
+ * 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.
+ */
+export declare function replaceInPlace(target: string, download: () => Promise<unknown>): Promise<void>;
+/**
+ * 让位：把一个名字下的「非启用态占位」移入回收站并清掉它的 sidecar 禁用记录。
+ * 只动这两类，**启用的技能一律不碰**：
+ * - 禁用发现文件（`<name>/SKILL.md.disabled` 或 `<name>.md.disabled`，两种形态都认）；
+ * - 同名目录存在但既无 `SKILL.md` 也无 `SKILL.md.disabled`（导入中断/手工删除的空壳）。
+ *
+ * 回收站按名字索引，所以多形态只会记下最后一条的恢复指针；其余的那份会在
+ * 「清空回收站」时被孤儿回收扫掉（见 sourceTrashClear）。
+ *
+ * @returns 被移入回收站的路径列表，没有可让位的东西时 undefined。
+ */
+export declare function retireNamePlaceholders(deps: SkillHubRouteDeps, base: string, name: string): Promise<string[] | undefined>;