@khorsheed/dsh-capability-catalog 0.1.95

package/lib/index.js

@@ -0,0 +1,4022 @@
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { inflateRawSync } from "node:zlib";
+import { existsSync, watch } from "node:fs";
+import { createScope } from "@deepseek-ai/dsh-scope";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/capabilities.js
+/**
+* The capability FINGERPRINT: a canonical form of a catalog snapshot, and the
+* sha256 over it.
+*
+* A catalog snapshot is a listing — ordered by registration, worded for a
+* human, stamped with file mtimes. None of that is the capability face. Two
+* instances that register the same tools in a different order have the same
+* capabilities; an instance whose tool description was reworded has the same
+* capabilities; an instance whose tool gained a parameter does NOT. This
+* module decides which of those differences count, so a condition document
+* can claim `preset: X` and something can check the claim instead of
+* believing it.
+*
+* What enters the fingerprint, and why:
+*
+* | Row | Fields | Left out |
+* |---|---|---|
+* | skill | `name`, `source`, `body` (sha256 of SKILL.md) | `description`, `whenToUse`, `provider`, `updatedAt` |
+* | tool | `name`, `channel`, `parameters` | `description`, `confidence`, `owner` |
+* | mcpServer | `name`, `tools` (its tool names) | tool count (derived) |
+* | channel | the names | the counts (derived from the rows) |
+*
+* The exclusions are deliberate and each one is a claim: **prose is not a
+* capability**. Rewording a tool description, or a skill's routing blurb,
+* changes what the model reads but not what it can do — and a factor that
+* moves when someone fixes a typo is a factor nobody can hold still across a
+* run. A skill's BODY is the opposite: it is the procedure the model
+* executes, so it enters as a sha. `updatedAt` is a filesystem fact, not a
+* capability: touching a file must not mint a new subject.
+*
+* Determinism is the whole product. Every list is sorted by name, and the
+* digest is taken over canonical JSON (sorted keys, no whitespace), so the
+* same capability face hashes the same on two machines and in two processes.
+* @module @khorsheed/dsh-capability-catalog/capabilities
+*/
+/** Prefix of the human-facing capability tag (`caps:<sha256>`). */
+const CAPS_TAG_PREFIX = "caps:";
+/**
+* Canonical JSON: object keys sorted (code-unit order), no whitespace, arrays
+* in document order. Two documents differing only in key order canonicalize
+* alike.
+*
+* Deliberately duplicated rather than imported from `@khorsheed/dsh-eval`:
+* community plugins never depend on siblings, and the two copies are pinned
+* against each other by the eval contract tests that consume a `caps:` tag.
+* @param value - any JSON value.
+* @returns its canonical serialization.
+*/
+function canonicalJson(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const obj = value;
+	return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
+}
+/** Sort by `name`, code-unit order (the one ordering rule of this module). */
+function byName(rows) {
+	return [...rows].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+/**
+* Project a snapshot onto its canonical capability face.
+*
+* Pure and total: it reads nothing but the snapshot, and a row missing an
+* optional field contributes `null` rather than disappearing — a tool with no
+* parameter schema is a different capability from one whose schema is `{}`,
+* and both are different from the tool being absent.
+* @param snapshot - a catalog snapshot (its own `sha` field, if any, is ignored).
+* @returns the canonical form the digest is taken over.
+*/
+function canonicalCapabilities(snapshot) {
+	const tools = byName(snapshot.tools);
+	return {
+		skills: byName(snapshot.skills).map((skill) => ({
+			name: skill.name,
+			source: skill.source,
+			body: skill.bodySha ?? null
+		})),
+		tools: tools.map((tool) => ({
+			name: tool.name,
+			channel: tool.channel,
+			parameters: tool.parameters ?? null
+		})),
+		mcpServers: byName(snapshot.mcpServers).map((server) => ({
+			name: server.name,
+			tools: tools.filter((tool) => tool.serverName === server.name).map((tool) => tool.name)
+		})),
+		channels: [...snapshot.channels].map((channel) => channel.channel).sort()
+	};
+}
+/**
+* The capability hash: sha256 hex of the canonical form's canonical JSON.
+* @param snapshot - a catalog snapshot.
+* @returns the 64-hex digest.
+*/
+function hashOf(snapshot) {
+	return createHash("sha256").update(canonicalJson(canonicalCapabilities(snapshot))).digest("hex");
+}
+/**
+* The human-facing tag form of a capability hash.
+* @param sha - a sha256 hex digest (or the hash of a snapshot).
+* @returns `caps:<sha>`.
+*/
+function capsTag(sha) {
+	return `${CAPS_TAG_PREFIX}${sha}`;
+}
+/** sha256 hex of a skill body, the form {@link CanonicalSkill.body} carries. */
+function hashSkillBody(content) {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+//#endregion
+//#region lib/types/skills.js
+/**
+* Skill collection: project `ctx.skills.snapshot()` output into catalog rows,
+* decode the frontmatter `metadata.credentials` declaration (the plugin's own
+* convention), and load per-skill detail on demand via `ctx.skills.get()`.
+*
+* The registry already performs root discovery, de-duplication, and rank
+* resolution; this module only projects the winning summaries onto wire rows
+* and reads credentials state through the optional `ctx.credentials` service.
+* @module @khorsheed/dsh-capability-catalog/skills
+*/
+/** POSIX identifier — the minimal shape a credential reference name must match
+* (the env keys the catalog handles are a strict subset of this). */
+const CREDENTIAL_REF_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Skill `source` buckets that resolve to a local file the catalog may delete.
+* Built-in / plugin-provided skills (`runtime`, `bundled`, official `skill-badge`)
+* have no catalog-owned file and are never deletable. */
+const DELETABLE_SOURCES = /* @__PURE__ */ new Set([
+	"user-dsh",
+	"user-agents",
+	"project-dsh",
+	"project-agents",
+	"custom"
+]);
+/** Decode `metadata.credentials` as an array of { key, label? }. */
+function decodeCredentialDecls(metadata) {
+	const raw = metadata?.credentials;
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) continue;
+		const key = item.key;
+		if (typeof key !== "string" || key.length === 0) continue;
+		const label = item.label;
+		out.push({
+			key,
+			...typeof label === "string" ? { label } : {}
+		});
+	}
+	return out;
+}
+/** Scan a skill body for env-var references (`$X`, `process.env.X`, `env['X']`,
+* `{{env:X}}`) and surface them as generic credential decls — envs are not
+* assumed to be API keys; they may be tokens, ids, or any secret. */
+function decodeEnvDecls(content) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	const add = (raw) => {
+		if (raw === void 0) return;
+		const key = raw.replace(/^\$\{?/, "").replace(/\}?$/, "").trim();
+		if (!/^[A-Z][A-Z0-9_]*$/.test(key) || seen.has(key)) return;
+		seen.add(key);
+		out.push({ key });
+	};
+	for (const p of [
+		/\$\{?([A-Z][A-Z0-9_]*)\}?/g,
+		/process\.env\.([A-Z][A-Z0-9_]*)/g,
+		/env\[\s*['"]?([A-Z][A-Z0-9_]+)['"]?\s*\]/g,
+		/\{\{\s*env:([A-Z][A-Z0-9_]*)\s*\}\}/g
+	]) {
+		let m;
+		while ((m = p.exec(content)) !== null) add(m[1]);
+	}
+	return out;
+}
+/** Merge metadata.credentials and env-derived decls, deduped by key. */
+function mergeCredentialDecls(metadataDecls, envDecls) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const decl of [...metadataDecls, ...envDecls]) {
+		const existing = byKey.get(decl.key);
+		byKey.set(decl.key, existing !== void 0 && existing.label !== void 0 ? existing : decl);
+	}
+	return [...byKey.values()];
+}
+/** Project one summary onto a wire skill row. */
+function skillRowFrom(summary, updatedAt, bodySha) {
+	return {
+		name: summary.name,
+		description: summary.description,
+		source: summary.source,
+		provider: summary.provider,
+		modelInvocable: summary.invocation.modelInvocable,
+		userInvocable: summary.invocation.userInvocable,
+		...summary.whenToUse !== void 0 ? { whenToUse: summary.whenToUse } : {},
+		...updatedAt !== void 0 ? { updatedAt } : {},
+		...bodySha !== void 0 ? { bodySha } : {}
+	};
+}
+/** Last-modified time (epoch ms) of a skill's body: the SKILL.md in its bundle
+* directory for a directory skill, else the directory itself. Remote
+* (`url`/`opaque`) skills have no local file and yield `undefined`. */
+async function skillUpdatedAt(summary) {
+	const base = summary.resourceBase;
+	if (base?.kind !== "directory" || base.path === void 0) return void 0;
+	try {
+		return (await stat(join(base.path, "SKILL.md")).catch(() => void 0) ?? await stat(base.path)).mtimeMs;
+	} catch {
+		return;
+	}
+}
+/** Resolve the optional services on a context. */
+function resolveServices(ctx) {
+	return {
+		registry: ctx.get?.("skills"),
+		credentials: ctx.get?.("credentials")
+	};
+}
+/**
+* sha256 of one skill's body, loaded through the registry so the digest is
+* taken over what the MODEL would be handed rather than over whichever file
+* happens to sit in the bundle directory. A skill the registry declines to
+* load (remote, opaque, or raced away) contributes no digest — the
+* fingerprint records `null` for it rather than guessing.
+*/
+async function skillBodySha(registry, name, options) {
+	try {
+		const definition = await registry.get(name, options);
+		if (typeof definition?.content !== "string") return void 0;
+		return hashSkillBody(definition.content);
+	} catch {
+		return;
+	}
+}
+/**
+* Collect the skills portion of the catalog across the given view scopes.
+*
+* `bodySha` costs one registry load per skill, so it is opt-in: the browser
+* card wants a listing, and the capability fingerprint wants the bodies.
+*/
+async function collectSkills$1(registry, workdir, scopes = [void 0], collectOptions = {}) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const scope of scopes) {
+		const base = workdir === void 0 ? {} : { cwd: workdir };
+		const options = scope === void 0 ? base : {
+			...base,
+			scope
+		};
+		let snapshot;
+		try {
+			snapshot = await registry.snapshot(options);
+		} catch {
+			continue;
+		}
+		for (const summary of snapshot.skills) {
+			if (byName.has(summary.name)) continue;
+			const bodySha = collectOptions.bodySha === true ? await skillBodySha(registry, summary.name, options) : void 0;
+			const row = skillRowFrom(summary, await skillUpdatedAt(summary), bodySha);
+			byName.set(row.name, row);
+		}
+	}
+	const skills = [...byName.values()];
+	return {
+		skills,
+		tools: [],
+		mcpServers: [],
+		channels: [{
+			channel: "skill",
+			count: skills.length
+		}]
+	};
+}
+/** Directory names never listed as skill-bundle resources. */
+const SKIP_SKILL_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
+/** Recursively collect a directory's file paths relative to `root`. */
+async function collectSkillFiles(dir, root, out, depth) {
+	if (depth > 16 || out.length > 1e3) return;
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (SKIP_SKILL_DIRS.has(entry.name)) continue;
+			await collectSkillFiles(full, root, out, depth + 1);
+		} else if (entry.isFile()) out.push(relative(root, full));
+	}
+}
+/** Reject unsafe bundle-relative paths (absolute, drive-letter, or `..`). */
+function sanitizeBundlePath(path) {
+	if (path === "" || path.startsWith("/") || /^[a-zA-Z]:/.test(path)) return void 0;
+	const safe = [];
+	for (const segment of path.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") return void 0;
+		safe.push(segment);
+	}
+	return safe.length === 0 ? void 0 : safe.join("/");
+}
+/** Read one skill-bundle file's text content, on demand. */
+async function readSkillFileContent(registry, name, filePath, workdir, scope = void 0, fallback) {
+	const base = workdir === void 0 ? {} : { cwd: workdir };
+	const lookup = scope === void 0 ? base : {
+		...base,
+		scope
+	};
+	const def = await registry.get(name, lookup) ?? fallback;
+	if (def === void 0) return void 0;
+	const resourceBase = def.resourceBase;
+	const bundleDir = resourceBase?.kind === "directory" ? resourceBase.path : void 0;
+	if (bundleDir === void 0) return void 0;
+	const safe = sanitizeBundlePath(filePath);
+	if (safe === void 0) return void 0;
+	const full = join(bundleDir, safe);
+	if (!full.startsWith(bundleDir)) return void 0;
+	try {
+		return { content: (await readFile(full)).toString("utf8") };
+	} catch {
+		return;
+	}
+}
+/** Delete a file skill's directory. Returns an error for built-in / plugin-provided
+* skills (`runtime`, `bundled`, official `skill-badge`) that have no catalog-owned
+* file, and for any skill whose bundle directory cannot be resolved. */
+async function deleteSkillDir(def) {
+	if (!DELETABLE_SOURCES.has(def.source)) return {
+		ok: false,
+		error: "not a deletable file skill"
+	};
+	const dir = def.resourceBase?.kind === "directory" ? def.resourceBase.path : void 0;
+	if (dir === void 0) return {
+		ok: false,
+		error: "skill has no bundle directory"
+	};
+	try {
+		await stat(dir);
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: String(error)
+		};
+	}
+}
+/** Load one skill's full detail (content + metadata + credentials state). */
+async function loadSkillDetail(ctx, registry, name, workdir, scope = void 0, fallback) {
+	const base = workdir === void 0 ? {} : { cwd: workdir };
+	const lookup = scope === void 0 ? base : {
+		...base,
+		scope
+	};
+	const def = await registry.get(name, lookup) ?? fallback;
+	if (def === void 0) return void 0;
+	const metadataDecls = decodeCredentialDecls(def.metadata);
+	const environmentRefs = decodeEnvDecls(def.content).map((decl) => decl.key);
+	const { credentials } = resolveServices(ctx);
+	let credentialStates = [];
+	if (metadataDecls.length > 0 && credentials !== void 0) credentialStates = await Promise.all(metadataDecls.map(async (decl) => {
+		const configured = CREDENTIAL_REF_NAME.test(decl.key) ? (await credentials.describe(decl.key).catch(() => void 0))?.configured === true : false;
+		return {
+			key: decl.key,
+			...decl.label !== void 0 ? { label: decl.label } : {},
+			configured
+		};
+	}));
+	const resourceBase = def.resourceBase;
+	const bundleDir = resourceBase?.kind === "directory" ? resourceBase.path : void 0;
+	let files = [];
+	if (bundleDir !== void 0) {
+		const collected = [];
+		await collectSkillFiles(bundleDir, bundleDir, collected, 0);
+		files = collected.sort();
+	}
+	return {
+		name: def.name,
+		description: def.description,
+		source: def.source,
+		provider: def.provider,
+		modelInvocable: def.invocation.modelInvocable,
+		userInvocable: def.invocation.userInvocable,
+		...def.path !== void 0 ? { path: def.path } : {},
+		...def.whenToUse !== void 0 ? { whenToUse: def.whenToUse } : {},
+		content: def.content,
+		...def.metadata !== void 0 ? { metadataText: JSON.stringify(def.metadata) } : {},
+		...credentialStates.length > 0 ? { credentials: credentialStates } : {},
+		...environmentRefs.length > 0 ? { environmentRefs } : {},
+		...files.length > 0 ? { files } : {}
+	};
+}
+//#endregion
+//#region lib/types/channels.js
+/**
+* Tool channel attribution and skill source labels.
+*
+* Tools have no source field on `ToolDefinition`, so the catalog infers the
+* channel from three signals (see the proposal "工具归因" section):
+*   1. the `mcp__` prefix (exact),
+*   2. the generated official-tools whitelist (exact),
+*   3. baseline-diff inference (`builtin?` / `plugin`).
+*
+* MCP serverName is resolved by longest-match: the mcp-client server-name
+* charset permits underscores (`[A-Za-z0-9_-]{1,32}`), so `mcp__a__b__tool`
+* could belong to server `a` or `a__b`; the longest configured prefix that
+* leaves a non-empty raw tool name wins.
+* @module @khorsheed/dsh-capability-catalog/channels
+*/
+/** The `mcp__` prefix mcp-client stamps on every tool it registers. */
+const MCP_TOOL_PREFIX = "mcp__";
+/** Tool names this plugin itself registers (self-attribution). */
+const SELF_TOOL_NAMES = ["list_capabilities"];
+/**
+* Resolve the channel for one tool name.
+* @param name - wire tool name.
+* @param officialTools - official-tools whitelist (Set).
+* @param mcpServerNames - configured MCP serverNames (longest first).
+* @param appearedAfterApply - whether the tool appeared after apply-time baseline.
+*/
+function attributeToolChannel(name, officialTools, mcpServerNames, appearedAfterApply, toolOrigins = /* @__PURE__ */ new Map()) {
+	if (name.startsWith("mcp__")) {
+		const serverName = resolveMcpServerName(name, mcpServerNames);
+		return {
+			channel: "mcp",
+			confidence: "exact",
+			...serverName !== void 0 ? { serverName } : {}
+		};
+	}
+	if (SELF_TOOL_NAMES.includes(name)) return {
+		channel: "plugin",
+		confidence: "exact",
+		owner: "@khorsheed/dsh-capability-catalog"
+	};
+	const origin = toolOrigins.get(name);
+	if (origin !== void 0) return {
+		channel: origin.channel,
+		confidence: "exact",
+		...origin.owner !== void 0 ? { owner: origin.owner } : {}
+	};
+	if (officialTools.has(name)) return {
+		channel: "builtin",
+		confidence: "exact"
+	};
+	if (!appearedAfterApply) return {
+		channel: "builtin",
+		confidence: "inferred"
+	};
+	return {
+		channel: "plugin",
+		confidence: "inferred"
+	};
+}
+/** Longest-match MCP serverName resolution. */
+function resolveMcpServerName(name, serverNames) {
+	const candidates = [...serverNames].sort((a, b) => b.length - a.length);
+	for (const server of candidates) {
+		const prefix = `${MCP_TOOL_PREFIX}${server}__`;
+		if (name.startsWith(prefix) && name.length > prefix.length) return server;
+	}
+	const rest = name.slice(5);
+	const separator = rest.indexOf("__");
+	if (separator > 0) return rest.slice(0, separator);
+}
+//#endregion
+//#region lib/types/zip.js
+/**
+* Minimal, dependency-free ZIP reader: enough to unpack a skill archive
+* (dirs, stored and deflated entries) into `{ path, data }` pairs.
+*
+* Why hand-rolled: the host face is analyzed by the typert generator against a
+* scratch overlay that only resolves `@deepseek-ai/*` source-plane packages and
+* the harness's own node_modules — a third-party zip library resolves there but
+* not at publish time, and no host edit is allowed. Using only node:zlib keeps
+* the boundary to node built-ins, which the overlay resolves natively, and
+* keeps the published package free of a zip runtime dependency.
+*
+* Skips directories; throws on a malformed or unsupported (e.g. zip64, encrypted,
+* or data-descriptor-only) archive. Skill zips are small and conventional, so
+* the classic (non-zip64) central directory is the only layout needed.
+* @module @khorsheed/dsh-capability-catalog/zip
+*/
+const SIG_LOCAL = 67324752;
+const SIG_CENTRAL = 33639248;
+const SIG_EOCD = 101010256;
+/** Unpack a zip archive into its non-directory entries. */
+function extractZip(buf) {
+	const eocd = findEocd(buf);
+	if (eocd === void 0) throw new Error("end of central directory not found");
+	const count = buf.readUInt16LE(eocd + 10);
+	if (count === 65535) throw new Error("zip64 archives are not supported");
+	let offset = buf.readUInt32LE(eocd + 16);
+	const entries = [];
+	for (let i = 0; i < count; i++) offset = readCentralDirEntry(buf, offset, entries);
+	return entries;
+}
+/** Walk one central-directory entry, appending it when it is a file. */
+function readCentralDirEntry(buf, offset, entries) {
+	if (buf.readUInt32LE(offset) !== SIG_CENTRAL) throw new Error("bad central directory entry");
+	const method = buf.readUInt16LE(offset + 10);
+	const compSize = buf.readUInt32LE(offset + 20);
+	if (compSize === 4294967295) throw new Error("zip64 entries are not supported");
+	const nameLen = buf.readUInt16LE(offset + 28);
+	const extraLen = buf.readUInt16LE(offset + 30);
+	const commentLen = buf.readUInt16LE(offset + 32);
+	const localOffset = buf.readUInt32LE(offset + 42);
+	const name = buf.toString("utf8", offset + 46, offset + 46 + nameLen);
+	if (!name.endsWith("/")) {
+		const { dataOffset } = readLocalHeader(buf, localOffset);
+		entries.push({
+			path: name,
+			data: inflateEntry(buf, dataOffset, method, compSize)
+		});
+	}
+	return offset + 46 + nameLen + extraLen + commentLen;
+}
+/** Read a local file header, returning the offset where the data begins. */
+function readLocalHeader(buf, offset) {
+	if (buf.readUInt32LE(offset) !== SIG_LOCAL) throw new Error("bad local file header");
+	const nameLen = buf.readUInt16LE(offset + 26);
+	const extraLen = buf.readUInt16LE(offset + 28);
+	return { dataOffset: offset + 30 + nameLen + extraLen };
+}
+/** Decompress one entry: stored (0) or raw-deflated (8). */
+function inflateEntry(buf, dataOffset, method, compSize) {
+	const compressed = buf.subarray(dataOffset, dataOffset + compSize);
+	if (method === 0) return Buffer.from(compressed);
+	if (method === 8) return inflateRawSync(compressed);
+	throw new Error(`unsupported compression method ${method}`);
+}
+/** Locate the end-of-central-directory record (last 64 KiB window). */
+function findEocd(buf) {
+	const min = Math.max(0, buf.length - 22 - 65535);
+	for (let i = buf.length - 22; i >= min; i--) if (buf.readUInt32LE(i) === SIG_EOCD) return i;
+}
+//#endregion
+//#region lib/types/import.js
+/**
+* Add-skill import: write a skill from a pasted SKILL.md payload or an uploaded
+* zip archive into the managed skills root and extract its name/frontmatter.
+*
+* A skill is a directory bundle (`<name>/SKILL.md` plus optional
+* `references`/`scripts`/`assets`) or a single flat file, discovered by the
+* skill-filesystem watcher from one of the managed roots. So "installing" a
+* skill is just placing it under the root; nothing executes the payload.
+*
+* The zip path reads the archive with the dependency-free zip reader
+* (`./zip.ts`, node:zlib only), locates the `SKILL.md`, derives the kebab-case
+* `name` from frontmatter, and extracts the bundle under `<root>/<name>/`
+* (strip the archive's own wrapping folder if present). The clone path resolves
+* a repo spec — including a whole `npx skills add <repo> --skill <name>` command
+* copied from a skill's README — clones it into a scratch directory, and lifts
+* the selected skill bundle(s) into the root.
+* @module @khorsheed/dsh-capability-catalog/import
+*/
+const execFileAsync = promisify(execFile);
+const FRONTMATTER$1 = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+/** First bytes of a ZIP archive (local file header / empty / spanned). */
+const ZIP_MAGIC_PK = 80;
+const ZIP_MAGIC_K = 75;
+/** Resolve the managed root directory. */
+function managedRoot(root, dshHome) {
+	return root === "user" ? join(dshHome, "skills") : join(dshHome, ".agents", "skills");
+}
+/** Extract the kebab-case `name` and `description` from a SKILL.md body. */
+function resolveSkillNameFromContent(content) {
+	const m = FRONTMATTER$1.exec(content);
+	if (m === null) return void 0;
+	const front = m[1] ?? "";
+	const name = /^name:\s*(.+)$/m.exec(front)?.[1]?.trim();
+	const description = /^description:\s*(.+)$/m.exec(front)?.[1]?.trim();
+	if (name === void 0 || description === void 0 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) return void 0;
+	return {
+		name,
+		description
+	};
+}
+/** Decode base64 bytes to a UTF-8 string. */
+function decodeBase64(payload) {
+	return Buffer.from(payload, "base64").toString("utf8");
+}
+/** Read the frontmatter `disable-model-invocation` flag (default model-invocable true). */
+function inferModelInvocable(content) {
+	const m = FRONTMATTER$1.exec(content);
+	if (m === null) return true;
+	const front = m[1] ?? "";
+	return /^disable-model-invocation:\s*(true|false)$/m.exec(front)?.[1] !== "true";
+}
+/** Whether a filesystem path exists (dir or file). */
+async function pathExists(p) {
+	try {
+		await stat(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** True when a base64 payload decodes to a ZIP archive (magic bytes). */
+function isZipPayload(payload) {
+	let bytes;
+	try {
+		bytes = Buffer.from(payload, "base64");
+	} catch {
+		return false;
+	}
+	return bytes.length >= 4 && bytes[0] === ZIP_MAGIC_PK && bytes[1] === ZIP_MAGIC_K && (bytes[2] === 3 || bytes[2] === 5 || bytes[2] === 7);
+}
+/** Reject unsafe relative paths (absolute, drive-letter, or `..` traversal). */
+function sanitizeRelPath(p) {
+	if (p === "" || p.startsWith("/") || /^[a-zA-Z]:/.test(p)) return void 0;
+	const safe = [];
+	for (const seg of p.split("/")) {
+		if (seg === "" || seg === ".") continue;
+		if (seg === "..") return void 0;
+		safe.push(seg);
+	}
+	return safe.length === 0 ? void 0 : safe.join("/");
+}
+/** Apply the frontmatter `disable-model-invocation` line to match the request. */
+function finalizeSkillText(content, modelInvocable) {
+	const m = FRONTMATTER$1.exec(content);
+	if (m === null) return content;
+	const front = String(m[1] ?? "");
+	const body = String(m[2] ?? "");
+	if (inferModelInvocable(content) === modelInvocable) return content;
+	const without = front.split("\n").filter((line) => !line.trim().startsWith("disable-model-invocation:")).join("\n");
+	return `---\n${modelInvocable ? without : `${without}${without.endsWith("\n") ? "" : "\n"}disable-model-invocation: true`}\n---\n${body}`;
+}
+/**
+* Add a skill from a base64 SKILL.md text payload into the managed root.
+* @param request - the add-skill request.
+* @param dshHome - the dsh home root.
+*/
+async function addSkillFromText(request, dshHome) {
+	let text;
+	try {
+		text = decodeBase64(request.payload);
+	} catch {
+		return {
+			ok: false,
+			error: "invalid payload: not base64 text"
+		};
+	}
+	const parsed = resolveSkillNameFromContent(text);
+	if (parsed === void 0) return {
+		ok: false,
+		error: "SKILL.md missing or missing name/description frontmatter"
+	};
+	const finalText = finalizeSkillText(text, request.modelInvocable);
+	const target = join(managedRoot(request.root, dshHome), parsed.name);
+	if (!request.overwrite && await pathExists(target)) return {
+		ok: false,
+		exists: true,
+		name: parsed.name
+	};
+	try {
+		await mkdir(target, { recursive: true });
+		await writeFile(join(target, "SKILL.md"), finalText, "utf8");
+	} catch (error) {
+		return {
+			ok: false,
+			error: `failed to write skill: ${String(error)}`
+		};
+	}
+	return {
+		ok: true,
+		name: parsed.name
+	};
+}
+/** Pick the SKILL.md entry: the shallowest absolute path ending in `SKILL.md`. */
+function pickSkillEntry(entries) {
+	let best;
+	let bestDepth = Number.POSITIVE_INFINITY;
+	for (const entry of entries) {
+		const parts = entry.path.split("/");
+		if (parts[parts.length - 1] !== "SKILL.md") continue;
+		const depth = parts.length - 1;
+		if (depth < bestDepth) {
+			best = entry;
+			bestDepth = depth;
+		}
+	}
+	return best;
+}
+/** The archive's wrapping folder prefix ('' when SKILL.md is at the root). */
+function skillDirPrefix(entryName) {
+	const idx = entryName.lastIndexOf("/");
+	return idx >= 0 ? entryName.slice(0, idx + 1) : "";
+}
+/**
+* Add a skill from a base64 ZIP archive payload into the managed root.
+*
+* The archive should contain a skill bundle. If the `SKILL.md` sits directly at
+* the archive root it is extracted as-is; if it sits under a single wrapping
+* folder that folder is stripped so the bundle lands at `<root>/<name>/`. Path
+* traversal entries are skipped; the frontmatter name drives the target folder.
+* @param request - the add-skill request.
+* @param dshHome - the dsh home root.
+*/
+async function addSkillFromZip(request, dshHome) {
+	let bytes;
+	try {
+		bytes = Buffer.from(request.payload, "base64");
+	} catch {
+		return {
+			ok: false,
+			error: "invalid payload: not base64"
+		};
+	}
+	let entries;
+	try {
+		entries = extractZip(bytes);
+	} catch (error) {
+		return {
+			ok: false,
+			error: `invalid zip archive: ${String(error)}`
+		};
+	}
+	const skillEntry = pickSkillEntry(entries);
+	if (skillEntry === void 0) return {
+		ok: false,
+		error: "archive did not contain a SKILL.md"
+	};
+	const original = skillEntry.data.toString("utf8");
+	const parsed = resolveSkillNameFromContent(original);
+	if (parsed === void 0) return {
+		ok: false,
+		error: "SKILL.md missing name/description frontmatter"
+	};
+	const name = parsed.name;
+	const prefix = skillDirPrefix(skillEntry.path);
+	const finalContent = finalizeSkillText(original, request.modelInvocable);
+	const target = join(managedRoot(request.root, dshHome), name);
+	if (!request.overwrite && await pathExists(target)) return {
+		ok: false,
+		exists: true,
+		name
+	};
+	let wrote = false;
+	try {
+		if (request.overwrite === true) await rm(target, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(target, { recursive: true });
+	} catch (error) {
+		return {
+			ok: false,
+			error: `failed to create skill dir: ${String(error)}`
+		};
+	}
+	for (const entry of entries) {
+		const rel = entry.path;
+		if (prefix !== "" && !rel.startsWith(prefix)) continue;
+		const safe = sanitizeRelPath(prefix !== "" ? rel.slice(prefix.length) : rel);
+		if (safe === void 0) continue;
+		const outPath = join(target, safe);
+		if (!outPath.startsWith(target)) continue;
+		const data = safe === "SKILL.md" ? Buffer.from(finalContent, "utf8") : entry.data;
+		try {
+			await mkdir(dirname(outPath), { recursive: true });
+			await writeFile(outPath, data);
+			wrote = true;
+		} catch (error) {
+			return {
+				ok: false,
+				error: `failed to write skill file: ${String(error)}`
+			};
+		}
+	}
+	return wrote ? {
+		ok: true,
+		name
+	} : {
+		ok: false,
+		error: "archive contained no reusable skill files"
+	};
+}
+/**
+* Add a skill from a base64 payload into the managed root, auto-detecting a
+* ZIP archive (magic bytes) from a raw SKILL.md text payload.
+* @param request - the add-skill request.
+* @param dshHome - the dsh home root.
+*/
+async function addSkillFromPayload(request, dshHome) {
+	if (isZipPayload(request.payload)) return addSkillFromZip(request, dshHome);
+	return addSkillFromText(request, dshHome);
+}
+/** `skills add` flags whose following non-flag values dsh consumes and ignores. */
+const DROPPED_VALUE_FLAGS = /* @__PURE__ */ new Set([
+	"-a",
+	"--agent",
+	"--subagent"
+]);
+/** `skills add` flags that take exactly one value dsh consumes and ignores. */
+const DROPPED_SINGLE_VALUE_FLAGS = /* @__PURE__ */ new Set(["--metadata"]);
+/** `skills add` boolean flags dsh consumes and ignores (`-g` is meaningless for a root dsh owns). */
+const DROPPED_BOOL_FLAGS = /* @__PURE__ */ new Set([
+	"-g",
+	"--global",
+	"-y",
+	"--yes",
+	"-l",
+	"--list",
+	"--all",
+	"--full-depth",
+	"--json",
+	"--copy"
+]);
+/** `skills add` flags that select sub-skills; their greedy values are kept. */
+const SKILL_FLAGS = /* @__PURE__ */ new Set(["-s", "--skill"]);
+/**
+* Parse a `command`-channel spec — `owner/repo`, a git URL, or a whole
+* `npx skills add <repo> [--skill <name>]… [-g]` command — into its source
+* reference and `--skill` selections.
+*
+* Every flag token is consumed here, never left in the string: the spec used to
+* be handed to `git clone` after only a prefix and a trailing `-g` were
+* stripped, so the README form `npx skills add owner/repo --skill name` became
+* the clone URL `https://github.com/owner/repo --skill name`, which git rejects
+* as a malformed URL. The recognized set mirrors the `skills` CLI's own `add`
+* parser (vercel-labs/skills) so a command copied from a skill's README installs
+* what it says: a flag's value is consumed with it, never glued onto the
+* reference.
+* @param spec - the raw spec from the add-skill command channel.
+*/
+function parseRepoSpec(spec) {
+	const tokens = spec.trim().replace(/^npx\s+skills\s+add\s+/i, "").trim().split(/\s+/);
+	const skills = [];
+	let ref;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i] ?? "";
+		if (token === "") continue;
+		if (SKILL_FLAGS.has(token)) {
+			while (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) skills.push(tokens[++i]);
+			continue;
+		}
+		if (DROPPED_VALUE_FLAGS.has(token)) {
+			while (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) i++;
+			continue;
+		}
+		if (DROPPED_SINGLE_VALUE_FLAGS.has(token)) {
+			i++;
+			continue;
+		}
+		if (DROPPED_BOOL_FLAGS.has(token) || token.startsWith("-")) continue;
+		if (ref === void 0) ref = token;
+	}
+	return ref === void 0 ? void 0 : {
+		ref,
+		skills
+	};
+}
+/** A copy-pasted SCP-style remote (`git@host:owner/repo`): a clone URL, never `owner/repo`. */
+const SCP_STYLE_RE = /^[^/@\s]+@[^/\s:]+:/;
+/** A scheme-prefixed spec, which must carry a path after its host. */
+const SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+/** The only host whose URL shape is known to be `owner/repo[/path…]`. */
+const GITHUB_HOST = "github.com";
+/** Segments a copied browser URL puts in front of the real in-repo path. */
+const BROWSER_PATH_MARKERS = /* @__PURE__ */ new Set(["tree", "blob"]);
+/** Local-path shapes: `stat` already ran, so a miss here is a missing directory, not a repo spec. */
+const LOCAL_PATH_RE = /^(?:~\/|\/|\.\.?\/|\.\.?$)/;
+/** Whether a spec's first segment names a host rather than an owner (`github.com`, `localhost:3000`). */
+function isHostSegment(segment) {
+	return segment !== "." && segment !== ".." && (segment.includes(".") || segment.includes(":"));
+}
+/**
+* Build a target from `owner/repo` plus whatever path followed it, dropping the
+* copy-paste noise a browser URL carries: a `tree/<branch>`/`blob/<branch>`
+* marker, and a trailing `SKILL.md` naming the file rather than its directory.
+*/
+function targetFromParts(host, owner, repo, rest) {
+	let path = rest;
+	if (path.length >= 2 && BROWSER_PATH_MARKERS.has(path[0] ?? "")) path = path.slice(2);
+	if (path[path.length - 1] === "SKILL.md") path = path.slice(0, -1);
+	return {
+		ok: true,
+		url: `${host === void 0 ? `https://${GITHUB_HOST}` : `https://${host}`}/${owner}/${repo}`,
+		subpath: path.join("/")
+	};
+}
+/**
+* Resolve a source reference into a clone URL plus an optional in-repo subpath.
+*
+* Accepted: a git URL with a transport, `owner/repo`, and either of those behind
+* a host — `github.com/owner/repo`, `github.com/owner/repo/skills/name`, a copied
+* browser URL's `tree/<branch>/…` or `blob/<branch>/SKILL.md`. Only `github.com`
+* gets the `owner/repo` split; on any other host the whole path is the repository
+* (GitLab subgroups are real paths, not repo + subpath), so it is handed to git
+* untouched.
+*
+* Getting this wrong is what the host rule exists for: the old code matched the
+* `owner/repo` shape anywhere in the string and kept only the FIRST TWO segments,
+* so the everyday paste `github.com/larashero3-dotcom/lieflat-charts` cloned
+* `https://github.com/github.com/larashero3-dotcom` — the host taken for the
+* owner, the real repo name silently dropped — and failed with GitHub's
+* "Repository not found", which reads like the skill is unsupported.
+* @param ref - the source reference from `parseRepoSpec`.
+*/
+function resolveCloneTarget(ref) {
+	const spec = (ref.trim().split(/[?#]/)[0] ?? "").replace(/\.git$/, "");
+	if (spec === "") return {
+		ok: false,
+		error: "the spec is empty — use owner/repo or a git URL"
+	};
+	const urlMatch = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/([^/]+)\/(.*)$/.exec(spec);
+	if (urlMatch !== null) {
+		const host = urlMatch[1];
+		const rest = urlMatch[2].split("/").filter((part) => part !== "");
+		if (host.toLowerCase() !== GITHUB_HOST || rest.length <= 2) return {
+			ok: true,
+			url: spec,
+			subpath: ""
+		};
+		return targetFromParts(host, rest[0], rest[1], rest.slice(2));
+	}
+	if (SCP_STYLE_RE.test(spec)) return {
+		ok: true,
+		url: spec,
+		subpath: ""
+	};
+	if (SCHEME_RE.test(spec)) return {
+		ok: false,
+		error: `${spec} has no repository path`
+	};
+	const parts = spec.split("/").filter((part) => part !== "");
+	const first = parts[0];
+	const host = first !== void 0 && isHostSegment(first) ? parts.shift() : void 0;
+	if (parts.length < 2) return {
+		ok: false,
+		error: `${[host, ...parts].filter((part) => part !== void 0).join("/")} is not a repository — a source needs owner/repo (a host or a user page alone has nothing to clone)`
+	};
+	if (host !== void 0 && host.toLowerCase() !== GITHUB_HOST) return {
+		ok: true,
+		url: `https://${host}/${parts.join("/")}`,
+		subpath: ""
+	};
+	return targetFromParts(host, parts[0], parts[1], parts.slice(2));
+}
+/** An actionable line appended to a failed clone, keyed off git's own stderr. */
+function cloneFailureHint(text) {
+	if (/Repository not found/i.test(text)) return "\ncheck the owner and repo name: GitHub answers \"Repository not found\" for a misspelled repo and for a private one alike.";
+	if (/Could not resolve host/i.test(text)) return "\ncheck the host in the clone URL.";
+	return "";
+}
+/** Every skill bundle at or under `dir` (depth ≤ 4, `.git` skipped), shallowest first. */
+async function collectSkills(dir, depth = 0) {
+	if (depth > 4) return [];
+	const out = [];
+	const content = await readFile(join(dir, "SKILL.md"), "utf8").catch(() => void 0);
+	const parsed = content === void 0 ? void 0 : resolveSkillNameFromContent(content);
+	if (content !== void 0 && parsed !== void 0) out.push({
+		dir,
+		dirName: basename(dir),
+		name: parsed.name,
+		content
+	});
+	const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.name === ".git") continue;
+		out.push(...await collectSkills(join(dir, entry.name), depth + 1));
+	}
+	return out;
+}
+/**
+* Resolve `--skill` selections against the skills a repo carries. A selection
+* matches a skill's directory name or its frontmatter `name`, case-insensitively
+* — the `skills` CLI's own rule — and `*` selects every skill.
+* @returns the chosen skills; `[]` when nothing was selected but the repo is
+* ambiguous (more than one skill); `undefined` when a selection matched nothing.
+*/
+function selectSkills(skills, selections) {
+	if (selections.length === 0) return skills.length > 1 ? [] : [...skills];
+	if (selections.includes("*")) return [...skills];
+	const chosen = skills.filter((s) => selections.some((sel) => sel.toLowerCase() === s.dirName.toLowerCase() || sel.toLowerCase() === s.name.toLowerCase()));
+	return chosen.length === 0 ? void 0 : chosen;
+}
+/** Expand a leading `~` to the OS home directory. */
+function expandHome(p) {
+	if (p === "~") return homedir();
+	if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+	return p;
+}
+/** Sub-directories of `dir` that contain a SKILL.md (a skills container). */
+async function listSkillDirs(dir) {
+	try {
+		const entries = await readdir(dir, { withFileTypes: true });
+		const out = [];
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			try {
+				await stat(join(dir, entry.name, "SKILL.md"));
+				out.push(entry.name);
+			} catch {}
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+/**
+* Install a skill by cloning a source repo (owner/repo, a git URL, a host-prefixed
+* `github.com/owner/repo[/path]`, a copied browser URL, or a whole
+* `npx skills add <repo> [--skill <name>]` command) into the managed root. This
+* is the dsh-native "install from source" — a plain `npx skills add` writes into
+* an external skills dir the dsh filesystem watcher does not scan.
+*
+* The clone lands in a scratch directory; the chosen skill bundle (the repo's
+* only one, `request.skills`, or the command's `--skill` values) is then lifted
+* to `<managed root>/<frontmatter name>/`. A repo carrying several skills and no
+* selection is refused with the list rather than installing the shallowest one.
+* A spec naming a path inside the repo (`…/skills/<name>`) searches only that
+* path.
+* @param request - the add-skill request (channel 'command', repo carries the spec).
+* @param dshHome - the dsh home root.
+*/
+async function commandInstall(request, dshHome) {
+	const spec = request.repo ?? "";
+	const trimmed = spec.trim();
+	const expanded = expandHome(trimmed);
+	let dirStat;
+	try {
+		dirStat = await stat(expanded);
+	} catch {
+		dirStat = void 0;
+	}
+	if (dirStat?.isDirectory() === true) {
+		const copyInto = async (src, skillName) => {
+			const skillMd = join(src, "SKILL.md");
+			let content;
+			try {
+				content = await readFile(skillMd, "utf8");
+			} catch {
+				return {
+					ok: false,
+					error: "directory has no SKILL.md"
+				};
+			}
+			const parsed = resolveSkillNameFromContent(content);
+			if (parsed === void 0) return {
+				ok: false,
+				error: "SKILL.md missing name/description frontmatter"
+			};
+			const name = skillName ?? parsed.name;
+			const target = join(managedRoot(request.root, dshHome), name);
+			if (!request.overwrite && await pathExists(target)) return {
+				ok: false,
+				exists: true,
+				name
+			};
+			try {
+				await rm(target, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			await cp(src, target, { recursive: true });
+			await writeFile(join(target, "SKILL.md"), finalizeSkillText(content, request.modelInvocable), "utf8");
+			return {
+				ok: true,
+				name
+			};
+		};
+		const children = await listSkillDirs(expanded);
+		if (request.skills !== void 0 && request.skills.length > 0) {
+			const results = await Promise.all(request.skills.map(async (s) => copyInto(join(expanded, s), s)));
+			const existing = results.find((r) => !r.ok && r.exists === true);
+			if (existing !== void 0) return existing;
+			const ok = results.filter((r) => r.ok);
+			if (ok.length > 0) return {
+				ok: true,
+				name: ok.map((r) => r.name).join(", ")
+			};
+			return results.find((r) => !r.ok) ?? {
+				ok: false,
+				error: "no skills installed"
+			};
+		}
+		if (children.length > 1) return {
+			ok: false,
+			error: `directory has ${children.length} skills — pick one: ${children.join(", ")}`
+		};
+		const only = children[0];
+		if (children.length === 1 && only !== void 0) return copyInto(join(expanded, only), only);
+		return copyInto(expanded);
+	}
+	if (LOCAL_PATH_RE.test(trimmed)) return {
+		ok: false,
+		error: `local directory not found: ${expanded}`
+	};
+	const source = parseRepoSpec(spec);
+	if (source === void 0) return {
+		ok: false,
+		error: `unrecognized repo spec: ${spec || "(empty)"} — use owner/repo, a git URL, or an existing local directory`
+	};
+	const resolved = resolveCloneTarget(source.ref);
+	if (!resolved.ok) return {
+		ok: false,
+		error: `unrecognized repo spec: ${resolved.error}`
+	};
+	const { url, subpath } = resolved;
+	const root = managedRoot(request.root, dshHome);
+	const repoName = url.replace(/\.git$/, "").split("/").pop() ?? "skill";
+	const scratchRoot = await mkdtemp(join(tmpdir(), "dsh-skill-clone-"));
+	const scratch = join(scratchRoot, repoName);
+	try {
+		try {
+			await execFileAsync("git", [
+				"clone",
+				"--depth",
+				"1",
+				url,
+				scratch
+			]);
+		} catch (error) {
+			const text = String(error);
+			return {
+				ok: false,
+				error: `install failed: ${text}${cloneFailureHint(text)}`
+			};
+		}
+		const searchRoot = subpath === "" ? scratch : join(scratch, subpath);
+		if (searchRoot !== scratch && !await pathExists(searchRoot)) return {
+			ok: false,
+			error: `no such path in the repo: ${subpath} — the clone succeeded, but it has nothing there`
+		};
+		const skills = await collectSkills(searchRoot);
+		if (skills.length === 0) return {
+			ok: false,
+			error: subpath === "" ? "cloned repo has no SKILL.md" : `cloned repo has no SKILL.md under ${subpath}`
+		};
+		const selections = request.skills !== void 0 && request.skills.length > 0 ? request.skills : source.skills;
+		const chosen = selectSkills(skills, selections);
+		if (chosen === void 0) return {
+			ok: false,
+			error: `no matching skill for: ${selections.join(", ")} — available: ${skills.map((s) => s.dirName).join(", ")}`
+		};
+		if (chosen.length === 0) return {
+			ok: false,
+			error: `directory has ${skills.length} skills — pick one: ${skills.map((s) => s.dirName).join(", ")}`
+		};
+		const plans = chosen.map((skill) => ({
+			skill,
+			target: join(root, skill.name)
+		}));
+		for (const { skill, target } of plans) if (!request.overwrite && await pathExists(target)) return {
+			ok: false,
+			exists: true,
+			name: skill.name
+		};
+		const installed = [];
+		for (const { skill, target } of plans) {
+			await rm(target, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+			await cp(skill.dir, target, { recursive: true });
+			await writeFile(join(target, "SKILL.md"), finalizeSkillText(skill.content, request.modelInvocable), "utf8");
+			installed.push(skill.name);
+		}
+		return {
+			ok: true,
+			name: installed.join(", ")
+		};
+	} finally {
+		await rm(scratchRoot, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
+* List the skills inside a local dir for the add-skill chooser. If the dir is a
+* **skill container** (a set of `<name>/SKILL.md` sub-dirs) the sub-skills are
+* listed as `kind:'child'`; if the dir is **itself a single skill bundle** (a
+* `SKILL.md` at its root) it is listed as one `kind:'self'` entry so the user can
+* install the directory as-is. Both shapes are returned when a dir has a root
+* `SKILL.md` AND child skill dirs.
+* @param dirPath - the local directory path (may be `~`-prefixed).
+*/
+async function listDirSkills(dirPath) {
+	const expanded = expandHome(dirPath);
+	const out = [];
+	const selfContent = await readFile(join(expanded, "SKILL.md"), "utf8").catch(() => void 0);
+	if (selfContent !== void 0) {
+		const parsed = resolveSkillNameFromContent(selfContent);
+		if (parsed !== void 0) out.push({
+			name: parsed.name,
+			description: parsed.description,
+			kind: "self"
+		});
+	}
+	for (const name of await listSkillDirs(expanded)) {
+		const parsed = resolveSkillNameFromContent(await readFile(join(expanded, name, "SKILL.md"), "utf8").catch(() => ""));
+		out.push({
+			name,
+			description: parsed?.description ?? "",
+			kind: "child"
+		});
+	}
+	return out;
+}
+//#endregion
+//#region lib/types/official-tools.js
+/** Generated from the pinned harness checkout — do not edit by hand. Run scripts/gen-official-tools.mts. */
+const OFFICIAL_TOOLS = [
+	"ask_user_question",
+	"bash",
+	"cordis_define",
+	"cordis_inspect_list",
+	"cordis_inspect_query",
+	"cordis_inspect_self",
+	"cordis_run",
+	"cordis_stop",
+	"cordis_undefine",
+	"create_goal",
+	"edit",
+	"get_goal",
+	"interrupt_agent",
+	"job_kill",
+	"job_list",
+	"job_output",
+	"list_agents",
+	"list_subagent_models",
+	"lsp",
+	"pwsh",
+	"ralph",
+	"read",
+	"read_image",
+	"send_message",
+	"session_event_read",
+	"session_event_search",
+	"session_event_trace",
+	"session_search",
+	"session_trace",
+	"str_replace_editor",
+	"terminal_close",
+	"terminal_list",
+	"terminal_open",
+	"terminal_read",
+	"terminal_send",
+	"terminal_signal",
+	"todo_write",
+	"update_goal",
+	"web_fetch",
+	"web_search",
+	"write"
+];
+//#endregion
+//#region lib/types/remote.js
+/**
+* Catalog data layer: pure functions the Remote service calls. Kept separate
+* from the service so the snapshot/add/detail/credential logic is unit-testable
+* without a Cordis context and stays independent of the typert decorators.
+* @module @khorsheed/dsh-capability-catalog/remote
+*/
+/** Load the cached official-tools names. */
+function officialToolsSet() {
+	return new Set(OFFICIAL_TOOLS);
+}
+/** Project visible tools onto catalog rows with channel attribution. */
+function projectTools(schemas, mcpServers, appearedAfterApply, toolOrigins = /* @__PURE__ */ new Map()) {
+	const official = officialToolsSet();
+	const rows = [];
+	for (const schema of schemas) {
+		const attributed = attributeToolChannel(schema.name, official, mcpServers, appearedAfterApply.has(schema.name), toolOrigins);
+		rows.push({
+			name: schema.name,
+			description: schema.description ?? "",
+			channel: attributed.channel,
+			confidence: attributed.confidence,
+			...attributed.serverName !== void 0 ? { serverName: attributed.serverName } : {},
+			...attributed.owner !== void 0 ? { owner: attributed.owner } : {},
+			...schema.parameters !== void 0 ? { parameters: schema.parameters } : {}
+		});
+	}
+	return rows;
+}
+/**
+* Build the full catalog snapshot (skills + tools).
+*
+* `fingerprint` decides whether the snapshot is a LISTING or an IDENTITY: it
+* loads every skill body (one registry read each) so the rows carry
+* `bodySha`, and stamps `sha` — the capability hash. The browser card wants
+* the listing; a condition's capability record wants the identity.
+*/
+async function catalogSnapshot(workdir, registry, toolsSchemas, mcpServers, appearedAfterApply, scopes = [void 0], toolOrigins = /* @__PURE__ */ new Map(), options = {}) {
+	const fingerprint = options.fingerprint === true;
+	const base = await collectSkills$1(registry, workdir, scopes, { bodySha: fingerprint });
+	const tools = projectTools(toolsSchemas, mcpServers, appearedAfterApply, toolOrigins);
+	const snapshot = {
+		skills: base.skills,
+		tools,
+		mcpServers: mcpServers.map((name) => ({
+			name,
+			toolCount: tools.filter((t) => t.serverName === name).length
+		})),
+		channels: [{
+			channel: "skill",
+			count: base.skills.length
+		}, {
+			channel: "tool",
+			count: tools.length
+		}],
+		...options.preset !== void 0 ? { preset: options.preset } : {}
+	};
+	return fingerprint ? {
+		...snapshot,
+		sha: hashOf(snapshot)
+	} : snapshot;
+}
+/** Load one skill detail. */
+async function catalogDetail(ctx, registry, name, workdir, scope = void 0, fallback) {
+	return loadSkillDetail(ctx, registry, name, workdir, scope, fallback);
+}
+/** Read one skill-bundle file's text content on demand. */
+async function catalogReadSkillFile(registry, name, filePath, workdir, scope = void 0, fallback) {
+	return readSkillFileContent(registry, name, filePath, workdir, scope, fallback);
+}
+/** Open the host's native directory chooser (the workspace "add" dialog). */
+async function catalogPickDirectory(ctx, signal) {
+	const cap = (ctx.get?.("directoryPicker"))?.capability?.();
+	if (cap?.kind !== "native" || cap.pick === void 0) return null;
+	try {
+		return await cap.pick(signal ?? new AbortController().signal);
+	} catch {
+		return null;
+	}
+}
+/** Delete a catalog-owned file skill (rejects built-in / plugin-provided). */
+async function catalogDeleteSkill(registry, name, workdir, scope = void 0) {
+	const base = workdir === void 0 ? {} : { cwd: workdir };
+	const lookup = scope === void 0 ? base : {
+		...base,
+		scope
+	};
+	const def = await registry.get(name, lookup);
+	if (def === void 0) return {
+		ok: false,
+		error: "skill not found"
+	};
+	return deleteSkillDir(def);
+}
+/** Set one declared credential value (never returned on the wire). */
+async function catalogSetCredential(ctx, request) {
+	const { credentials } = resolveServices(ctx);
+	if (credentials === void 0) return false;
+	try {
+		if (!CREDENTIAL_REF_NAME.test(request.key)) return false;
+		await credentials.set(request.key, request.value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Add a skill from a raw SKILL.md text payload into the managed root. */
+async function catalogAddSkill(ctx, request, dshHome) {
+	const { registry } = resolveServices(ctx);
+	if (registry === void 0) return {
+		ok: false,
+		error: "skills service absent in this composition"
+	};
+	if (request.channel === "zip") return addSkillFromPayload(request, dshHome);
+	if (request.channel === "command") return commandInstall(request, dshHome);
+	return {
+		ok: false,
+		error: "github clone not wired in v1"
+	};
+}
+/** List the skills inside a local container dir (for the add-skill chooser). */
+async function catalogListDirSkills(dirPath) {
+	return listDirSkills(dirPath);
+}
+//#endregion
+//#region lib/types/preset-scope.js
+/**
+* Resolving WHICH scope the catalog reads — and the one place where a listing
+* and a fingerprint part company.
+*
+* The catalog reads the skill and tool registries at an agent preset's
+* standing scope, because that is the view the model actually has. Resolving
+* it can fail: the composition may mount no roster, the named preset may not
+* exist, or its composition may refuse to mount.
+*
+* The roster face depends on the host line: 0.1.5 exposes a lease-free
+* `standingKeyFor(id)`, while rc.1 replaced it with a LEASED
+* `acquireScope(id)` — the resolved lease carries the key and a release on
+* `Symbol.asyncDispose`, and a lease never released leaks a generation user,
+* so the preset's scope is never collected. Both faces resolve through
+* {@link acquireStandingScope}; callers that hold the key across reads own
+* the release (see {@link ResolvedPresetScope.dispose}).
+*
+* A LISTING degrades on all three. The settings card must not go blank
+* because a preset has a bad row, and the global layer is a useful, honestly
+* unlabelled answer there.
+*
+* A FINGERPRINT must not. Falling back to the global layer and stamping the
+* requested preset's name on the result hands back a hash that is not that
+* preset's face — which is precisely the "claim with nothing behind it" the
+* hash exists to eliminate. It was not hypothetical: on a real sub-dsh whose
+* preset carried one invalid row, two scopes rostering two different presets
+* produced one identical hash, silently, and the only way to notice was to
+* already know the answer.
+* @module @khorsheed/dsh-capability-catalog/preset-scope
+*/
+/**
+* Acquire one preset's standing scope key from whichever face the roster
+* offers — 0.1.5's lease-free `standingKeyFor` first, rc.1's leased
+* `acquireScope` when that is absent. Errors propagate unchanged, so the
+* caller owns the strict/degrade policy; the caller also owns the release.
+* @param roster - the agent-preset roster (already probed present).
+* @param id - the preset to read, or undefined for the deployment default.
+* @returns the key and the lease release, if the face leases.
+*/
+async function acquireStandingScope(roster, id) {
+	if (roster.standingKeyFor !== void 0) return { key: await roster.standingKeyFor(id) };
+	if (roster.acquireScope === void 0) return { key: void 0 };
+	const lease = await roster.acquireScope(id);
+	const dispose = leaseRelease(lease);
+	return {
+		key: leaseKey(lease),
+		...dispose === void 0 ? {} : { dispose }
+	};
+}
+/**
+* Resolve the catalog's reading scope.
+*
+* Resolving a preset MOUNTS it (the roster's single-flight standing mount),
+* so this is not a free read: asking for the capability face of a preset
+* nothing has composed yet composes it.
+* @param roster - the optional agent-preset roster (`ctx.get('agentPresets')`).
+* @param presetId - the preset to read, or undefined for the deployment default.
+* @param strict - fingerprint mode: throw rather than degrade to the global layer.
+* @returns the scope to read at and the label it may carry.
+* @throws in strict mode when the roster is absent for a named preset, or
+*   cannot resolve a standing scope.
+*/
+async function resolvePresetScope(roster, presetId, strict) {
+	if (roster?.standingKeyFor === void 0 && roster?.acquireScope === void 0) {
+		if (strict && presetId !== void 0) throw new Error(`capability-catalog: cannot fingerprint preset ${JSON.stringify(presetId)} — this composition mounts no agent-preset roster`);
+		return {
+			scope: void 0,
+			preset: void 0
+		};
+	}
+	const wanted = presetId ?? roster?.defaultId;
+	let read;
+	try {
+		read = await acquireStandingScope(roster, wanted);
+	} catch (error) {
+		if (strict) throw new Error(`capability-catalog: cannot fingerprint preset ${JSON.stringify(wanted)}: ${error instanceof Error ? error.message : String(error)}`);
+		return {
+			scope: void 0,
+			preset: void 0
+		};
+	}
+	if (read.key === void 0) {
+		await read.dispose?.();
+		if (strict) throw new Error(`capability-catalog: the roster resolved no standing scope for preset ${JSON.stringify(wanted)}`);
+		return {
+			scope: void 0,
+			preset: void 0
+		};
+	}
+	return {
+		scope: read.key,
+		preset: typeof wanted === "string" && wanted !== "" ? wanted : void 0,
+		...read.dispose === void 0 ? {} : { dispose: read.dispose }
+	};
+}
+/** The lease's key, read structurally (`key` is opaque to the catalog). */
+function leaseKey(lease) {
+	if (lease === null || typeof lease !== "object" && typeof lease !== "function") return void 0;
+	return lease.key;
+}
+/**
+* The lease's release, hung on `Symbol.asyncDispose` by the roster. The
+* es2024 target does not type that symbol, so it is read through a cast —
+* any runtime hosting an rc.1 roster defines it, because the roster's own
+* lease literal is keyed by it. A lease without a callable release degrades
+* to the 0.1.5 shape (nothing to dispose) rather than failing the read.
+*/
+function leaseRelease(lease) {
+	if (lease === null || typeof lease !== "object" && typeof lease !== "function") return void 0;
+	const asyncDispose = Symbol.asyncDispose;
+	const release = asyncDispose === void 0 ? void 0 : lease[asyncDispose];
+	if (typeof release !== "function") return void 0;
+	return async () => {
+		await release.call(lease);
+	};
+}
+//#endregion
+//#region lib/types/scoped-delivery.js
+/**
+* Preset-scoped skill delivery: a plugin-owned skills root whose entries are
+* delivered **into one preset's scope layer** instead of into the global layer.
+*
+* The skill registry is layered by the scope a registration is made from, and a
+* read merges the global layer with the viewing agent's scope chain. A provider
+* registered through a context scoped to a preset's standing key is therefore
+* consulted only for sessions on that preset — no read-time identity guessing,
+* and no dependence on the borrowed lookup options.
+*
+* The per-skill policy lives in the skill's own frontmatter
+* (`metadata.presetScope: [<preset-id>, …]`); an absent or empty list means the
+* entry is not delivered by this module at all. A managed name that ALSO exists
+* in a default skill root is refused delivery and reported: a leftover copy is
+* served by the host provider in every preset, so silently delivering a second
+* candidate would make the scope a lie.
+*
+* Scope of enforcement: this is a discovery/delivery policy for one Harness
+* instance, not an authorization boundary. `ScopeKey` values are ordinary
+* objects and the roster hands real ones to any caller, so a same-process plugin
+* can claim membership. In-process agents and children joining the parent's
+* composition are covered; native codex/claude-code and ACP backends start their
+* own runtime and never consult this registry at all.
+* @module @khorsheed/dsh-capability-catalog/scoped-delivery
+*/
+let presetRegistryProbe;
+/**
+* Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+* `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+* (the livePresetMounts API carried over); 0.1.5/0.1.6 hosts install only the
+* old name, and a host without preset composition installs neither — `null`,
+* and {@link ScopedSkillDelivery.liveKeys} then reports nothing live, the same
+* degrade the call's own catch encodes. A STATIC import of either name is a
+* module-resolution failure at load on hosts installing only the other —
+* pack-dist strips `dependencies`, so the specifier resolves against the
+* host's install tree. Both specifiers stay static string literals so tsdown
+* externalizes them and tsc type-checks them.
+* @returns the module namespace, or null when neither name resolves.
+*/
+function loadPresetRegistry() {
+	presetRegistryProbe ??= import("@deepseek-ai/dsh-agent-preset-registry").catch(() => import("@deepseek-ai/dsh-agent-presets")).catch(() => null);
+	return presetRegistryProbe;
+}
+/** Provider label for managed entries; also the candidate's `provider` field. */
+const SCOPED_PROVIDER_NAME = "capability-catalog";
+/** Candidate rank, beside the filesystem provider's `custom` roots. */
+const MANAGED_SKILL_RANK = 300;
+/** Directory under the harness home that holds preset-scoped skills. */
+const SCOPED_SKILLS_DIR = join("capability-catalog", "skills");
+/** Debounce for filesystem-triggered rescans. */
+const RESCAN_DEBOUNCE_MS = 150;
+/** Frontmatter block, then the body it precedes. */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Kebab-case skill / preset id grammar (the registry's own). */
+const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The managed root for one harness home. */
+function scopedSkillsRoot(dshHome) {
+	return join(dshHome, SCOPED_SKILLS_DIR);
+}
+/**
+* Read the `presetScope` list out of a frontmatter block.
+*
+* Accepted forms, at any indentation (the canonical one is
+* `metadata.presetScope`):
+*
+* ```yaml
+* metadata:
+*   presetScope: [dsh-writing, dev]
+*   presetScope:
+*     - dsh-writing
+* ```
+* @param front - the frontmatter text without its `---` fences.
+* @returns the declared ids, or undefined when the key is absent.
+*/
+function parsePresetScopeFrontmatter(front) {
+	const lines = front.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const match = /^(\s*)presetScope\s*:\s*(.*)$/.exec(lines[index] ?? "");
+		if (match === null) continue;
+		const indent = (match[1] ?? "").length;
+		const rest = (match[2] ?? "").trim();
+		if (rest.startsWith("[")) return presetIdsOf(rest.slice(1, rest.lastIndexOf("]") === -1 ? void 0 : rest.lastIndexOf("]")).split(","));
+		if (rest !== "") return presetIdsOf([rest]);
+		const block = [];
+		for (let item = index + 1; item < lines.length; item += 1) {
+			const entry = /^(\s*)-\s*(.*?)\s*$/.exec(lines[item] ?? "");
+			if (entry === null) break;
+			if ((entry[1] ?? "").length <= indent) break;
+			block.push(entry[2] ?? "");
+		}
+		return presetIdsOf(block);
+	}
+}
+/** Normalize YAML scalars onto the preset-id grammar. */
+function presetIdsOf(values) {
+	const ids = [];
+	for (const value of values) {
+		const id = value.trim().replace(/^['"]|['"]$/g, "");
+		if (id === "" || !KEBAB_ID.test(id)) continue;
+		if (!ids.includes(id)) ids.push(id);
+	}
+	return ids;
+}
+/** Whether a string is a usable skill / preset id. */
+function isKebabId(value) {
+	return KEBAB_ID.test(value);
+}
+/** Split a SKILL.md into its frontmatter block and body. */
+function splitFrontmatter(content) {
+	const match = FRONTMATTER.exec(content);
+	if (match === null) return void 0;
+	return {
+		front: match[1] ?? "",
+		body: match[2] ?? ""
+	};
+}
+/** Read a boolean frontmatter flag (`key: true|false`). */
+function frontmatterFlag(front, key) {
+	const match = new RegExp(`^\\s*${key}\\s*:\\s*(true|false)\\s*$`, "m").exec(front);
+	if (match === null) return void 0;
+	return match[1] === "true";
+}
+/** Read a scalar frontmatter value, unquoting a simple quoted or plain form. */
+function frontmatterScalar(front, key) {
+	const match = new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, "m").exec(front);
+	if (match === null) return void 0;
+	const value = (match[1] ?? "").trim().replace(/^['"]|['"]$/g, "");
+	return value === "" ? void 0 : value;
+}
+/**
+* Parse one managed `SKILL.md` into its delivery record.
+* @param content - the file text.
+* @param dir - the skill's directory (its resource base).
+* @param path - the absolute `SKILL.md` path.
+* @returns the record, or undefined when the frontmatter is unusable.
+*/
+function managedSkillFrom(content, dir, path) {
+	const split = splitFrontmatter(content);
+	if (split === void 0) return void 0;
+	const name = frontmatterScalar(split.front, "name");
+	const description = frontmatterScalar(split.front, "description");
+	if (name === void 0 || description === void 0 || !KEBAB_ID.test(name)) return void 0;
+	const whenToUse = frontmatterScalar(split.front, "when-to-use") ?? frontmatterScalar(split.front, "whenToUse");
+	const presetScope = parsePresetScopeFrontmatter(split.front);
+	return {
+		name,
+		description,
+		...whenToUse === void 0 ? {} : { whenToUse },
+		modelInvocable: frontmatterFlag(split.front, "disable-model-invocation") !== true,
+		userInvocable: frontmatterFlag(split.front, "user-invocable") !== false,
+		presetScope,
+		dir,
+		path,
+		content
+	};
+}
+/** Whether this skill asks to be delivered to a specific preset set. */
+function isScoped(skill) {
+	return skill.presetScope !== void 0 && skill.presetScope.length > 0;
+}
+/** Project one managed skill onto a provider candidate for one preset. */
+function candidateFor(skill) {
+	return {
+		name: skill.name,
+		description: skill.description,
+		...skill.whenToUse === void 0 ? {} : { whenToUse: skill.whenToUse },
+		invocation: {
+			modelInvocable: skill.modelInvocable,
+			userInvocable: skill.userInvocable
+		},
+		source: "custom",
+		provider: SCOPED_PROVIDER_NAME,
+		rank: 300,
+		locator: skill.path,
+		path: skill.path,
+		metadata: { presetScope: [...skill.presetScope ?? []] },
+		resourceBase: {
+			kind: "directory",
+			path: skill.dir
+		}
+	};
+}
+/** Project one managed skill onto the complete definition the loader returns. */
+function definitionFor(skill) {
+	return {
+		...candidateFor(skill),
+		content: skill.content
+	};
+}
+/** The default roots a duplicate copy could live in. */
+function defaultSkillRoots(dshHome, workdir) {
+	const roots = [
+		join(dshHome, "skills"),
+		join(dshHome, ".agents", "skills"),
+		join(process.env.DSH_AGENTS_HOME ?? join(homedir(), ".agents"), "skills")
+	];
+	if (workdir !== void 0 && workdir !== "") roots.push(join(workdir, ".dsh", "skills"), join(workdir, ".agents", "skills"));
+	return roots;
+}
+/**
+* Find managed names that a default root also supplies.
+*
+* A duplicate is what makes a scope claim false: the host provider delivers the
+* default root's copy into every preset regardless of this module's decision.
+* @param skills - the managed entries under consideration.
+* @param dshHome - the harness home.
+* @param workdir - the session workspace, when known.
+* @returns skill name → the default root that already supplies it.
+*/
+function detectConflicts(skills, dshHome, workdir) {
+	const conflicts = /* @__PURE__ */ new Map();
+	for (const root of defaultSkillRoots(dshHome, workdir)) for (const skill of skills) {
+		if (conflicts.has(skill.name)) continue;
+		if (existsSync(join(root, skill.name, "SKILL.md")) || existsSync(join(root, `${skill.name}.md`))) conflicts.set(skill.name, root);
+	}
+	return conflicts;
+}
+/**
+* Scan the managed root for skill directories.
+* @param root - the managed skills root.
+* @returns every readable, usable entry, sorted by name.
+*/
+async function scanManagedSkills(root) {
+	let children;
+	try {
+		children = await readdir(root, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const found = [];
+	for (const child of children) {
+		if (!child.isDirectory() || !KEBAB_ID.test(child.name)) continue;
+		const dir = join(root, child.name);
+		const path = join(dir, "SKILL.md");
+		try {
+			const [content, info] = await Promise.all([readFile(path, "utf8"), stat(path)]);
+			if (!info.isFile()) continue;
+			const skill = managedSkillFrom(content, dir, path);
+			if (skill !== void 0) found.push(skill);
+		} catch {}
+	}
+	return found.sort((left, right) => left.name.localeCompare(right.name));
+}
+/** The sentinel preset id of the delivery that serves every preset. */
+const GLOBAL_PRESET = "*";
+/**
+* Delivers managed skills into the scope layers of the presets their
+* frontmatter names.
+*
+* Lifecycle: {@link start} once (watcher + first reconcile), {@link reconcile}
+* whenever policy or files may have changed, {@link dispose} when the owning
+* plugin unloads. Reconciliation never fails loudly: every problem becomes a
+* status field, because a catalog must not fail the boot of the instance it is
+* describing.
+*/
+var ScopedSkillDelivery = class {
+	ctx;
+	deps;
+	entries = [];
+	managed = [];
+	conflicts = /* @__PURE__ */ new Map();
+	presetErrors = /* @__PURE__ */ new Map();
+	watcher;
+	timer;
+	watching = false;
+	failure;
+	started = false;
+	disposed = false;
+	/** The probed registry's mount list (undefined until start()'s probe resolves). */
+	presetMounts;
+	/**
+	* @param ctx - the host context the delivery scopes are minted under.
+	* @param deps - borrowed services and paths, all optional at runtime.
+	*/
+	constructor(ctx, deps) {
+		this.ctx = ctx;
+		this.deps = deps;
+	}
+	/** Start watching the managed root and deliver what it currently holds. */
+	async start() {
+		if (this.started || this.disposed) return;
+		this.started = true;
+		this.presetMounts = (await loadPresetRegistry())?.livePresetMounts;
+		await this.ensureRoot();
+		this.watchRoot();
+		this.ctx.on("agent-preset/selected", () => {
+			this.reconcile();
+		});
+		await this.reconcile();
+	}
+	/** Re-read policy and files, then converge the delivery registrations. */
+	async reconcile() {
+		if (this.disposed) return;
+		const registry = this.deps.registry();
+		const roster = this.deps.roster();
+		if (registry?.registerProvider === void 0) {
+			this.failure = "the skill registry exposes no provider registration";
+			this.disposeEntries();
+			this.managed = [];
+			return;
+		}
+		if (roster?.standingKeyFor === void 0 && roster?.acquireScope === void 0) {
+			this.failure = "no agent-preset roster is composed";
+			this.disposeEntries();
+			this.managed = [];
+			return;
+		}
+		const root = this.root();
+		this.managed = await scanManagedSkills(root);
+		this.conflicts = detectConflicts(this.managed, this.deps.dshHome(), this.deps.workdir?.());
+		const byPreset = /* @__PURE__ */ new Map();
+		for (const skill of this.managed) {
+			if (!isScoped(skill) || this.conflicts.has(skill.name)) continue;
+			for (const presetId of skill.presetScope ?? []) {
+				const list = byPreset.get(presetId) ?? [];
+				list.push(skill);
+				byPreset.set(presetId, list);
+			}
+		}
+		const unscoped = this.managed.filter((skill) => !this.conflicts.has(skill.name) && !isScoped(skill));
+		this.presetErrors = /* @__PURE__ */ new Map();
+		const live = this.liveKeys();
+		const resolved = /* @__PURE__ */ new Map();
+		for (const presetId of byPreset.keys()) resolved.set(presetId, await this.resolveKey(roster, presetId));
+		for (const entry of [...this.entries]) {
+			if (entry.presetId === GLOBAL_PRESET) continue;
+			if (!byPreset.has(entry.presetId)) {
+				await this.dropEntry(entry);
+				continue;
+			}
+			const wantedKey = resolved.get(entry.presetId);
+			if (wantedKey === entry.key) continue;
+			if (wantedKey !== void 0 && entry.key !== void 0 && live.has(entry.key)) continue;
+			await this.dropEntry(entry);
+		}
+		for (const presetId of byPreset.keys()) {
+			const key = resolved.get(presetId);
+			if (key === void 0) continue;
+			if (this.entries.some((entry) => entry.presetId === presetId && entry.key === key)) continue;
+			await this.register(presetId, key);
+		}
+		const globalEntry = this.entries.find((entry) => entry.presetId === GLOBAL_PRESET);
+		if (unscoped.length > 0) {
+			if (globalEntry === void 0) await this.registerGlobal();
+		} else if (globalEntry !== void 0) await this.dropEntry(globalEntry);
+		this.failure = void 0;
+		this.invalidateAll();
+	}
+	/** The current status, for the settings surface and the model-facing tool. */
+	status() {
+		const delivered = /* @__PURE__ */ new Set();
+		for (const entry of this.entries) for (const skill of this.skillsFor(entry.presetId)) delivered.add(skill.name);
+		const skills = this.managed.map((skill) => {
+			const conflict = this.conflicts.get(skill.name);
+			return {
+				name: skill.name,
+				description: skill.description,
+				modelInvocable: skill.modelInvocable,
+				userInvocable: skill.userInvocable,
+				path: skill.path,
+				presets: [...skill.presetScope ?? []],
+				delivered: delivered.has(skill.name),
+				...conflict === void 0 ? {} : { conflict: join(conflict, skill.name) }
+			};
+		});
+		const presets = [...new Set(this.entries.map((entry) => entry.presetId))].sort((left, right) => left.localeCompare(right)).map((presetId) => {
+			const skills = this.managed.filter((skill) => !this.conflicts.has(skill.name) && (skill.presetScope ?? []).includes(presetId)).map((skill) => skill.name);
+			const error = this.presetErrors.get(presetId);
+			return {
+				presetId,
+				skills,
+				...error === void 0 ? {} : { error }
+			};
+		});
+		for (const [presetId, error] of this.presetErrors) if (!presets.some((row) => row.presetId === presetId)) presets.push({
+			presetId,
+			skills: [],
+			error
+		});
+		return {
+			enabled: this.failure === void 0 && this.entries.length > 0,
+			...this.failure === void 0 ? {} : { reason: this.failure },
+			root: this.root(),
+			watching: this.watching,
+			skills,
+			presets,
+			customRootsUnverifiable: true
+		};
+	}
+	/** Stop watching and dispose every delivery registration. */
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		this.timer = void 0;
+		this.watcher?.close();
+		this.watcher = void 0;
+		this.watching = false;
+		await this.disposeEntries();
+		this.managed = [];
+	}
+	/** The managed root under the current harness home. */
+	root() {
+		return scopedSkillsRoot(this.deps.dshHome());
+	}
+	/** Create the managed root if it is still absent. */
+	async ensureRoot() {
+		try {
+			await mkdir(this.root(), { recursive: true });
+		} catch (error) {
+			this.failure = `the managed root could not be created: ${describeError(error)}`;
+		}
+	}
+	/** Watch the managed root, degrading to on-demand rescans when it cannot. */
+	watchRoot() {
+		try {
+			this.watcher = watch(this.root(), { recursive: true }, () => this.scheduleRescan());
+			this.watching = true;
+		} catch (error) {
+			this.watching = false;
+			this.deps.log(`capability-catalog: managed root is not watched (${describeError(error)}); scope changes apply on the next reconcile`);
+		}
+	}
+	/** Coalesce a burst of filesystem events into one reconcile. */
+	scheduleRescan() {
+		if (this.timer !== void 0) clearTimeout(this.timer);
+		this.timer = setTimeout(() => {
+			this.timer = void 0;
+			this.reconcile().catch((error) => {
+				this.deps.log(`capability-catalog: scoped skill reconcile failed: ${describeError(error)}`);
+			});
+		}, RESCAN_DEBOUNCE_MS);
+	}
+	/** The standing keys that still have a live mount in this process. */
+	liveKeys() {
+		const keys = /* @__PURE__ */ new Set();
+		const livePresetMounts = this.presetMounts;
+		if (livePresetMounts === void 0) return keys;
+		try {
+			for (const mount of livePresetMounts()) if (mount.key !== void 0) keys.add(mount.key);
+		} catch {}
+		return keys;
+	}
+	/** Resolve one preset's standing key, remembering why it failed. */
+	async resolveKey(roster, presetId) {
+		try {
+			const read = await acquireStandingScope(roster, presetId);
+			try {
+				if (read.key === void 0) {
+					this.presetErrors.set(presetId, "the roster resolved no standing scope");
+					return;
+				}
+				return read.key;
+			} finally {
+				await read.dispose?.().catch((error) => {
+					this.deps.log(`capability-catalog: scope lease release failed: ${describeError(error)}`);
+				});
+			}
+		} catch (error) {
+			this.presetErrors.set(presetId, describeError(error));
+			return;
+		}
+	}
+	/** Register one delivery provider into a preset's layer. */
+	async register(presetId, key) {
+		const scope = createScope(this.ctx, key);
+		try {
+			const injected = await injectableScope(scope.ctx);
+			if (injected === void 0) {
+				await scope.dispose();
+				this.presetErrors.set(presetId, `the ${SKILLS_SERVICE} service was not injectable in the delivery scope`);
+				return;
+			}
+			let invalidate;
+			injected.skills.registerProvider((control) => {
+				invalidate = control.invalidate;
+				return this.providerFor(presetId, control);
+			});
+			this.entries.push({
+				presetId,
+				key,
+				dispose: () => scope.dispose(),
+				invalidate: () => invalidate?.()
+			});
+		} catch (error) {
+			await scope.dispose().catch(() => {});
+			this.presetErrors.set(presetId, `delivery scope could not be created: ${describeError(error)}`);
+		}
+	}
+	/** Register the provider that serves every preset (the unscoped skills). */
+	async registerGlobal() {
+		try {
+			const injected = await injectableScope(this.ctx);
+			if (injected === void 0) {
+				this.failure = `the ${SKILLS_SERVICE} service was not injectable for the global delivery`;
+				return;
+			}
+			let invalidate;
+			const dispose = injected.skills.registerProvider((control) => {
+				invalidate = control.invalidate;
+				return this.providerFor(GLOBAL_PRESET, control);
+			});
+			this.entries.push({
+				presetId: GLOBAL_PRESET,
+				dispose: () => {
+					dispose();
+				},
+				invalidate: () => invalidate?.()
+			});
+		} catch (error) {
+			this.failure = `the global delivery scope could not be created: ${describeError(error)}`;
+		}
+	}
+	/**
+	* The provider serving one preset. It reads only its own preset's assignment
+	* and re-reads the files, so a policy or content edit needs no re-registration
+	* beyond the invalidation reconcile already performs.
+	*/
+	providerFor(presetId, _control) {
+		return {
+			name: SCOPED_PROVIDER_NAME,
+			list: async () => this.skillsFor(presetId).map((skill) => candidateFor(skill)),
+			get: async (candidate) => {
+				const skill = this.skillsFor(presetId).find((entry) => entry.name === candidate.name);
+				return skill === void 0 ? void 0 : definitionFor(skill);
+			}
+		};
+	}
+	/** The managed skills one delivery currently serves. */
+	skillsFor(presetId) {
+		return this.managed.filter((skill) => !this.conflicts.has(skill.name) && (presetId === GLOBAL_PRESET ? !isScoped(skill) : (skill.presetScope ?? []).includes(presetId)));
+	}
+	/** Invalidate every registration's completed catalogs. */
+	invalidateAll() {
+		for (const entry of this.entries) entry.invalidate();
+	}
+	/** Dispose every registration. */
+	async disposeEntries() {
+		const entries = this.entries.splice(0, this.entries.length);
+		for (const entry of entries) try {
+			await entry.dispose();
+		} catch (error) {
+			this.deps.log(`capability-catalog: delivery scope disposal failed: ${describeError(error)}`);
+		}
+	}
+	/** Dispose one registration and forget it. */
+	async dropEntry(entry) {
+		const index = this.entries.indexOf(entry);
+		if (index >= 0) this.entries.splice(index, 1);
+		try {
+			await entry.dispose();
+		} catch (error) {
+			this.deps.log(`capability-catalog: delivery scope disposal failed: ${describeError(error)}`);
+		}
+	}
+};
+/** Render an unknown failure for a status field or a log line. */
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** The registry every delivery registration is made through. */
+const SKILLS_SERVICE = "skills";
+/** How long an injection may take before the registration is abandoned. */
+const INJECT_TIMEOUT_MS = 500;
+/**
+* A context within `scope` that may access the skill registry.
+*
+* A scope-minted context carries no dependency access by itself, and Cordis
+* resolves an `inject` callback after the current task — hence the bounded
+* await, which gives `reconcile()` a settled answer instead of a registration
+* that appears at some later tick.
+* @param scopeCtx - the context minted for one preset's standing key.
+* @returns the injected context, or undefined when it never became available.
+*/
+function injectableScope(scopeCtx) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = (value) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(value);
+		};
+		const timer = setTimeout(() => finish(void 0), INJECT_TIMEOUT_MS);
+		scopeCtx.inject([SKILLS_SERVICE], (injected) => finish(injected));
+	});
+}
+//#endregion
+//#region lib/types/scoped-edits.js
+/**
+* Writing side of preset-scoped delivery: rewrite one managed skill's
+* `metadata.presetScope`, adopt an installed skill into the managed root, and
+* release one back out.
+*
+* Every write here is deliberately narrow. The preset scope is edited in place
+* in the skill's OWN frontmatter (the same store the delivery reads), adoption
+* copies before it removes anything, and release refuses to overwrite an
+* existing default-root skill. Nothing deletes a managed skill: releasing is the
+* documented recovery direction, and a broken plugin must not take the user's
+* files with it.
+* @module @khorsheed/dsh-capability-catalog/scoped-edits
+*/
+/** Shared guard: every write path addresses one skill directory by name. */
+function invalidName(name) {
+	return isKebabId(name) ? void 0 : {
+		ok: false,
+		error: `"${name}" is not a valid skill name`
+	};
+}
+/**
+* Rewrite a SKILL.md's `metadata.presetScope` list.
+*
+* The frontmatter is edited line by line rather than re-serialized, so every
+* other key, comment, and quote in the file survives untouched. The canonical
+* inline form is written: `presetScope: []` for "every preset", otherwise
+* `presetScope: [a, b]`.
+* @param content - the current SKILL.md text.
+* @param presets - the preset ids to declare (deduplicated, order preserved).
+* @returns the rewritten file text.
+* @throws when the file has no frontmatter block to edit.
+*/
+function withPresetScope(content, presets) {
+	const split = splitFrontmatter(content);
+	if (split === void 0) throw new Error("the skill has no frontmatter block to edit");
+	const ids = [...new Set(presets)];
+	const lines = split.front.split("\n");
+	const kept = [];
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		const match = /^(\s*)presetScope\s*:/.exec(line);
+		if (match === null) {
+			kept.push(line);
+			continue;
+		}
+		const indent = (match[1] ?? "").length;
+		while (index + 1 < lines.length) {
+			const next = lines[index + 1] ?? "";
+			const entry = /^(\s*)-\s*/.exec(next);
+			if (entry === null || (entry[1] ?? "").length <= indent) break;
+			index += 1;
+		}
+	}
+	const rendered = `presetScope: [${ids.join(", ")}]`;
+	const metadataAt = kept.findIndex((line) => /^\s*metadata\s*:\s*$/.test(line));
+	if (metadataAt >= 0) {
+		const indent = (/^(\s*)/.exec(kept[metadataAt] ?? "")?.[1] ?? "").length + 2;
+		kept.splice(metadataAt + 1, 0, `${" ".repeat(indent)}${rendered}`);
+	} else if (kept.some((line) => line.trim() !== "")) kept.push("metadata:", `  ${rendered}`);
+	else kept.push("metadata:", `  ${rendered}`);
+	return `---\n${kept.join("\n")}\n---\n${split.body}`;
+}
+/** Find the managed entry for one skill name. */
+async function managedLocation(dshHome, name) {
+	const skill = (await scanManagedSkills(scopedSkillsRoot(dshHome))).find((entry) => entry.name === name);
+	if (skill === void 0) return void 0;
+	return {
+		name: skill.name,
+		path: skill.path,
+		dir: skill.dir
+	};
+}
+/** Write a file through a sibling temp file and one atomic rename. */
+async function writeAtomic(path, content) {
+	const temp = join(dirname(path), `.${Date.now()}-${process.pid}.tmp`);
+	await writeFile(temp, content, "utf8");
+	await rename(temp, path);
+}
+/**
+* Set one managed skill's preset scope.
+* @param dshHome - the harness home owning the managed root.
+* @param name - the skill name (its directory under the managed root).
+* @param presets - the preset ids to declare.
+* @returns the outcome, with a reason on failure.
+*/
+async function setManagedPresetScope(dshHome, name, presets) {
+	const badName = invalidName(name);
+	if (badName !== void 0) return badName;
+	const location = await managedLocation(dshHome, name);
+	if (location === void 0) return {
+		ok: false,
+		error: `"${name}" is not a managed skill`
+	};
+	try {
+		const content = await readFile(location.path, "utf8");
+		const updated = withPresetScope(content, presets);
+		if (updated !== content) await writeAtomic(location.path, updated);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: messageOf(error)
+		};
+	}
+}
+/**
+* Locate one skill in the default roots.
+* @param dshHome - the harness home.
+* @param workdir - the session workspace, when known.
+* @param name - the skill name.
+* @returns the source found, or undefined.
+*/
+function findSkillSource(dshHome, workdir, name) {
+	for (const root of defaultSkillRoots(dshHome, workdir)) {
+		const dir = join(root, name);
+		if (existsSync(join(dir, "SKILL.md"))) return {
+			root,
+			dir
+		};
+		const file = join(root, `${name}.md`);
+		if (existsSync(file)) return {
+			root,
+			file
+		};
+	}
+}
+/**
+* Move an installed skill into the managed root and declare its preset scope.
+*
+* Order matters: the source is only removed after the copy has been committed
+* and the scope written, so a failure at any step leaves one complete copy
+* behind. The copy lands as a temp sibling and is committed with one rename, so
+* the managed root never holds a half-written skill.
+* @param dshHome - the harness home.
+* @param name - the skill name.
+* @param presets - the preset ids to declare.
+* @param workdir - the session workspace, when known.
+* @returns the outcome, with a reason on failure.
+*/
+async function adoptManagedSkill(dshHome, name, presets, workdir) {
+	const badName = invalidName(name);
+	if (badName !== void 0) return badName;
+	const root = scopedSkillsRoot(dshHome);
+	const target = join(root, name);
+	if (existsSync(target)) return {
+		ok: false,
+		error: `the managed root already holds "${name}"`
+	};
+	const source = findSkillSource(dshHome, workdir, name);
+	if (source === void 0) return {
+		ok: false,
+		error: `"${name}" was not found in a default skill root`
+	};
+	const staging = join(root, `.${name}-${process.pid}`);
+	try {
+		await mkdir(root, { recursive: true });
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		if (source.dir !== void 0) await cp(source.dir, staging, { recursive: true });
+		else {
+			await mkdir(staging, { recursive: true });
+			await writeFile(join(staging, "SKILL.md"), await readFile(source.file ?? "", "utf8"), "utf8");
+		}
+		const staged = join(staging, "SKILL.md");
+		const content = await readFile(staged, "utf8");
+		await writeFile(staged, withPresetScope(content, presets), "utf8");
+		await rename(staging, target);
+	} catch (error) {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		return {
+			ok: false,
+			error: messageOf(error)
+		};
+	}
+	try {
+		if (source.dir !== void 0) await rm(source.dir, {
+			recursive: true,
+			force: true
+		});
+		else if (source.file !== void 0) await rm(source.file, { force: true });
+	} catch (error) {
+		return {
+			ok: false,
+			error: `adopted "${name}", but the default-root copy could not be removed: ${messageOf(error)}`
+		};
+	}
+	return { ok: true };
+}
+/**
+* Move a managed skill back to the user skill root — the recovery direction.
+*
+* A managed skill is delivered by this plugin, so releasing it restores plain
+* filesystem behavior that survives the plugin being removed.
+* @param dshHome - the harness home.
+* @param name - the skill name.
+* @returns the outcome, with a reason on failure.
+*/
+async function releaseManagedSkill(dshHome, name) {
+	const badName = invalidName(name);
+	if (badName !== void 0) return badName;
+	const location = await managedLocation(dshHome, name);
+	if (location === void 0) return {
+		ok: false,
+		error: `"${name}" is not a managed skill`
+	};
+	const target = join(dshHome, "skills", name);
+	if (existsSync(target)) return {
+		ok: false,
+		error: `"${name}" already exists in ${join(dshHome, "skills")}`
+	};
+	try {
+		await mkdir(dirname(target), { recursive: true });
+		await cp(location.dir, target, { recursive: true });
+		await rm(location.dir, {
+			recursive: true,
+			force: true
+		});
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: messageOf(error)
+		};
+	}
+}
+/** Whether a path exists and is a directory. */
+async function isDirectory(path) {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** Render an unknown failure. */
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region lib/types/shellEnv.js
+/**
+* Skill env injection via the official `ctx.shellEnv` seam (service-agnostic).
+*
+* The catalog lets a user configure a credential for a skill's declared env var
+* (e.g. `$WEREED_API_KEY`). That value is NOT in `process.env` — the launch env
+* is a read-only snapshot and never injects credentials. This module registers
+* a `ctx.shellEnv` contributor that exposes each configured credential as a
+* trusted, per-execution `DSH_<KEY>` variable. The model references it by shell
+* expansion (`--key="$DSH_WEREED_API_KEY"`) so the raw value never enters the
+* model's context; it only becomes visible if the model (or a command) actively
+* prints it — a default-hide, not a hard secret boundary.
+*
+* Constraint handling (shell-env/src/index.ts):
+* - keys must start `DSH_` and match `/^[A-Z][A-Z0-9_]*$/`; one owner per key;
+*   reserved built-ins (`DSH_HOME`/`DSH_SHELL`/`DSH_SESSION_ID`) are not ownable.
+* - `resolve()` is synchronous; credential reads are async, so values live in a
+*   cache (`envCache`) refreshed on apply + on `credentials/*-updated`.
+*
+* Robustness (addressed for the review):
+* - read the ref namespace: `credentials.resolve(credentialRef(key))` (value from
+*   the .credentials store that `setCredential` writes) — never `readRecord`.
+* - filter env keys that map onto reserved (`HOME`/`SHELL`/`SESSION_ID`) or are
+*   already owned by another contributor (e.g. `DSH_SESSION_JSONL`) so a single
+*   bad/conflicting key cannot break the whole registration; skip + warn.
+* - use a *declared superset*: register the full valid key set once and keep it;
+*   deleting a credential just makes `resolve` return empty (no delete-then-
+*   re-register window). Re-register only when the key SET changes.
+* - serialise refresh (single in-flight + queued) and gate commits on a
+*   generation counter + `disposed` so a stale run cannot overwrite or
+*   re-register after dispose.
+* @module @khorsheed/dsh-capability-catalog/shellEnv
+*/
+const DSH_PREFIX$1 = "DSH_";
+const ENV_KEY_SUFFIX = /^[A-Z][A-Z0-9_]*$/;
+/** Reserved `DSH_*` names the host's shell-env registry owns as built-in facts
+* (the instance's real HOME / SHELL / SESSION_ID). A credential must never be
+* allowed to take one of these over — a mapped value shadowing the built-in
+* `DSH_HOME` would make the agent read the configured credential as the
+* instance home. Keyed on the MAPPED name (not the raw declaration), so it
+* matches the upstream registry's own reserved set (dsh-home-paths/dsh-shell)
+* and survives prefix/schema drift. The catalog's own `DSH_`-prefixed keys are
+* unaffected: declaring e.g. `DSH_HOME` maps to `DSH_DSH_HOME`, which is not a
+* reserved name and never collides. */
+const RESERVED_ENV_KEYS = /* @__PURE__ */ new Set([
+	"DSH_HOME",
+	"DSH_SHELL",
+	"DSH_SESSION_ID"
+]);
+/**
+* Install the skill env injection contributor. Returns a disposer; the `ctx.on`
+* and `shellEnv.register` disposers are also effect-scoped to the calling fiber.
+* Degrades silently (a no-op) when `shellEnv`, `credentials`, or `skills` is
+* absent in the composition.
+*
+* Boot-timing robustness: the contributor's `register()` runs `ctx.effect(...)`
+* internally, so it must be called while its backing fiber is still `active`
+* (alpha's reordered app-boot can leave it in a transient inactive window where
+* a captured reference would throw `INACTIVE_EFFECT`). This install never caches
+* a service reference across an `await`; it re-reads `ctx.get` (strict — returns
+* the impl only while its fiber is active) immediately before calling `register`,
+* and self-retries on `INACTIVE_EFFECT` so it self-heals once boot stabilizes.
+*/
+function installSkillEnvInjection(ctx, getScope) {
+	let disposed = false;
+	let envCache = /* @__PURE__ */ new Map();
+	let disposeEnv;
+	let refreshKey;
+	let refreshGen = 0;
+	let inFlight;
+	let queued = false;
+	let retryTimer;
+	let retries = 0;
+	const MAX_RETRIES = 30;
+	const RETRY_DELAY = 300;
+	const cancelRetry = () => {
+		if (retryTimer !== void 0) {
+			clearTimeout(retryTimer);
+			retryTimer = void 0;
+		}
+	};
+	const scheduleRetry = () => {
+		if (disposed || retries >= MAX_RETRIES) return;
+		cancelRetry();
+		retries++;
+		retryTimer = setTimeout(() => {
+			retryTimer = void 0;
+			if (!disposed) refresh();
+		}, RETRY_DELAY);
+	};
+	/** True for the `INACTIVE_EFFECT` Cordis error thrown by `ctx.effect` when the
+	* fiber is inactive — a transient boot-time race, not a real owner collision. */
+	const isInactiveEffect = (err) => {
+		return !!err && typeof err === "object" && "code" in err && err.code === "INACTIVE_EFFECT";
+	};
+	/** One refresh pass; commits only if still the latest generation and not disposed. */
+	const refresh = async () => {
+		if (disposed) return;
+		if (inFlight !== void 0) {
+			refreshGen++;
+			queued = true;
+			return;
+		}
+		const shellEnv = ctx.get?.("shellEnv");
+		const credentials = ctx.get?.("credentials");
+		const skills = ctx.get?.("skills");
+		if (shellEnv?.register === void 0 || credentials === void 0 || skills === void 0) {
+			scheduleRetry();
+			return;
+		}
+		const gen = ++refreshGen;
+		inFlight = (async () => {
+			const scope = await getScope().catch(() => void 0);
+			const snapshotOptions = scope === void 0 ? {} : { scope };
+			try {
+				const snapshot = await skills.snapshot(snapshotOptions);
+				const occupied = new Set((shellEnv.list?.() ?? []).filter((e) => e.contributor !== "capability-catalog").map((e) => e.key));
+				const keys = /* @__PURE__ */ new Set();
+				const values = /* @__PURE__ */ new Map();
+				for (const row of snapshot.skills) {
+					if (row.invocation?.modelInvocable === false) continue;
+					let def;
+					try {
+						def = await skills.get(row.name, snapshotOptions);
+					} catch {
+						continue;
+					}
+					if (def === void 0) continue;
+					const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ""));
+					for (const decl of decls) {
+						if (!ENV_KEY_SUFFIX.test(decl.key)) continue;
+						const dshKey = `${DSH_PREFIX$1}${decl.key}`;
+						if (RESERVED_ENV_KEYS.has(dshKey) || occupied.has(dshKey)) continue;
+						keys.add(decl.key);
+						const resolved = await credentials.resolve(decl.key).catch(() => void 0);
+						if (resolved !== void 0 && resolved.value.length > 0) values.set(dshKey, resolved.value);
+					}
+				}
+				if (disposed || gen !== refreshGen) return;
+				envCache = values;
+				const keySet = [...keys].sort().join("\n");
+				if (keySet !== refreshKey) {
+					disposeEnv?.();
+					disposeEnv = void 0;
+					refreshKey = void 0;
+					const variables = {};
+					for (const k of keys) variables[`${DSH_PREFIX$1}${k}`] = { description: `Configured via the capability catalog for skill env \`${k}\`` };
+					const shellEnvNow = ctx.get?.("shellEnv");
+					if (shellEnvNow?.register === void 0) {
+						scheduleRetry();
+						return;
+					}
+					try {
+						disposeEnv = shellEnvNow.register({
+							name: "capability-catalog",
+							variables,
+							resolve: () => {
+								const out = {};
+								for (const [k, v] of envCache) if (Object.hasOwn(variables, k)) out[k] = v;
+								return out;
+							}
+						});
+						refreshKey = keySet;
+						retries = 0;
+					} catch (err) {
+						process.stderr.write(`capability-catalog: skill env contributor register failed (${String(err)})`);
+						if (isInactiveEffect(err)) scheduleRetry();
+					}
+				}
+			} catch (err) {
+				process.stderr.write(`capability-catalog: skill env injection refresh failed (${String(err)})`);
+			} finally {
+				inFlight = void 0;
+				if (queued && !disposed) {
+					queued = false;
+					refresh();
+				}
+			}
+		})();
+		await inFlight;
+	};
+	refresh();
+	const offRecord = ctx.on("credentials/record-updated", () => {
+		refresh();
+	});
+	const offReference = ctx.on("credentials/reference-updated", () => {
+		refresh();
+	});
+	return () => {
+		disposed = true;
+		cancelRetry();
+		disposeEnv?.();
+		offRecord();
+		offReference();
+	};
+}
+//#endregion
+//#region lib/types/mcps.js
+/** Find every `secretRef:<token>` marker in a config value (scheme-prefixed or bare). */
+const SECRET_REF_RE = /secretRef:([A-Za-z0-9_.-]+)/g;
+/** Flag a config field secret in the read-only display: `secretRef:x → ·secretRef·`,
+* preserving any scheme prefix (e.g. `Bearer ·secretRef·`). */
+function maskSecret(value) {
+	return value.replace(SECRET_REF_RE, "·secretRef·");
+}
+/** Mask a server config for the wire (the Remote DTO): replace every `secretRef:`
+* marker (bare or scheme-prefixed) with `·secretRef·`, so neither the secret key
+* name nor the marker is exposed to the browser. */
+function maskConfig(config) {
+	const env = (config.env ?? []).map(([k, v]) => [k, maskSecret(v)]);
+	const headers = (config.headers ?? []).map(([k, v]) => [k, maskSecret(v)]);
+	const url = config.url !== void 0 ? maskSecret(config.url) : void 0;
+	return {
+		...config,
+		...env.length > 0 ? { env } : {},
+		...headers.length > 0 ? { headers } : {},
+		...url !== void 0 ? { url } : {}
+	};
+}
+/** Resolve `secretRef:` markers in a config into plaintext before connecting
+* (the catalog resolves via the stored credential values, then connects).
+* Replaces embedded markers too, so a scheme-prefixed value (`Bearer secretRef:a`)
+* resolves to `Bearer <value>`. */
+async function resolveConfigSecrets(config, resolve) {
+	const resolveValue = async (value) => {
+		let out = value;
+		for (const m of value.matchAll(SECRET_REF_RE)) {
+			const ref = m[1];
+			const resolvedValue = await resolve(ref) ?? "";
+			out = out.replace(`secretRef:${ref}`, resolvedValue);
+		}
+		return out;
+	};
+	const env = [];
+	for (const [k, v] of config.env ?? []) env.push([k, await resolveValue(v)]);
+	const headers = [];
+	for (const [k, v] of config.headers ?? []) headers.push([k, await resolveValue(v)]);
+	const url = config.url !== void 0 ? await resolveValue(config.url) : void 0;
+	return {
+		...config,
+		...env.length > 0 ? { env } : {},
+		...headers.length > 0 ? { headers } : {},
+		...url !== void 0 ? { url } : {}
+	};
+}
+//#endregion
+//#region lib/types/mcpStore.js
+/**
+* Host-side MCP server store: keeps the user's configured MCP servers, their
+* discovered tools, credential state, and enable flags. Persistence is a pluggable
+* seam: the host hands the store an `onPersist` callback (backed by the settings
+* namespace) and seeds it with `loadFrom` at boot, so servers survive a restart.
+* Tool discovery connects via the SDK connector and caches the tool list.
+*/
+/** The catalog's own MCP management store (one per process). */
+var McpStore = class {
+	servers = /* @__PURE__ */ new Map();
+	/** Persistence hook, set by the host after the settings scope is available. */
+	onPersist = void 0;
+	/** Seed the store from the persisted state (boot or external config edit). */
+	loadFrom(state) {
+		if (state === void 0) return;
+		for (const server of state.servers ?? []) {
+			const existing = this.servers.get(server.config.serverName);
+			const known = new Map((existing?.tools ?? []).map((t) => [t.name, t]));
+			const tools = (server.tools ?? []).map((t) => {
+				const prev = known.get(t.name);
+				return prev !== void 0 ? {
+					...prev,
+					enabled: t.enabled
+				} : {
+					name: t.name,
+					description: "",
+					enabled: t.enabled
+				};
+			});
+			this.servers.set(server.config.serverName, {
+				config: server.config,
+				credentials: existing?.credentials ?? /* @__PURE__ */ new Map(),
+				tools,
+				error: void 0
+			});
+		}
+		for (const [ref, value] of Object.entries(state.credentials ?? {})) {
+			const s = this.servers.get(refServer(ref));
+			if (s !== void 0) s.credentials.set(ref, value);
+		}
+	}
+	/** Serialize the current state for persistence. */
+	toPersisted() {
+		const servers = [...this.servers.values()].sort((a, b) => a.config.serverName.localeCompare(b.config.serverName)).map((s) => ({
+			config: s.config,
+			tools: s.tools.map((t) => ({
+				name: t.name,
+				enabled: t.enabled
+			}))
+		}));
+		const credentials = {};
+		for (const s of this.servers.values()) for (const [ref, value] of s.credentials) credentials[ref] = value;
+		return {
+			servers,
+			credentials
+		};
+	}
+	persist() {
+		this.onPersist?.();
+	}
+	list() {
+		return [...this.servers.values()].map((s) => ({
+			...s.config,
+			enabled: s.config.enabled
+		})).sort((a, b) => a.serverName.localeCompare(b.serverName));
+	}
+	/** Discovered tool list per server (name → tools). */
+	toolsByServer() {
+		const out = {};
+		for (const [name, s] of this.servers) out[name] = s.tools;
+		return out;
+	}
+	/** Credential declarations for all servers (whether configured, never the value). */
+	credentials() {
+		const out = [];
+		for (const [name, s] of this.servers) for (const ref of this.credentialRefsOf(s.config)) out.push({
+			ref,
+			label: refLabel(ref),
+			configured: s.credentials.has(ref)
+		});
+		return out;
+	}
+	/** Add / replace a server config (keeps its credentials if already present). */
+	add(config) {
+		const existing = this.servers.get(config.serverName);
+		this.servers.set(config.serverName, {
+			config,
+			credentials: existing?.credentials ?? /* @__PURE__ */ new Map(),
+			tools: existing?.tools ?? [],
+			error: existing?.error
+		});
+		this.persist();
+	}
+	remove(serverName) {
+		if (this.servers.delete(serverName)) this.persist();
+	}
+	/** Set server-level enable flag (discovery/registration is the caller's job). */
+	setEnabled(serverName, enabled) {
+		const s = this.servers.get(serverName);
+		if (s === void 0) return;
+		s.config = {
+			...s.config,
+			enabled
+		};
+		this.persist();
+	}
+	/** Set one credential value (empty clears it). */
+	setCredential(ref, value) {
+		const serverName = refServer(ref);
+		const s = this.servers.get(serverName);
+		if (s === void 0) return;
+		if (value === "") s.credentials.delete(ref);
+		else s.credentials.set(ref, value);
+		this.persist();
+	}
+	/** Configure a tool's enable flag. */
+	setToolEnabled(serverName, toolName, enabled) {
+		const s = this.servers.get(serverName);
+		if (s === void 0) return;
+		s.tools = s.tools.map((t) => t.name === toolName ? {
+			...t,
+			enabled
+		} : t);
+		this.persist();
+	}
+	/** Connect + discover tools for a server; caches the list (connect errors surface). */
+	async discover(serverName) {
+		const s = this.servers.get(serverName);
+		if (s === void 0) return [];
+		try {
+			const { connectMcpServer } = await import("./mcpConnector-C2TbkPBY.js");
+			const connection = await connectMcpServer(await resolveConfigSecrets(s.config, async (ref) => {
+				const candidates = [
+					`mcp.${serverName}.env.${ref}`,
+					`mcp.${serverName}.header.${ref}`,
+					`mcp.${serverName}.query.${ref}`
+				];
+				for (const candidate of candidates) {
+					const value = s.credentials.get(candidate);
+					if (value !== void 0) return value;
+				}
+			}));
+			const prevEnabled = new Map(s.tools.map((t) => [t.name, t.enabled]));
+			s.tools = connection.tools.map((t) => ({
+				...t,
+				enabled: prevEnabled.get(t.name) ?? true
+			}));
+			s.error = void 0;
+			await connection.close();
+			this.persist();
+			return s.tools;
+		} catch (error) {
+			s.error = String(error);
+			this.persist();
+			return s.tools;
+		}
+	}
+	/** Re-connect + re-discover every enabled server — boot-time refill of the
+	* discovered descriptions/parameters (the persisted block stores only
+	* name+enabled). Preserves per-tool enable flags; per-server errors are
+	* recorded and do not stop the others. */
+	async reconnectAll() {
+		for (const server of this.list()) {
+			if (!server.enabled) continue;
+			await this.discover(server.serverName);
+		}
+	}
+	/** A server's most recent connection/dev error. */
+	errorOf(serverName) {
+		return this.servers.get(serverName)?.error;
+	}
+	/** Forward one tool call to a server (connect → call → close). Resolves secrets. */
+	async callTool(serverName, rawName, args) {
+		const s = this.servers.get(serverName);
+		if (s === void 0) throw new Error(`unknown MCP server: ${serverName}`);
+		const resolved = await resolveConfigSecrets(s.config, async (ref) => {
+			const candidates = [
+				`mcp.${serverName}.env.${ref}`,
+				`mcp.${serverName}.header.${ref}`,
+				`mcp.${serverName}.query.${ref}`
+			];
+			for (const candidate of candidates) {
+				const value = s.credentials.get(candidate);
+				if (value !== void 0) return value;
+			}
+		});
+		const { connectMcpServer } = await import("./mcpConnector-C2TbkPBY.js");
+		const connection = await connectMcpServer(resolved);
+		try {
+			return await connection.call(rawName, args);
+		} finally {
+			await connection.close();
+		}
+	}
+	/** Extract credential reference paths from a config (env/header/url-query).
+	* Namespaced `mcp.<serverName>.env.<KEY>` so multiple servers don't collide. */
+	credentialRefsOf(config) {
+		const refs = [];
+		for (const [k, v] of config.env ?? []) if (isSecretRef(v)) refs.push(`mcp.${config.serverName}.env.${k}`);
+		for (const [k, v] of config.headers ?? []) if (isSecretRef(v)) refs.push(`mcp.${config.serverName}.header.${k}`);
+		if (config.url !== void 0) for (const m of config.url.matchAll(/secretRef:([A-Za-z0-9_.-]+)/g)) refs.push(`mcp.${config.serverName}.query.${m[1]}`);
+		return refs;
+	}
+};
+/** Whether a config value contains an unresolved secret marker (bare or scheme-prefixed). */
+function isSecretRef(value) {
+	return value.includes("secretRef:");
+}
+/** Human label for a namespaced ref (strip the `mcp.<server>.` prefix). */
+function refLabel(ref) {
+	const idx = ref.indexOf(".");
+	return ref.slice(idx + 1);
+}
+/** The server name a namespaced credential ref belongs to (`mcp.<server>…`). */
+function refServer(ref) {
+	return /^mcp\.([A-Za-z0-9_-]+)\./.exec(ref)?.[1] ?? "";
+}
+//#endregion
+//#region lib/types/mcpTools.js
+/**
+* MCP tool bridge: turns catalog-discovered MCP tools into harness `ToolDefinition`s
+* registered on `ctx.tools` so the model can call them. A bounded subset of the
+* official mcp-client bridge — the common text-result case (no image/attachment
+* projection, no task execution). Model-facing names follow the stable
+* `mcp__<serverName>__<rawName>` contract, normalized to the DeepSeek
+* function-name constraints; the raw name is only ever sent on the wire.
+*
+* Registration must always invoke `ctx.tools.register(definition)` as a MEMBER
+* call on the traceable service proxy (never extract `register` to a standalone
+* variable) — the proxy resolves `this.ctx` (effect/scope ownership) from the
+* calling context, which a bare function reference loses.
+* @module @khorsheed/dsh-capability-catalog/mcpTools
+*/
+/** DeepSeek function-name contract: at most 64 characters. */
+const MAX_PUBLIC_NAME_LENGTH = 64;
+/** DeepSeek function-name contract: only `[A-Za-z0-9_-]` is allowed. */
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g;
+/** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
+const HASH_LENGTH = 12;
+/** Deterministic model-facing name for `(serverName, rawName)`. */
+function publicToolName(serverName, rawName) {
+	const joined = `mcp__${serverName}__${rawName}`;
+	const normalized = joined.replace(INVALID_NAME_CHARS, "_");
+	if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized;
+	const hash = createHash("sha256").update(joined).digest("hex").slice(0, HASH_LENGTH);
+	return `${normalized.slice(0, 51)}_${hash}`;
+}
+/** Coerce a raw MCP inputSchema into a JSON Schema object the registry accepts. */
+function sanitizeParameters(parameters) {
+	if (parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)) return parameters;
+	return {
+		type: "object",
+		properties: {}
+	};
+}
+/** Map the SDK `callTool` result to the canonical `{ content, structuredContent }`. */
+function normalizeResult(result) {
+	const r = result ?? {};
+	if (r.isError === true) throw new Error(r.error ?? "MCP tool reported an error");
+	return {
+		content: Array.isArray(r.content) ? r.content : [],
+		...r.structuredContent !== void 0 ? { structuredContent: r.structuredContent } : {}
+	};
+}
+/** Extract human-readable text from MCP content blocks (text blocks joined). */
+function extractText(content) {
+	const blocks = Array.isArray(content) ? content : [];
+	const texts = blocks.filter((b) => typeof b === "object" && b !== null && b.type === "text" && typeof b.text === "string").map((b) => b.text);
+	return texts.length > 0 ? texts.join("\n") : JSON.stringify(blocks);
+}
+/** Build a harness `ToolDefinition` for one discovered MCP tool. */
+function mcpToolDefinition(opts) {
+	const { publicName, rawName, serverName, description, parameters, callTool } = opts;
+	return {
+		name: publicName,
+		description,
+		parameters: sanitizeParameters(parameters),
+		output: {
+			schema: {
+				type: "object",
+				properties: { content: {
+					type: "array",
+					items: {}
+				} },
+				required: ["content"],
+				additionalProperties: true
+			},
+			render: (_args, value) => {
+				return [{
+					type: "text",
+					text: extractText(value.content)
+				}];
+			}
+		},
+		execute: async (args) => {
+			return normalizeResult(await callTool(serverName, rawName, args ?? {}));
+		}
+	};
+}
+/**
+* Reconcile registered MCP tools: dispose every previously-registered tool, then
+* register the desired set. Registration failures are contained per tool.
+*/
+function reconcileRegisteredMcpTools(desired, registry, current, callTool) {
+	for (const dispose of [...current.values()]) dispose();
+	current.clear();
+	for (const d of desired) try {
+		const dispose = registry.register(mcpToolDefinition({
+			publicName: d.publicName,
+			serverName: d.serverName,
+			rawName: d.rawName,
+			description: d.description,
+			parameters: d.parameters,
+			callTool
+		}));
+		current.set(d.publicName, dispose);
+	} catch (error) {
+		registry.onRegisterError?.(error);
+	}
+}
+/** Compute the desired set from enabled servers + their enabled tools. */
+function desiredMcpTools(servers, toolsByServer) {
+	const desired = [];
+	for (const server of servers) {
+		if (!server.enabled) continue;
+		for (const tool of toolsByServer[server.serverName] ?? []) {
+			if (!tool.enabled) continue;
+			desired.push({
+				publicName: publicToolName(server.serverName, tool.name),
+				serverName: server.serverName,
+				rawName: tool.name,
+				description: tool.description,
+				parameters: tool.parameters
+			});
+		}
+	}
+	return desired;
+}
+//#endregion
+//#region lib/types/envHint.js
+/**
+* Skill env hint via `tools/post-execute` — a runtime companion context that
+* tells the model about any skill's configured credential env mappings.
+*
+* The catalog injects credentials as trusted per-execution `DSH_<KEY>` env
+* vars (see shellEnv.ts), but a skill's own text references the original
+* `$KEY` name and the model does not derive the alias on its own. This module
+* observes `tools/post-execute` when the `skill` tool loads a skill and appends
+* a generic, per-skill note listing each configured mapping, so the model can
+* use the value without us modifying the user's SKILL.md.
+*
+* Generic: it derives the mappings from the loaded skill's own env-decl keys
+* (decodeEnvDecls) + the credential store, so any future key / skill is
+* covered. It never touches the skill file or the provider's returned content.
+* @module @khorsheed/dsh-capability-catalog/envHint
+*/
+const DSH_PREFIX = "DSH_";
+/** Subscribe to `tools/post-execute`; appends an env-mapping hint for the
+* loaded skill. Returns a disposer. Degrades silently when tools/registry/
+* credentials are absent or the tool is not the skills loader. */
+function installSkillEnvHint(ctx, getScope) {
+	ctx.inject(["tools"], () => {
+		ctx.on("tools/post-execute", (async (exec, _result, next) => {
+			if (exec?.name !== "skill") return next();
+			const skillName = exec.arguments?.name;
+			if (typeof skillName !== "string" || skillName.length === 0) return next();
+			const scope = await getScope().catch(() => void 0);
+			const { registry, credentials } = resolveServices(ctx);
+			if (registry === void 0 || credentials === void 0) return next();
+			const lookup = scope === void 0 ? {} : { scope };
+			let def;
+			try {
+				def = await registry.get(skillName, lookup);
+			} catch {
+				return next();
+			}
+			if (def === void 0) return next();
+			const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ""));
+			const configured = [];
+			for (const decl of decls) if ((await credentials.describe(decl.key).catch(() => void 0))?.configured === true) configured.push(decl.key);
+			if (configured.length === 0) return next();
+			const hint = [
+				`Runtime credential mapping for ${skillName}:`,
+				...configured.map((k) => `- ${k} is configured; in the model shell it is available as ${DSH_PREFIX}${k}. Use it as ${k}="${DSH_PREFIX}${k}" <command>.`),
+				`Do not search dotenv files or ask the user for this credential, and do not print either variable.`
+			].join("\n");
+			return {
+				kind: "accept",
+				additionalContexts: [{
+					id: `capability-catalog-env-hint-${skillName}`,
+					role: "user",
+					content: [{
+						type: "text",
+						text: hint
+					}],
+					source: {
+						kind: "capability-catalog",
+						plugin: "capability-catalog",
+						form: "env-hint"
+					}
+				}]
+			};
+		}));
+	});
+}
+//#endregion
+//#region lib/types/tool-origin.js
+/**
+* Community tool-origin convention: a host-side tag a plugin attaches to a tool
+* definition BEFORE `ctx.tools.register`, so the catalog can attribute the tool
+* to `plugin` (and any channel) instead of relying on heuristics.
+*
+* The harness `ToolSchema` carries no source/owner field and the system-prompt
+* assembly projects tools to `{ name, description, parameters }`, so the tag must
+* live on the retained `ToolDefinition` and be read via `ctx.tools.get(name)`
+* (the registry keeps the definition by reference, so the symbol survives).
+* The key is `Symbol.for('dsh.tool.origin')` (global symbol registry) — a plugin
+* may tag without importing anything, using `def[Symbol.for('dsh.tool.origin')]`.
+* `setToolOrigin` is the convenience form exported for the catalog's own plugins.
+* @module @khorsheed/dsh-capability-catalog/tool-origin
+*/
+/** The global origin-tag key. `Symbol.for` returns the same symbol everywhere. */
+const TOOL_ORIGIN = Symbol.for("dsh.tool.origin");
+/** Convenience: attach an origin tag to a tool definition (before `register`). */
+function setToolOrigin(definition, origin) {
+	definition[TOOL_ORIGIN] = origin;
+	return definition;
+}
+/** Read the origin tag off a tool definition (host-side; never on the model wire). */
+function toolOrigin(definition) {
+	return definition[TOOL_ORIGIN];
+}
+/** Whether an origin's `channel` is one the catalog can honor (plugin/builtin/mcp). */
+function isValidOrigin(origin) {
+	return origin?.channel === "plugin" || origin?.channel === "builtin" || origin?.channel === "mcp";
+}
+//#endregion
+//#region lib/types/namespace.js
+/**
+* The settings namespace owned by the capability-catalog plugin. Plain string
+* so both the host half (settings registration) and the browser half (the
+* settings.plugin.item card key) import it without dragging host-only
+* dependencies into the client bundle.
+*/
+/** Settings namespace owned by the capability-catalog plugin. */
+const CAPABILITY_CATALOG_NS = "capability-catalog";
+const mcpField = z.any().default({});
+/** Section shape: the MCP management state block (permissive) + nothing else. */
+const CapabilityCatalogSettingsSchema = z.object({ ["mcp"]: typeof mcpField.volatile === "function" ? mcpField.volatile() : mcpField });
+//#endregion
+//#region lib/types/modes.js
+/**
+* MODES: reading the catalog through each agent preset.
+*
+* A dsh instance composes every session from an agent preset — 「模式」 in the
+* settings copy, `preset` in the code: the same deployment can run a full
+* coding agent, a minimal single-tool one, or a user-authored preset, and each
+* of those sees a DIFFERENT set of skills and tools. The catalog's default read
+* answers for one of them (the deployment default). "Which of these does this
+* mode actually load, and which modes load it?" is a different question, and
+* this module is the whole answer to it.
+*
+* Two shapes travel:
+*
+* - a mode ROSTER ({@link modeOptions}) — the presets a viewer offers, with the
+*   deployment default marked so a picker can label one 「标准模式（默认）」;
+* - a mode FACE ({@link readModeFaces}) — what one mode's standing scope
+*   actually registers, read through the same `resolvePresetScope` +
+*   `catalogSnapshot` path the default read uses, so a mode view and the
+*   default view cannot drift apart.
+*
+* Reading a mode is NOT free: resolving a preset's standing scope MOUNTS its
+* composition (the roster's single-flight standing mount), so a face read for a
+* mode nothing has composed yet composes it. That is the price of the only
+* honest answer — a composition file says which plugins a mode NAMES, not which
+* tools and skills those plugins register once they run — and it is why the
+* settings surface asks for faces only when a human chooses to compare modes.
+*
+* Both functions are pure over their inputs (the caller supplies the roster rows
+* and the face reader), so their unit tests need no Cordis context.
+* @module @khorsheed/dsh-capability-catalog/modes
+*/
+/**
+* The mode roster a viewer offers: the agent-preset rows, path-free, with the
+* deployment default marked.
+*
+* Roster order is preserved — the roster already orders shipped presets by the
+* `order` they publish — because a picker that re-sorts hands the human a
+* different order every time the roster grows.
+* @param rows - the roster rows (`agentPresets.list()`).
+* @param defaultId - the preset a session naming none composes, when known.
+* @returns the options a mode picker renders, in roster order.
+*/
+function modeOptions(rows, defaultId) {
+	return rows.map((row) => ({
+		id: row.id,
+		...row.name === void 0 ? {} : { name: row.name },
+		...row.description === void 0 ? {} : { description: row.description },
+		...row.broken === void 0 ? {} : { broken: row.broken },
+		...row.id === defaultId ? { isDefault: true } : {}
+	}));
+}
+/**
+* Read one face per mode, in roster order.
+*
+* A BROKEN preset is not read at all: discovery already refused it, and asking
+* the roster to mount it would spend a mount attempt on a composition known to
+* be unusable. It keeps its row with `unavailable` set, so a comparison can say
+* which mode is missing instead of silently showing an empty face — "this mode
+* has no tools" and "this mode could not be read" are different claims, and a
+* viewer that conflates them is worse than one that omits the mode.
+*
+* A reader answering `undefined` means the same thing (its scope did not
+* resolve, so the answer would be the global layer wearing a mode's name).
+* Faces are read SEQUENTIALLY: each read may start a mount, and walking the
+* roster's single-flight mount in order is cheaper than racing it.
+* @param options - the mode roster (from {@link modeOptions}).
+* @param readFace - read one mode's face; undefined when its scope refuses.
+* @returns one face per option, roster order preserved.
+*/
+async function readModeFaces(options, readFace) {
+	const faces = [];
+	for (const option of options) {
+		const identity = {
+			preset: option.id,
+			...option.name === void 0 ? {} : { name: option.name },
+			...option.description === void 0 ? {} : { description: option.description },
+			isDefault: option.isDefault === true
+		};
+		if (option.broken !== void 0) {
+			faces.push({
+				...identity,
+				skills: [],
+				tools: [],
+				unavailable: option.broken
+			});
+			continue;
+		}
+		let face;
+		try {
+			face = await readFace(option.id);
+		} catch {
+			face = void 0;
+		}
+		faces.push(face === void 0 ? {
+			...identity,
+			skills: [],
+			tools: [],
+			unavailable: "the preset resolved no standing scope"
+		} : {
+			...identity,
+			skills: face.skills,
+			tools: face.tools
+		});
+	}
+	return faces;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Capability catalog host service: a Typert Remote over the running skill and
+* tool registries. It projects `ctx.skills.snapshot()` into catalog rows,
+* attributes `ctx.tools.schemas()` to a channel (mcp prefix / official
+* whitelist / baseline-diff), loads per-skill detail on demand, writes
+* declared credentials, and adds skills into the managed root. The browser
+* half binds through the generated `capabilityCatalog` Remote namespace.
+*
+* Zero host edits: everything rides existing official services (`ctx.skills`,
+* `ctx.tools`, `ctx.credentials`) through `ctx.get`, degrading silently when a
+* capability is absent.
+* @module @khorsheed/dsh-capability-catalog
+*/
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) {
+			if (kind === "field") initializers.unshift(_);
+			else descriptor[key] = _;
+		}
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** The remote namespace name (matches the generated remote-client type). */
+const REMOTE_NS = "capabilityCatalog";
+/** Custom inject: subscribe no extra service beyond the two we probe. */
+function resolveServicesHelper(ctx) {
+	return resolveServices(ctx);
+}
+/**
+* Capability catalog Remote service.
+* @module @khorsheed/dsh-capability-catalog
+*/
+let CapabilityCatalogService = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _presetScopeStatus_decorators;
+	let _presetScopeRoster_decorators;
+	let _modeFaces_decorators;
+	let _presetScopeSet_decorators;
+	let _presetScopeAdopt_decorators;
+	let _presetScopeRelease_decorators;
+	let _snapshot_decorators;
+	let _snapshotAt_decorators;
+	let _snapshotFor_decorators;
+	let _detail_decorators;
+	let _readSkillFile_decorators;
+	let _listDirSkills_decorators;
+	let _setCredential_decorators;
+	let _addSkill_decorators;
+	let _deleteSkill_decorators;
+	let _pickDirectory_decorators;
+	let _mcpList_decorators;
+	let _mcpAdd_decorators;
+	let _mcpRemove_decorators;
+	let _mcpSetEnabled_decorators;
+	let _mcpSetCredential_decorators;
+	let _mcpSetToolEnabled_decorators;
+	let _mcpDiscover_decorators;
+	let _mcpSnapshot_decorators;
+	return class CapabilityCatalogService extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_presetScopeStatus_decorators = [Remote("presetScopeStatus")];
+			_presetScopeRoster_decorators = [Remote("presetScopeRoster")];
+			_modeFaces_decorators = [Remote("modeFaces")];
+			_presetScopeSet_decorators = [Remote("presetScopeSet")];
+			_presetScopeAdopt_decorators = [Remote("presetScopeAdopt")];
+			_presetScopeRelease_decorators = [Remote("presetScopeRelease")];
+			_snapshot_decorators = [Remote("snapshot")];
+			_snapshotAt_decorators = [Remote("snapshotAt")];
+			_snapshotFor_decorators = [Remote("snapshotFor")];
+			_detail_decorators = [Remote("detail")];
+			_readSkillFile_decorators = [Remote("readSkillFile")];
+			_listDirSkills_decorators = [Remote("listDirSkills")];
+			_setCredential_decorators = [Remote("setCredential")];
+			_addSkill_decorators = [Remote("addSkill")];
+			_deleteSkill_decorators = [Remote("deleteSkill")];
+			_pickDirectory_decorators = [Remote("pickDirectory")];
+			_mcpList_decorators = [Remote("mcpList")];
+			_mcpAdd_decorators = [Remote("mcpAdd")];
+			_mcpRemove_decorators = [Remote("mcpRemove")];
+			_mcpSetEnabled_decorators = [Remote("mcpSetEnabled")];
+			_mcpSetCredential_decorators = [Remote("mcpSetCredential")];
+			_mcpSetToolEnabled_decorators = [Remote("mcpSetToolEnabled")];
+			_mcpDiscover_decorators = [Remote("mcpDiscover")];
+			_mcpSnapshot_decorators = [Remote("mcpSnapshot")];
+			__esDecorate(this, null, _presetScopeStatus_decorators, {
+				kind: "method",
+				name: "presetScopeStatus",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "presetScopeStatus" in obj,
+					get: (obj) => obj.presetScopeStatus
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _presetScopeRoster_decorators, {
+				kind: "method",
+				name: "presetScopeRoster",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "presetScopeRoster" in obj,
+					get: (obj) => obj.presetScopeRoster
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _modeFaces_decorators, {
+				kind: "method",
+				name: "modeFaces",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "modeFaces" in obj,
+					get: (obj) => obj.modeFaces
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _presetScopeSet_decorators, {
+				kind: "method",
+				name: "presetScopeSet",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "presetScopeSet" in obj,
+					get: (obj) => obj.presetScopeSet
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _presetScopeAdopt_decorators, {
+				kind: "method",
+				name: "presetScopeAdopt",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "presetScopeAdopt" in obj,
+					get: (obj) => obj.presetScopeAdopt
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _presetScopeRelease_decorators, {
+				kind: "method",
+				name: "presetScopeRelease",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "presetScopeRelease" in obj,
+					get: (obj) => obj.presetScopeRelease
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _snapshot_decorators, {
+				kind: "method",
+				name: "snapshot",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "snapshot" in obj,
+					get: (obj) => obj.snapshot
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _snapshotAt_decorators, {
+				kind: "method",
+				name: "snapshotAt",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "snapshotAt" in obj,
+					get: (obj) => obj.snapshotAt
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _snapshotFor_decorators, {
+				kind: "method",
+				name: "snapshotFor",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "snapshotFor" in obj,
+					get: (obj) => obj.snapshotFor
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _detail_decorators, {
+				kind: "method",
+				name: "detail",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "detail" in obj,
+					get: (obj) => obj.detail
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _readSkillFile_decorators, {
+				kind: "method",
+				name: "readSkillFile",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "readSkillFile" in obj,
+					get: (obj) => obj.readSkillFile
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _listDirSkills_decorators, {
+				kind: "method",
+				name: "listDirSkills",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "listDirSkills" in obj,
+					get: (obj) => obj.listDirSkills
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _setCredential_decorators, {
+				kind: "method",
+				name: "setCredential",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "setCredential" in obj,
+					get: (obj) => obj.setCredential
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _addSkill_decorators, {
+				kind: "method",
+				name: "addSkill",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "addSkill" in obj,
+					get: (obj) => obj.addSkill
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _deleteSkill_decorators, {
+				kind: "method",
+				name: "deleteSkill",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "deleteSkill" in obj,
+					get: (obj) => obj.deleteSkill
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _pickDirectory_decorators, {
+				kind: "method",
+				name: "pickDirectory",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "pickDirectory" in obj,
+					get: (obj) => obj.pickDirectory
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpList_decorators, {
+				kind: "method",
+				name: "mcpList",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpList" in obj,
+					get: (obj) => obj.mcpList
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpAdd_decorators, {
+				kind: "method",
+				name: "mcpAdd",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpAdd" in obj,
+					get: (obj) => obj.mcpAdd
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpRemove_decorators, {
+				kind: "method",
+				name: "mcpRemove",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpRemove" in obj,
+					get: (obj) => obj.mcpRemove
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpSetEnabled_decorators, {
+				kind: "method",
+				name: "mcpSetEnabled",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpSetEnabled" in obj,
+					get: (obj) => obj.mcpSetEnabled
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpSetCredential_decorators, {
+				kind: "method",
+				name: "mcpSetCredential",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpSetCredential" in obj,
+					get: (obj) => obj.mcpSetCredential
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpSetToolEnabled_decorators, {
+				kind: "method",
+				name: "mcpSetToolEnabled",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpSetToolEnabled" in obj,
+					get: (obj) => obj.mcpSetToolEnabled
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpDiscover_decorators, {
+				kind: "method",
+				name: "mcpDiscover",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpDiscover" in obj,
+					get: (obj) => obj.mcpDiscover
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _mcpSnapshot_decorators, {
+				kind: "method",
+				name: "mcpSnapshot",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "mcpSnapshot" in obj,
+					get: (obj) => obj.mcpSnapshot
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		config = __runInitializers(this, _instanceExtraInitializers);
+		static inject = [];
+		static Config = CapabilityCatalogSettingsSchema;
+		baseline;
+		appearedAfterApply;
+		mcp;
+		/** The live `ctx.tools` (traceable proxy) captured from the tools inject. */
+		mcpToolsRegistry;
+		/** Registered MCP tool disposers, keyed by model-facing public name. */
+		mcpToolDisposers = /* @__PURE__ */ new Map();
+		/** Preset-scoped delivery of the plugin's own managed skill root. */
+		scoped;
+		/** The workspace the catalog was last asked about, for project-root conflict checks. */
+		observedWorkdir;
+		constructor(ctx, config) {
+			super(ctx, "capabilityCatalog");
+			this.config = config;
+			this.mcp = new McpStore();
+			this.baseline = /* @__PURE__ */ new Set();
+			this.appearedAfterApply = /* @__PURE__ */ new Set();
+			ctx.inject(["settings"], (settingsCtx) => {
+				const svc = settingsCtx.settings;
+				if (typeof svc.register === "function") {
+					const scope = svc.register(CAPABILITY_CATALOG_NS, CapabilityCatalogSettingsSchema);
+					const persisted = scope.get()?.mcp;
+					if (persisted !== void 0) this.mcp.loadFrom(persisted);
+					this.mcp.onPersist = () => {
+						scope.update({ mcp: this.mcp.toPersisted() }).catch((error) => this.ctx.logger.error(error));
+					};
+					scope.watch((next) => {
+						this.mcp.loadFrom(next?.mcp);
+						this.afterMcpMutation();
+					});
+				} else if (typeof svc.update === "function") {
+					svc.configure?.({ auto: false }, ctx.fiber);
+					const readVolatile = () => {
+						const field = this.config.mcp;
+						if (field !== null && typeof field === "object" && typeof field.get === "function") return field.get();
+						return field;
+					};
+					const persisted = readVolatile();
+					if (persisted !== void 0) this.mcp.loadFrom(persisted);
+					this.mcp.onPersist = () => {
+						(typeof svc.replace === "function" ? svc.replace(CAPABILITY_CATALOG_NS, { mcp: this.mcp.toPersisted() }) : svc.update(CAPABILITY_CATALOG_NS, { mcp: this.mcp.toPersisted() })).catch((error) => this.ctx.logger.error(error));
+					};
+					settingsCtx.on("settings/document-updated", (ns) => {
+						if (ns !== "capability-catalog") return;
+						this.mcp.loadFrom(readVolatile());
+						this.afterMcpMutation();
+					});
+				}
+				this.syncRegisteredMcpTools();
+				this.reconnectEnabledMcp();
+			});
+			ctx.inject(["tools"], (toolCtx) => {
+				this.mcpToolsRegistry = toolCtx.tools;
+				this.syncRegisteredMcpTools();
+				this.registerListTool(toolCtx.tools);
+				this.baseline = new Set(toolCtx.tools.schemas().map((t) => t.name) ?? []);
+				this.appearedAfterApply.clear();
+				ctx.on("tools/change", () => this.markNewTools());
+			});
+			ctx.inject([
+				"shellEnv",
+				"credentials",
+				"skills"
+			], () => {
+				installSkillEnvInjection(ctx, () => this.catalogScope());
+			});
+			installSkillEnvHint(ctx, () => this.catalogScope());
+			ctx.inject(["skills"], (skillsCtx) => {
+				const delivery = new ScopedSkillDelivery(skillsCtx, {
+					dshHome: () => this.dshHome(),
+					roster: () => this.agentPresets(),
+					registry: () => this.ctx.get?.("skills"),
+					workdir: () => this.observedWorkdir,
+					log: (message) => this.ctx.logger.warn(message)
+				});
+				this.scoped = delivery;
+				skillsCtx.effect(() => {
+					delivery.start().catch((error) => {
+						this.ctx.logger.warn(`capability-catalog: preset-scoped delivery failed to start: ${error instanceof Error ? error.message : String(error)}`);
+					});
+					return () => {
+						delivery.dispose();
+					};
+				}, "capability-catalog: preset-scoped skills");
+			});
+		}
+		/** The preset-scoped delivery's current state, for the settings surface. */
+		async presetScopeStatus() {
+			const status = this.scoped?.status();
+			return status === void 0 ? {
+				enabled: false,
+				reason: "preset-scoped delivery is not composed",
+				root: scopedSkillsRoot(this.dshHome()),
+				watching: false,
+				skills: [],
+				presets: [],
+				customRootsUnverifiable: true
+			} : status;
+		}
+		/** Every preset the roster supplies, for the scope picker. */
+		async presetScopeRoster() {
+			return modeOptions(await this.rosterRows(), this.agentPresets()?.defaultId);
+		}
+		/**
+		* Every mode's capability face in ONE call, for the cross-mode comparison
+		* view ("which modes load this tool/skill?").
+		*
+		* This is the expensive verb of the pair: a mode whose standing scope has not
+		* been composed yet is MOUNTED by its read (see modes.ts — there is no cheap
+		* honest source, because a composition file names plugins, not the tools and
+		* skills those plugins register). The browser therefore calls it only when a
+		* human chooses to compare modes, never on opening the section.
+		*
+		* A mode that cannot be read keeps its row with `unavailable` set rather than
+		* an empty face, so the comparison never claims that a broken mode loads
+		* nothing. `preset` on a face is always the id that was asked for: a read
+		* that silently degraded to the global layer is reported as unavailable, not
+		* as that mode's face.
+		* @param workdir - optional cwd for project-scoped skill roots.
+		*/
+		async modeFaces(workdir) {
+			return readModeFaces(modeOptions(await this.rosterRows(), this.agentPresets()?.defaultId), async (id) => {
+				try {
+					const face = await this.collect(id, workdir, false);
+					if (face.preset !== id) {
+						this.ctx.logger.warn(`capability-catalog: preset "${id}" resolved no standing scope — its mode face reads as unavailable`);
+						return;
+					}
+					return face;
+				} catch (error) {
+					this.ctx.logger.warn(`capability-catalog: mode face read for preset "${id}" failed: ${error instanceof Error ? error.message : String(error)}`);
+					return;
+				}
+			});
+		}
+		/** The roster rows, or [] when this composition mounts no agent-preset service. */
+		async rosterRows() {
+			const roster = this.agentPresets();
+			if (roster?.list === void 0) return [];
+			try {
+				return await roster.list();
+			} catch (error) {
+				this.ctx.logger.warn(`capability-catalog: the preset roster could not be listed: ${error instanceof Error ? error.message : String(error)}`);
+				return [];
+			}
+		}
+		/** Declare which presets one managed skill is delivered to. */
+		async presetScopeSet(request) {
+			const result = await setManagedPresetScope(this.dshHome(), request.name, request.presets);
+			await this.reconcileScoped();
+			return result;
+		}
+		/** Move an installed skill into the managed root with a preset scope. */
+		async presetScopeAdopt(request) {
+			const result = await adoptManagedSkill(this.dshHome(), request.name, request.presets, request.workdir ?? this.observedWorkdir);
+			await this.reconcileScoped();
+			return result;
+		}
+		/** Move a managed skill back to the user skill root (the recovery direction). */
+		async presetScopeRelease(name) {
+			const result = await releaseManagedSkill(this.dshHome(), name);
+			await this.reconcileScoped();
+			return result;
+		}
+		/** Re-deliver after a write; a delivery that is absent is not an error. */
+		async reconcileScoped() {
+			try {
+				await this.scoped?.reconcile();
+			} catch (error) {
+				this.ctx.logger.warn(`capability-catalog: scoped skill reconcile failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		/** Record tools that appeared after the apply-time baseline (reads the live
+		* registry each time, so a change event never sees a stale/undefined ref). */
+		markNewTools() {
+			const tools = this.ctx.get?.("tools");
+			const current = new Set(tools?.schemas().map((t) => t.name) ?? []);
+			for (const name of current) if (!this.baseline.has(name)) this.appearedAfterApply.add(name);
+		}
+		/** The managed skills root under `$DSH_HOME`. */
+		dshHome() {
+			return (this.ctx.get?.("settings"))?.home ?? process.env.DSH_HOME ?? join(homedir(), ".dsh-official");
+		}
+		/**
+		* The standing skill view scope of ONE preset. In the web bundle the
+		* host-global skill-filesystem provider is mounted under each agent
+		* preset's standing scope, so a host-global snapshot sees only runtime
+		* skills; reading at the preset's scope surfaces the official/plugin/user
+		* skills the model actually sees. When the presets service is absent the
+		* catalog degrades to the global layer alone.
+		*
+		* `presetId` names WHICH preset — the deployment default when omitted, the
+		* way every reader before `snapshotFor` behaved. The roster's scope face
+		* (0.1.5's `standingKeyFor`, rc.1's leased `acquireScope`) has always taken
+		* an id; the catalog simply never passed one, so "the capability face of
+		* preset X" was unaskable and a condition declaring `preset: X` could only
+		* be believed.
+		*
+		* `strict` is the listing/fingerprint split — see
+		* {@link resolvePresetScope}, which owns the policy.
+		* @param presetId - the preset to read, or undefined for the default.
+		* @param strict - throw instead of degrading when the roster cannot answer.
+		*/
+		async catalogScope(presetId, strict = false) {
+			const { scope, dispose } = await resolvePresetScope(this.agentPresets(), presetId, strict);
+			await this.releaseScope(dispose);
+			return scope;
+		}
+		/** Release a scope lease, logging rather than failing the read it followed. */
+		async releaseScope(dispose) {
+			if (dispose === void 0) return;
+			try {
+				await dispose();
+			} catch (error) {
+				this.ctx.logger.warn(`capability-catalog: scope lease release failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		/** The optional agent-preset roster (absent in a rosterless composition). */
+		agentPresets() {
+			return this.ctx.get?.("agentPresets");
+		}
+		/** Register the model-facing `list_capabilities` tool (optional; called from the
+		* tools inject so the registry is guaranteed present). */
+		registerListTool(tools) {
+			if (tools.register === void 0) return;
+			tools.register(defineTool({
+				name: "list_capabilities",
+				description: "List the capabilities (skills and tools) registered in this instance and their source channels. Call to discover what is available.",
+				parameters: { kind: {
+					type: "string",
+					enum: ["skill", "tool"],
+					description: "Optional: filter to skills or tools."
+				} },
+				output: {
+					schema: { type: "string" },
+					render: (_args, value) => [{
+						type: "text",
+						text: String(value)
+					}]
+				},
+				execute: async (args, exec) => {
+					const { registry } = resolveServicesHelper(this.ctx);
+					if (registry === void 0) return "skills service absent in this composition";
+					const scope = exec?.agent ?? await this.catalogScope();
+					const snapshot = await catalogSnapshot(void 0, registry, this.toolSchemasIn(scope), this.mcpServerNamesIn(scope), this.appearedAfterApply, [scope], this.toolOriginsMap(scope), { fingerprint: true });
+					const filter = args?.kind;
+					const skills = filter === void 0 || filter === "skill" ? snapshot.skills : [];
+					const toolsRows = filter === void 0 || filter === "tool" ? snapshot.tools : [];
+					return JSON.stringify({
+						capabilities: capsTag(snapshot.sha),
+						skills,
+						tools: toolsRows
+					}, null, 2);
+				}
+			}));
+		}
+		async snapshot(workdir) {
+			return this.collect(void 0, workdir, false);
+		}
+		/**
+		* The capability face of ONE mode as a LISTING — {@link snapshot} scoped to a
+		* named preset, for the settings surface's mode picker.
+		*
+		* The LISTING/FINGERPRINT split matters here the way it does everywhere else:
+		* a viewer wants rows as fast as the registries can produce them, not every
+		* skill body loaded and digested. Asking for a preset's IDENTITY is
+		* {@link snapshotFor}. Like every scope resolution, this MOUNTS a preset
+		* nothing has composed yet.
+		*
+		* Degrades like {@link snapshot}: a preset whose standing scope refuses
+		* answers with the global layer and NO `preset` stamp, which is how a caller
+		* tells "this mode" from "the fallback" and says so.
+		* @param presetId - the mode to read, or undefined for the deployment default.
+		* @param workdir - optional cwd for project-scoped skill roots.
+		*/
+		async snapshotAt(presetId, workdir) {
+			return this.collect(presetId, workdir, false);
+		}
+		/**
+		* The capability face of ONE preset, with its {@link hashOf} digest.
+		*
+		* This is the fingerprint verb: every skill body is loaded (so the rows
+		* carry `bodySha`) and `sha` is stamped, which is what makes the answer an
+		* identity rather than a listing. `presetId` omitted reads the deployment
+		* default — the same face `snapshot` reads, now hashable.
+		*
+		* Degrades like every other verb: without a skills registry the answer is
+		* an empty face with the hash of an empty face, not a throw. Note that a
+		* preset nobody has composed yet is MOUNTED by the read (the roster's
+		* single-flight standing mount), so asking is not free.
+		* @param presetId - the preset to fingerprint, or undefined for the default.
+		* @param workdir - optional cwd for project-scoped skill roots.
+		*/
+		async snapshotFor(presetId, workdir) {
+			return this.collect(presetId, workdir, true);
+		}
+		/**
+		* Shared body of {@link snapshot} and {@link snapshotFor}. The scope is
+		* resolved ONCE — three resolutions of a mounting preset would race the
+		* roster's single-flight for no reason — and `fingerprint` makes the
+		* resolution strict.
+		*/
+		async collect(presetId, workdir, fingerprint) {
+			const { registry } = resolveServicesHelper(this.ctx);
+			if (workdir !== void 0 && workdir !== "") this.observedWorkdir = workdir;
+			const { scope, preset, dispose } = await resolvePresetScope(this.agentPresets(), presetId, fingerprint);
+			try {
+				if (registry === void 0) {
+					const empty = {
+						skills: [],
+						tools: [],
+						mcpServers: [],
+						channels: [],
+						...preset !== void 0 ? { preset } : {}
+					};
+					return fingerprint ? {
+						...empty,
+						sha: hashOf(empty)
+					} : empty;
+				}
+				return await catalogSnapshot(workdir, registry, this.toolSchemasIn(scope), this.mcpServerNamesIn(scope), this.appearedAfterApply, [scope], this.toolOriginsMap(scope), {
+					fingerprint,
+					...preset !== void 0 ? { preset } : {}
+				});
+			} finally {
+				await this.releaseScope(dispose);
+			}
+		}
+		async detail(name, workdir, presetId) {
+			const { registry } = resolveServicesHelper(this.ctx);
+			if (registry === void 0) return void 0;
+			return catalogDetail(this.ctx, registry, name, workdir, await this.catalogScope(presetId), await this.managedDefinition(name));
+		}
+		async readSkillFile(name, filePath, workdir, presetId) {
+			const { registry } = resolveServicesHelper(this.ctx);
+			if (registry === void 0) return void 0;
+			return catalogReadSkillFile(registry, name, filePath, workdir, await this.catalogScope(presetId), await this.managedDefinition(name));
+		}
+		/** One managed skill's definition, for management reads outside its scope. */
+		async managedDefinition(name) {
+			const skill = (await scanManagedSkills(scopedSkillsRoot(this.dshHome()))).find((entry) => entry.name === name);
+			return skill === void 0 ? void 0 : definitionFor(skill);
+		}
+		async listDirSkills(dirPath) {
+			return catalogListDirSkills(dirPath);
+		}
+		async setCredential(request) {
+			return catalogSetCredential(this.ctx, request);
+		}
+		async addSkill(request) {
+			return catalogAddSkill(this.ctx, request, this.dshHome());
+		}
+		async deleteSkill(name, workdir, presetId) {
+			const { registry } = resolveServicesHelper(this.ctx);
+			if (registry === void 0) return {
+				ok: false,
+				error: "skills service absent in this composition"
+			};
+			return catalogDeleteSkill(registry, name, workdir, await this.catalogScope(presetId));
+		}
+		async pickDirectory() {
+			return catalogPickDirectory(this.ctx);
+		}
+		async mcpList() {
+			return this.mcp.list().map(maskConfig);
+		}
+		async mcpAdd(config) {
+			if (config.serverName.trim() === "") return false;
+			this.mcp.add(config);
+			this.afterMcpMutation();
+			return true;
+		}
+		async mcpRemove(serverName) {
+			this.mcp.remove(serverName);
+			this.afterMcpMutation();
+			return true;
+		}
+		async mcpSetEnabled(serverName, enabled) {
+			this.mcp.setEnabled(serverName, enabled);
+			this.afterMcpMutation();
+		}
+		async mcpSetCredential(ref, value) {
+			this.mcp.setCredential(ref, value);
+			return true;
+		}
+		async mcpSetToolEnabled(serverName, tool, enabled) {
+			this.mcp.setToolEnabled(serverName, tool, enabled);
+			this.afterMcpMutation();
+		}
+		async mcpDiscover(serverName) {
+			const tools = await this.mcp.discover(serverName);
+			this.afterMcpMutation();
+			return tools;
+		}
+		async mcpSnapshot() {
+			return {
+				servers: this.mcp.list().map(maskConfig),
+				tools: this.mcp.toolsByServer(),
+				credentials: this.mcp.credentials()
+			};
+		}
+		/** The visible tool schemas in the standing scope (the set the model sees),
+		* or the global layer when no preset standing key resolves. Skills already
+		* enumerate through the same scope; tools must use it too so the
+		* settings reader sees the official/plugin/MCP tools the model actually has. */
+		toolSchemasIn(scope) {
+			const tools = this.ctx.get?.("tools");
+			if (tools?.schemas === void 0) return [];
+			return scope === void 0 ? tools.schemas() : tools.schemas(scope);
+		}
+		/** tool name → author-declared origin, read via `ctx.tools.get(name)` so the
+		* `Symbol.for('dsh.tool.origin')` tag on the retained definition survives (the
+		* system-prompt assembly strips it, but `get()` returns the full definition). */
+		toolOriginsMap(scope) {
+			const tools = this.ctx.get?.("tools");
+			if (tools?.get === void 0) return /* @__PURE__ */ new Map();
+			const schemas = scope === void 0 ? tools.schemas() : tools.schemas(scope);
+			const out = /* @__PURE__ */ new Map();
+			for (const schema of schemas) {
+				const def = scope === void 0 ? tools.get(schema.name) : tools.get(schema.name, scope);
+				if (def === void 0) {
+					this.ctx.logger.warn(`capability-catalog: tool "${schema.name}" is visible but ctx.tools.get() is undefined in this scope — its origin tag cannot be read; it will be classified by heuristics`);
+					continue;
+				}
+				const origin = toolOrigin(def);
+				if (origin !== void 0) {
+					if (!isValidOrigin(origin)) {
+						this.ctx.logger.warn(`capability-catalog: tool "${schema.name}" origin channel "${String(origin.channel)}" is not a known channel (plugin/builtin/mcp) — ignoring the tag, falling back to heuristics`);
+						continue;
+					}
+					out.set(schema.name, origin);
+				}
+			}
+			return out;
+		}
+		/** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
+		mcpServerNamesIn(scope) {
+			const names = [];
+			for (const schema of this.toolSchemasIn(scope)) {
+				if (!schema.name.startsWith("mcp__")) continue;
+				const rest = schema.name.slice(5);
+				const sep = rest.indexOf("__");
+				const server = sep > 0 ? rest.slice(0, sep) : rest;
+				if (server.length > 0 && !names.includes(server)) names.push(server);
+			}
+			return names;
+		}
+		/**
+		* Reconcile which discovered MCP tools are registered on `ctx.tools` so the
+		* model can call them. `mcpToolsRegistry` is the traceable `ctx.tools` proxy,
+		* so `register` is always invoked as a MEMBER call (`reconcile` calls
+		* `registry.register(...)`) — extracting it to a standalone variable loses the
+		* `this.ctx` binding and breaks the disposal effect.
+		*/
+		syncRegisteredMcpTools() {
+			const registry = this.mcpToolsRegistry;
+			if (registry === void 0) return;
+			reconcileRegisteredMcpTools(desiredMcpTools(this.mcp.list(), this.mcp.toolsByServer()), {
+				register: (definition) => registry.register(definition),
+				onRegisterError: (error) => this.ctx.logger.error(`capability-catalog: MCP tool registration failed: ${String(error)}`)
+			}, this.mcpToolDisposers, (serverName, rawName, args) => this.mcp.callTool(serverName, rawName, args));
+		}
+		/** Re-sync registered MCP tools after any MCP store mutation. */
+		afterMcpMutation() {
+			this.syncRegisteredMcpTools();
+		}
+		/** Refill the persisted MCP tools' descriptions/parameters by re-connecting the
+		* enabled servers at boot (the persisted `mcp` block stores only name+enabled to
+		* keep settings.yaml small). Async: boot is not blocked; each server's errors are
+		* contained, and registration is re-synced once the descriptions are back. */
+		async reconnectEnabledMcp() {
+			const enabled = this.mcp.list().filter((s) => s.enabled);
+			if (enabled.length === 0) return;
+			for (const server of enabled) try {
+				await this.mcp.discover(server.serverName);
+			} catch (error) {
+				this.ctx.logger.error(`capability-catalog: reconnect ${server.serverName} failed: ${String(error)}`);
+			}
+			this.syncRegisteredMcpTools();
+		}
+	};
+})();
+//#endregion
+export { CAPS_TAG_PREFIX, CapabilityCatalogService, CapabilityCatalogService as default, MANAGED_SKILL_RANK, REMOTE_NS, SCOPED_PROVIDER_NAME, ScopedSkillDelivery, TOOL_ORIGIN, adoptManagedSkill, canonicalCapabilities, canonicalJson, capsTag, defaultSkillRoots, detectConflicts, findSkillSource, hashOf, hashSkillBody, isDirectory, managedLocation, managedSkillFrom, modeOptions, parsePresetScopeFrontmatter, readModeFaces, releaseManagedSkill, resolvePresetScope, resolveSkillNameFromContent, scanManagedSkills, scopedSkillsRoot, setManagedPresetScope, setToolOrigin, toolOrigin, withPresetScope };