dsh-skill-hub 0.3.19 → 0.3.21

package/lib/index.js

@@ -83,29 +83,30 @@ const HUB_CONFIG_DEFAULTS = {
 	statsScanMinutes: 5
 };
 /**
-* Resolve the effective hub config: saved sidecar overrides win over the
-* cordis composition entry (the web card owns runtime config), missing
-* booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
-* (saved first, then base) only when set. Numeric stats knobs are clamped to
-* their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
+* Fill a raw settings value into the effective hub config: schema defaults for
+* anything missing, and the numeric stats knobs clamped to sane ranges
+* (window ≥ 0, scan interval ≥ 1 minute).
+*
+* There is deliberately no "saved sidecar layer" parameter. Until dsh 0.1.7 the
+* hub kept its own runtime overrides in the sidecar and merged them here; the
+* settings namespace is now the only user layer (`updateConfig` writes through
+* `ctx.settings.mutate`), so a merge against a sidecar layer could never
+* observe anything but `{}` — see the git history of `resolveHubConfig`.
 */
-function resolveHubConfig(saved, base = {}) {
-	const dotModelColor = saved.dotModelColor !== void 0 ? saved.dotModelColor : base.dotModelColor;
-	const dotUserColor = saved.dotUserColor !== void 0 ? saved.dotUserColor : base.dotUserColor;
-	const githubToken = saved.githubToken !== void 0 ? saved.githubToken : base.githubToken;
-	const windowDays = clampNumber(saved.statsWindowDays ?? base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays;
-	const scanMinutes = clampNumber(saved.statsScanMinutes ?? base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes;
+function resolveHubConfig(base = {}) {
+	const windowDays = clampNumber(base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays;
+	const scanMinutes = clampNumber(base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes;
 	return {
-		enabled: saved.enabled ?? base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
-		announceToAgent: saved.announceToAgent ?? base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
-		showUseCount: saved.showUseCount ?? base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
-		showUseTime: saved.showUseTime ?? base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
-		showGroupSummary: saved.showGroupSummary ?? base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
+		enabled: base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
+		announceToAgent: base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
+		showUseCount: base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
+		showUseTime: base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
+		showGroupSummary: base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
 		statsWindowDays: windowDays,
 		statsScanMinutes: scanMinutes,
-		...dotModelColor !== void 0 ? { dotModelColor } : {},
-		...dotUserColor !== void 0 ? { dotUserColor } : {},
-		...githubToken !== void 0 ? { githubToken } : {}
+		...base.dotModelColor !== void 0 ? { dotModelColor: base.dotModelColor } : {},
+		...base.dotUserColor !== void 0 ? { dotUserColor: base.dotUserColor } : {},
+		...base.githubToken !== void 0 ? { githubToken: base.githubToken } : {}
 	};
 }
 /** Clamp a numeric override into a valid value; undefined/invalid stays undefined. */
@@ -332,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,
@@ -429,7 +430,7 @@ function hydrateMigratedState(migrated) {
 		tagsById,
 		sourcesByRepo,
 		marketSources,
-		trashByName,
+		trashByPath,
 		skillStats,
 		marketStats,
 		collectionOrder,
@@ -690,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 = [];
@@ -716,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;
@@ -1094,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). */
@@ -1162,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] } : {},
@@ -1373,6 +1384,26 @@ function rootOfPath(path, home = dshHome()) {
 	}
 }
 //#endregion
+//#region src/concurrency.ts
+/**
+* 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
+* 这里统一为一份（采用 stats 版本的 limit 夹取，调用点 limit≥1 行为不变）。
+*/
+/** Run an async worker over items with a bounded concurrency, preserving index order. */
+async function mapConcurrent(items, limit, worker) {
+	const results = new Array(items.length);
+	let cursor = 0;
+	const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
+		while (cursor < items.length) {
+			const index = cursor;
+			cursor += 1;
+			results[index] = await worker(items[index], index);
+		}
+	});
+	await Promise.all(runners);
+	return results;
+}
+//#endregion
 //#region src/skillfs/scan.ts
 /**
 * Scan one skills root for discovery files: directory bundles (SKILL.md)
@@ -1443,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);
 }
@@ -1475,7 +1506,7 @@ async function readSkillInterface(directory) {
 	const hexColor = (value) => {
 		if (typeof value !== "string") return void 0;
 		const trimmed = value.trim();
-		return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed : void 0;
+		return HEX_COLOR_RE.test(trimmed) ? trimmed : void 0;
 	};
 	const iconPath = (value) => {
 		if (typeof value !== "string" || value.trim() === "") return void 0;
@@ -1515,37 +1546,40 @@ async function findProjectRoot(cwd) {
 	return resolve(cwd);
 }
 /**
-* Scan one writable root for files the provider ignores, so the GUI can
-* show why a skill never appears — a
-* missing frontmatter must be visible, not silent). .disabled files belong
-* to the hub and are skipped.
+* Scan one writable root for files the provider ignores, so the GUI can show
+* why a skill never appears — a missing frontmatter, a name that disagrees
+* with the discovery path, and the like must be visible, not silent. Files the
+* hub itself disabled (`.disabled`) are skipped: they are a toggle state, not
+* a defect.
 */
 async function scanDiagnostics(root, home = dshHome()) {
-	const diagnostics = [];
-	for (const entry of await listSkillEntries(root, home)) {
+	const entries = await listSkillEntries(root, home);
+	const discovered = [];
+	const perEntry = await mapConcurrent(entries, 8, async (entry) => {
+		const found = [];
 		let text;
 		try {
 			text = await readFile(entry.path, "utf8");
 		} catch (error) {
-			if (error.code !== "ENOENT") diagnostics.push({
+			if (error.code !== "ENOENT") found.push({
 				path: entry.path,
 				root,
 				reason: "unreadable: " + errorText(error)
 			});
-			continue;
+			return found;
 		}
 		const parsed = parseFrontmatter(text);
 		if ("error" in parsed) {
 			const fixable = repairFrontmatterFileText(text) !== null;
-			diagnostics.push({
+			found.push({
 				path: entry.path,
 				root,
 				reason: parsed.error,
 				...fixable ? { fixable: true } : {}
 			});
-			continue;
+			return found;
 		}
-		if (repairFrontmatterFileText(text) !== null) diagnostics.push({
+		if (repairFrontmatterFileText(text) !== null) found.push({
 			path: entry.path,
 			root,
 			reason: "frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)",
@@ -1553,18 +1587,80 @@ async function scanDiagnostics(root, home = dshHome()) {
 		});
 		const { value } = parsed;
 		const pathName = entry.kind === "directory" ? basename(entry.directory) : basename(entry.path, ".md");
-		if (value.name !== pathName) diagnostics.push({
+		discovered.push({
+			path: entry.path,
+			keys: [.../* @__PURE__ */ new Set([pathName, value.name])]
+		});
+		if (value.name !== pathName) found.push({
 			path: entry.path,
 			root,
 			reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)`
 		});
-		if (value.description.length < 10) diagnostics.push({
+		if (value.description.length < 10) found.push({
 			path: entry.path,
 			root,
 			reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill`
 		});
+		return found;
+	});
+	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 diagnostics;
+	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
@@ -1624,14 +1720,18 @@ async function enableSkill(disabledPath) {
 	return original;
 }
 /**
-* 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.
+* Move one already-resolved skill (a bundle directory or a flat .md file) into
+* its root's trash as `<root>/.trash/<name>-<timestamp>`.
+*
+* The layout is the restore contract, not an implementation detail:
+* `restoreSkill` renames the entry back and only proves the parent is `.trash`,
+* and `clearTrash` deletes in place. Every producer of a trash entry must go
+* through here — skill delete, the hub-disabled whole-group delete, and repo
+* import's placeholder replacement all move skills for the same recovery flow.
+*
 * @returns the trashed path plus the original path that was moved.
 */
-async function trashSkill(sourcePath) {
-	const source = basename(sourcePath) === "SKILL.md" ? dirname(sourcePath) : sourcePath;
+async function moveIntoTrash(source) {
 	const trashDir = join(dirname(source), ".trash");
 	await mkdir(trashDir, { recursive: true });
 	const target = join(trashDir, basename(source) + "-" + Date.now());
@@ -1641,6 +1741,27 @@ async function trashSkill(sourcePath) {
 		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 (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(trashSourceOf(sourcePath));
+}
 /** Restore a trashed skill (directory or flat file) to its original location. */
 async function restoreSkill(entry, home = dshHome()) {
 	if (basename(dirname(entry.path)) !== ".trash") throw new TypeError("not a trashed skill path: " + entry.path);
@@ -1663,14 +1784,29 @@ function skillFileKind(path) {
 	if (basename(path) === "SKILL.md") return "directory";
 	if (path.endsWith(".md")) return "flat";
 }
-/** Repair one file on disk when its frontmatter is auto-fixable. Returns the new text. */
+/**
+* Repair one file on disk when its frontmatter is auto-fixable. Returns the new text.
+*
+* The write is atomic (sibling temp file + rename), matching the sidecar's
+* persist path: this rewrites a real skill file in place, and a crash midway
+* through a plain write would leave a truncated SKILL.md — exactly the failure
+* the store layer already guards against. The `.tmp` sibling is never picked
+* up by discovery (only `SKILL.md` and `*.md` are scanned).
+*/
 async function fixDiagnosticFile(path, home = dshHome()) {
 	if (rootOfPath(path, home) === void 0) throw new TypeError("not a hub writable skill path: " + path);
 	const repairedText = repairFrontmatterFileText(await readFile(path, "utf8"));
 	if (repairedText === null) throw new TypeError("diagnostic is not auto-fixable: " + path);
 	const parsed = parseFrontmatter(repairedText);
 	if ("error" in parsed) throw new TypeError("repaired frontmatter still invalid: " + parsed.error);
-	await writeFile(path, repairedText, "utf8");
+	const tmp = path + ".tmp";
+	await writeFile(tmp, repairedText, "utf8");
+	try {
+		await rename(tmp, path);
+	} catch (error) {
+		await rm(tmp, { force: true }).catch(() => {});
+		throw error;
+	}
 	return path;
 }
 //#endregion
@@ -1913,15 +2049,27 @@ function etagCacheSet(url, etag, json) {
 	});
 }
 /**
+* When the response shows an exhausted GitHub rate limit, the instant it
+* resets; otherwise undefined. Shared by the repo fetch layer and the plugin's
+* own update check so both agree on what counts as a rate-limit rejection
+* (403/429 + `x-ratelimit-remaining: 0` + a parseable `x-ratelimit-reset`)
+* instead of each re-deriving it from the headers.
+*/
+function rateLimitResetAt(response) {
+	if (response.status !== 403 && response.status !== 429) return void 0;
+	if (response.headers.get("x-ratelimit-remaining") !== "0") return void 0;
+	const reset = response.headers.get("x-ratelimit-reset");
+	if (reset === null) return void 0;
+	const at = /* @__PURE__ */ new Date(Number(reset) * 1e3);
+	return Number.isNaN(at.getTime()) ? void 0 : at;
+}
+/**
 * Build a RepoFetchError; when the response shows an exhausted rate limit,
 * report the reset time instead of a bare HTTP status.
 */
 function fetchError(context, response, fallbackStatus = 502) {
-	const remaining = response.headers.get("x-ratelimit-remaining");
-	const reset = response.headers.get("x-ratelimit-reset");
-	if (response.status === 403 || response.status === 429) {
-		if (remaining === "0" && reset !== null) return new RepoFetchError("github rate limit reached (anonymous quota exhausted); retry after " + (/* @__PURE__ */ new Date(Number(reset) * 1e3)).toLocaleTimeString() + " or set GITHUB_TOKEN", 403);
-	}
+	const resetAt = rateLimitResetAt(response);
+	if (resetAt !== void 0) return new RepoFetchError("github rate limit reached (anonymous quota exhausted); retry after " + resetAt.toLocaleTimeString() + " or set GITHUB_TOKEN", 403);
 	return new RepoFetchError(context + " (HTTP " + response.status + ")", response.status === 404 ? 404 : fallbackStatus);
 }
 /** 是否限流/中断类错误（调用方可直接透出，不再包装）。 */
@@ -1951,10 +2099,9 @@ async function fetchJson(url, fetchImpl, context, headers = apiHeaders()) {
 	}
 }
 /**
-* Load repo metadata and the recursive git tree at the given ref. The meta
-* request always resolves the default branch (used when ref is absent); the
-* tree is fetched at `ref ?? default_branch` so an explicit branch/tag scans
-* the exact same content a later download would fetch.
+* Load one JSON document from the GitHub API, reusing an ETag when the URL was
+* fetched before. `fetchImpl`/`context` exist so callers can stub the transport
+* and shape the error text; the payload is whatever the endpoint returned.
 */
 async function fetchJsonCached(url, fetchImpl, context) {
 	const cached = etagCache.get(url);
@@ -2081,26 +2228,6 @@ async function loadRepoTreeAt(repo, treeSha, fetchImpl = fetch) {
 	return Array.isArray(record.tree) ? record.tree : [];
 }
 //#endregion
-//#region src/concurrency.ts
-/**
-* 并发工具：有界并发的 map。原先 repo.ts 与 stats.ts 各有一份实现，
-* 这里统一为一份（采用 stats 版本的 limit 夹取，调用点 limit≥1 行为不变）。
-*/
-/** Run an async worker over items with a bounded concurrency, preserving index order. */
-async function mapConcurrent(items, limit, worker) {
-	const results = new Array(items.length);
-	let cursor = 0;
-	const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
-		while (cursor < items.length) {
-			const index = cursor;
-			cursor += 1;
-			results[index] = await worker(items[index], index);
-		}
-	});
-	await Promise.all(runners);
-	return results;
-}
-//#endregion
 //#region src/repo/install.ts
 /**
 * 技能目录下载与落地：单文件下载（raw 优先、contents 兜底）、整目录
@@ -2352,9 +2479,14 @@ function isWritableSource(source) {
 }
 /** The resolved hub config a route sees (the shared resolver fills defaults). */
 function configOf(deps) {
-	return resolveHubConfig({}, deps.config?.() ?? {});
+	return resolveHubConfig(deps.config?.() ?? {});
 }
-/** The raw saved config layer a route reports (empty when the owner omits it). */
+/**
+* The raw saved config layer as persisted in the sidecar, reported for display
+* only. Since dsh 0.1.7 the settings namespace is the one user layer, so this
+* is legacy data: nothing writes it any more and the effective config above
+* never merges it.
+*/
 function savedOf(deps) {
 	return deps.saved?.() ?? {};
 }
@@ -2502,9 +2634,8 @@ async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl = fetch) {
 	}
 	if (response.status === 404) return failure("no release published yet");
 	if (!response.ok) {
-		const remaining = response.headers.get("x-ratelimit-remaining");
-		const reset = response.headers.get("x-ratelimit-reset");
-		if ((response.status === 403 || response.status === 429) && remaining === "0" && reset !== null) return failure("github rate limit reached; retry after " + (/* @__PURE__ */ new Date(Number(reset) * 1e3)).toLocaleTimeString() + " or set GITHUB_TOKEN");
+		const resetAt = rateLimitResetAt(response);
+		if (resetAt !== void 0) return failure("github rate limit reached; retry after " + resetAt.toLocaleTimeString() + " or set GITHUB_TOKEN");
 		return failure("GitHub HTTP " + response.status);
 	}
 	let payload;
@@ -2692,7 +2823,8 @@ async function buildCatalog(deps, cwd) {
 		if (iface !== void 0) applyInterface(row, iface);
 		return row;
 	});
-	const diagnostics = [...await scanDiagnostics("user-dsh", home), ...await scanDiagnostics("user-agents", home)];
+	const [userDshDiagnostics, userAgentsDiagnostics] = await Promise.all([scanDiagnostics("user-dsh", home), scanDiagnostics("user-agents", home)]);
+	const diagnostics = [...userDshDiagnostics, ...userAgentsDiagnostics];
 	return {
 		ok: true,
 		pluginVersion: CURRENT_VERSION,
@@ -2881,15 +3013,18 @@ function catalogRoutes(deps) {
 							writeError(res, 409, "disabled skill path is outside the hub writable roots");
 							return;
 						}
-						const sourceToTrash = disabled.path.endsWith("SKILL.md.disabled") ? dirname(disabled.path) : disabled.path;
-						const trashDir = join(dirname(sourceToTrash), ".trash");
-						await mkdir(trashDir, { recursive: true });
-						const target = join(trashDir, basename(sourceToTrash) + "-" + Date.now());
-						await rename(sourceToTrash, target);
-						trashResult = {
-							path: target,
-							source: sourceToTrash
-						};
+						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;
@@ -2940,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;
@@ -3048,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));
@@ -3256,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;
 	}
@@ -3273,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
 /**
@@ -3303,6 +3492,7 @@ function marketRoutes(deps) {
 			}
 			try {
 				const latestTag = await getLatestReleaseTag(source.repo);
+				lastMarketCheck.set(source.repo, now);
 				if (source.ref === void 0) {
 					results.push({
 						...base,
@@ -3313,7 +3503,6 @@ function marketRoutes(deps) {
 					continue;
 				}
 				const latest = await getLatestCommit(source.repo, source.ref);
-				lastMarketCheck.set(source.repo, now);
 				const commitMoved = source.commitSha !== void 0 && latest.commitSha !== source.commitSha;
 				const newRelease = latestTag !== void 0 && latestTag !== source.ref;
 				results.push({
@@ -3358,9 +3547,11 @@ function marketRoutes(deps) {
 					return;
 				}
 				const ref = parsed.ref;
+				const slug = repoSlug(parsed);
 				writeJson(res, 200, {
 					ok: true,
-					repos: await deps.store.addMarketSource(repoSlug(parsed), ref)
+					repo: slug,
+					repos: await deps.store.addMarketSource(slug, ref)
 				});
 			}
 		},
@@ -3540,32 +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 trashDir = join(targetRoot, ".trash");
-	await mkdir(trashDir, { recursive: true });
-	const target = join(trashDir, name + "-" + Date.now());
-	await rename(sourceToTrash, target);
-	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) {
@@ -3695,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);
@@ -4107,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) {
@@ -4166,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,
@@ -4241,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,
@@ -4257,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
 /**
@@ -4681,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). */
@@ -4776,7 +5042,7 @@ function apply(ctx, config) {
 		}
 		return out;
 	};
-	const current = () => resolveHubConfig({}, readConfig());
+	const current = () => resolveHubConfig(readConfig());
 	/** The Settings service, when this deployment mounts it. Absent ⇒ no user layer to read or write. */
 	const settingsOf = () => ctx.get("settings");
 	const store = new SkillHubStore();
@@ -4868,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 {