@khorsheed/dsh-capability-catalog 0.1.98 → 0.1.99

package/lib/types/scoped-delivery.js

@@ -29,7 +29,11 @@ import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { createScope } from '@deepseek-ai/dsh-scope';
+import { defineTool } from '@deepseek-ai/dsh-tools';
 import { acquireStandingScope } from './preset-scope.js';
+import { collectSkillFiles, resolveBundleTarget, sanitizeBundlePath } from './skills.js';
+import { isKebabId, parseSkillFrontmatter } from './frontmatter.js';
+import { setToolOrigin } from './tool-origin.js';
 let presetRegistryProbe;
 /**
  * Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
@@ -62,118 +66,39 @@ export const MANAGED_SKILL_RANK = 300;
 export 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. */
 export 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.
- */
-export 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('[')) {
-            const inner = rest.slice(1, rest.lastIndexOf(']') === -1 ? undefined : rest.lastIndexOf(']'));
-            return presetIdsOf(inner.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);
-    }
-    return undefined;
-}
-/** 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. */
-export function isKebabId(value) {
-    return KEBAB_ID.test(value);
-}
-/** Split a SKILL.md into its frontmatter block and body. */
-export function splitFrontmatter(content) {
-    const match = FRONTMATTER.exec(content);
-    if (match === null)
-        return undefined;
-    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 undefined;
-    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 undefined;
-    const value = (match[1] ?? '').trim().replace(/^['"]|['"]$/g, '');
-    return value === '' ? undefined : value;
-}
 /**
  * Parse one managed `SKILL.md` into its delivery record.
+ *
+ * The frontmatter is ONE real-YAML parse (see `./frontmatter.ts`): name and
+ * description read top-level only, the invocation flags accept the host
+ * loader's boolean variants, and the scope list comes from the canonical
+ * `metadata.presetScope` (falling back to a legacy top-level key). A malformed
+ * `metadata:` block degrades to no-metadata — the skill still delivers —
+ * rather than rejecting a file the rest of the block could still serve.
  * @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.
  */
 export function managedSkillFrom(content, dir, path) {
-    const split = splitFrontmatter(content);
-    if (split === undefined)
+    const parsed = parseSkillFrontmatter(content);
+    if (parsed === undefined)
         return undefined;
-    const name = frontmatterScalar(split.front, 'name');
-    const description = frontmatterScalar(split.front, 'description');
-    if (name === undefined || description === undefined || !KEBAB_ID.test(name))
+    const { name, description } = parsed;
+    if (name === undefined || description === undefined || !isKebabId(name))
         return undefined;
-    const whenToUse = frontmatterScalar(split.front, 'when-to-use') ?? frontmatterScalar(split.front, 'whenToUse');
-    const presetScope = parsePresetScopeFrontmatter(split.front);
     return {
         name,
         description,
-        ...whenToUse === undefined ? {} : { whenToUse },
-        modelInvocable: frontmatterFlag(split.front, 'disable-model-invocation') !== true,
-        userInvocable: frontmatterFlag(split.front, 'user-invocable') !== false,
-        presetScope,
+        ...parsed.whenToUse === undefined ? {} : { whenToUse: parsed.whenToUse },
+        modelInvocable: parsed.modelInvocable,
+        userInvocable: parsed.userInvocable,
+        presetScope: parsed.presetScope,
+        ...parsed.metadata === undefined ? {} : { metadata: parsed.metadata },
         dir,
         path,
         content,
@@ -195,7 +120,10 @@ export function candidateFor(skill) {
         rank: MANAGED_SKILL_RANK,
         locator: skill.path,
         path: skill.path,
-        metadata: { presetScope: [...(skill.presetScope ?? [])] },
+        // The declared scope is overlaid onto the skill's own metadata block (never
+        // a rebuild): credentials declarations and other plugin data must survive
+        // delivery unchanged, or the detail surface loses them on adoption.
+        metadata: { ...skill.metadata, presetScope: [...(skill.presetScope ?? [])] },
         resourceBase: { kind: 'directory', path: skill.dir },
     };
 }
@@ -253,7 +181,7 @@ export async function scanManagedSkills(root) {
     }
     const found = [];
     for (const child of children) {
-        if (!child.isDirectory() || !KEBAB_ID.test(child.name))
+        if (!child.isDirectory() || !isKebabId(child.name))
             continue;
         const dir = join(root, child.name);
         const path = join(dir, 'SKILL.md');
@@ -297,6 +225,9 @@ export class ScopedSkillDelivery {
     failure;
     started = false;
     disposed = false;
+    /** Reconcile gate: one pass in flight, one queued rerun (see reconcile). */
+    reconcileInFlight;
+    reconcileQueued = false;
     /** The probed registry's mount list (undefined until start()'s probe resolves). */
     presetMounts;
     /**
@@ -322,8 +253,49 @@ export class ScopedSkillDelivery {
         this.ctx.on('agent-preset/selected', () => { void this.reconcile(); });
         await this.reconcile();
     }
-    /** Re-read policy and files, then converge the delivery registrations. */
+    /**
+     * Re-read policy and files, then converge the delivery registrations.
+     *
+     * Triggers arrive concurrently — the filesystem watcher, the
+     * `agent-preset/selected` event, and the management Remotes — and two
+     * overlapping passes can both decide a preset has no registration and each
+     * register one, leaving two same-named providers serving one preset. The
+     * gate allows ONE pass in flight and coalesces every trigger that arrives
+     * during it into ONE queued rerun (the pass re-reads policy and files from
+     * scratch, so a rerun loses no update). A caller that finds a pass in
+     * flight waits for the chain its flag provoked, so an awaited reconcile
+     * still reflects the write that triggered it.
+     */
     async reconcile() {
+        if (this.disposed)
+            return;
+        if (this.reconcileInFlight !== undefined) {
+            this.reconcileQueued = true;
+            let run = this.reconcileInFlight;
+            while (run !== undefined) {
+                await run;
+                if (this.disposed)
+                    return;
+                run = this.reconcileInFlight;
+            }
+            return;
+        }
+        const run = (async () => {
+            try {
+                do {
+                    this.reconcileQueued = false;
+                    await this.reconcileNow();
+                } while (this.reconcileQueued && !this.disposed);
+            }
+            finally {
+                this.reconcileInFlight = undefined;
+            }
+        })();
+        this.reconcileInFlight = run;
+        return run;
+    }
+    /** One reconcile pass (call only through {@link reconcile}'s gate). */
+    async reconcileNow() {
         if (this.disposed)
             return;
         const registry = this.deps.registry();
@@ -565,6 +537,13 @@ export class ScopedSkillDelivery {
                 invalidate = control.invalidate;
                 return this.providerFor(presetId, control);
             });
+            // The bundle-file reader rides the same scope layer: a preset that mounts
+            // no fs tools (learning mode) still lets the model read a delivered
+            // skill's reference files. Best-effort — a composition without the tools
+            // service keeps the delivery and drops only the reader.
+            const withTools = await injectableScope(injected, TOOLS_SERVICE);
+            const tools = withTools?.get(TOOLS_SERVICE);
+            tools?.register?.(this.bundleFileTool(presetId));
             this.entries.push({
                 presetId,
                 key,
@@ -622,6 +601,56 @@ export class ScopedSkillDelivery {
                 ? !isScoped(skill)
                 : (skill.presetScope ?? []).includes(presetId)));
     }
+    /** The managed skills readable through one preset's reader: its own scoped
+     * delivery plus the unscoped ones every preset sees through the global layer. */
+    readableFor(presetId) {
+        return [...this.skillsFor(presetId), ...this.skillsFor(GLOBAL_PRESET)];
+    }
+    /** The read-only bundle-file reader served with one preset's delivery. */
+    bundleFileTool(presetId) {
+        return setToolOrigin(defineTool({
+            name: READ_SKILL_FILE_TOOL,
+            description: 'Read a file from the bundle of a skill delivered to this mode — the reference documents and scripts beside its SKILL.md (a SKILL.md may point at them, e.g. "see search.md"). Omit path to list the bundle files.',
+            parameters: {
+                name: { type: 'string', required: true, description: 'The exact skill name from the available skills list.' },
+                path: { type: 'string', description: 'The bundle-relative file path (e.g. search.md). Omit it to list the bundle files.' },
+            },
+            output: {
+                schema: { type: 'string' },
+                render: (_args, value) => [{ type: 'text', text: String(value) }],
+            },
+            execute: async (args) => this.readBundleFile(presetId, args.name, args.path),
+        }), { channel: 'plugin', owner: '@khorsheed/dsh-capability-catalog' });
+    }
+    /** Serve one bundle file (or the bundle's file list) to a delivered skill's caller. */
+    async readBundleFile(presetId, name, filePath) {
+        const skill = this.readableFor(presetId).find(entry => entry.name === name);
+        if (skill === undefined)
+            return `skill "${name}" is not delivered to this mode by the capability catalog`;
+        if (filePath === undefined || filePath.trim() === '') {
+            const files = [];
+            await collectSkillFiles(skill.dir, skill.dir, files, 0);
+            return files.length === 0 ? `skill "${name}" has no bundle files` : files.sort().join('\n');
+        }
+        const safe = sanitizeBundlePath(filePath);
+        if (safe === undefined)
+            return `refused: "${filePath}" is not a bundle-relative path`;
+        // Containment including symlinks — the bundle directory is user content.
+        const target = await resolveBundleTarget(skill.dir, safe);
+        if (target === undefined)
+            return `no such bundle file: ${safe}`;
+        let content;
+        try {
+            content = await readFile(target, 'utf8');
+        }
+        catch {
+            return `no such bundle file: ${safe}`;
+        }
+        if (content.length > MAX_BUNDLE_FILE_CHARS) {
+            return `${content.slice(0, MAX_BUNDLE_FILE_CHARS)}\n…(truncated at ${MAX_BUNDLE_FILE_CHARS} characters)`;
+        }
+        return content;
+    }
     /** Invalidate every registration's completed catalogs. */
     invalidateAll() {
         for (const entry of this.entries)
@@ -658,6 +687,12 @@ function describeError(error) {
 }
 /** The registry every delivery registration is made through. */
 const SKILLS_SERVICE = 'skills';
+/** The tools registry the bundle-file reader registers through (optional). */
+const TOOLS_SERVICE = 'tools';
+/** The scoped bundle-file reader's tool name. */
+export const READ_SKILL_FILE_TOOL = 'read_skill_file';
+/** A bundle file's served text is capped so a giant asset cannot flood a turn. */
+const MAX_BUNDLE_FILE_CHARS = 100_000;
 /** How long an injection may take before the registration is abandoned. */
 const INJECT_TIMEOUT_MS = 500;
 /**
@@ -668,9 +703,10 @@ const INJECT_TIMEOUT_MS = 500;
  * 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.
+ * @param service - the service the injected context must reach.
  * @returns the injected context, or undefined when it never became available.
  */
-function injectableScope(scopeCtx) {
+function injectableScope(scopeCtx, service = SKILLS_SERVICE) {
     return new Promise(resolve => {
         let settled = false;
         const finish = (value) => {
@@ -681,6 +717,6 @@ function injectableScope(scopeCtx) {
             resolve(value);
         };
         const timer = setTimeout(() => finish(undefined), INJECT_TIMEOUT_MS);
-        scopeCtx.inject([SKILLS_SERVICE], (injected) => finish(injected));
+        scopeCtx.inject([service], (injected) => finish(injected));
     });
 }

package/lib/types/scoped-edits.js

@@ -14,7 +14,8 @@
 import { cp, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { defaultSkillRoots, isKebabId, scanManagedSkills, scopedSkillsRoot, splitFrontmatter, } from './scoped-delivery.js';
+import { defaultSkillRoots, scanManagedSkills, scopedSkillsRoot, } from './scoped-delivery.js';
+import { isKebabId, splitFrontmatter } from './frontmatter.js';
 /** Shared guard: every write path addresses one skill directory by name. */
 function invalidName(name) {
     return isKebabId(name) ? undefined : { ok: false, error: `"${name}" is not a valid skill name` };

package/lib/types/shellEnv.d.ts

@@ -10,6 +10,13 @@
  * model's context; it only becomes visible if the model (or a command) actively
  * prints it — a default-hide, not a hard secret boundary.
  *
+ * Coverage: the registry snapshot is read at the catalog's preset scope, which
+ * a preset-scoped managed skill never appears in — so the managed root is ALSO
+ * scanned directly (its skills' declared keys join the same set). The injected
+ * variables are instance-wide per execution: preset scope is a delivery policy,
+ * not a secret boundary, and a value leaves the shell env only if a command
+ * prints it.
+ *
  * 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.
@@ -60,6 +67,6 @@ export interface ShellEnvRegistryLike {
  * 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.
  */
-export declare function installSkillEnvInjection(ctx: Context, getScope: () => Promise<unknown | undefined>): () => void;
+export declare function installSkillEnvInjection(ctx: Context, getScope: () => Promise<unknown | undefined>, getDshHome: () => string): () => void;
 export { DSH_PREFIX };
 //# sourceMappingURL=shellEnv.d.ts.map

package/lib/types/shellEnv.js

@@ -10,6 +10,13 @@
  * model's context; it only becomes visible if the model (or a command) actively
  * prints it — a default-hide, not a hard secret boundary.
  *
+ * Coverage: the registry snapshot is read at the catalog's preset scope, which
+ * a preset-scoped managed skill never appears in — so the managed root is ALSO
+ * scanned directly (its skills' declared keys join the same set). The injected
+ * variables are instance-wide per execution: preset scope is a delivery policy,
+ * not a secret boundary, and a value leaves the shell env only if a command
+ * prints it.
+ *
  * 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.
@@ -31,6 +38,7 @@
  * @module @khorsheed/dsh-capability-catalog/shellEnv
  */
 import { decodeCredentialDecls, decodeEnvDecls, mergeCredentialDecls } from './skills.js';
+import { definitionFor, scanManagedSkills, scopedSkillsRoot } from './scoped-delivery.js';
 const DSH_PREFIX = 'DSH_';
 const ENV_KEY_SUFFIX = /^[A-Z][A-Z0-9_]*$/;
 /** Reserved `DSH_*` names the host's shell-env registry owns as built-in facts
@@ -57,7 +65,7 @@ const RESERVED_ENV_KEYS = new Set(['DSH_HOME', 'DSH_SHELL', 'DSH_SESSION_ID']);
  * 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.
  */
-export function installSkillEnvInjection(ctx, getScope) {
+export function installSkillEnvInjection(ctx, getScope, getDshHome) {
     let disposed = false;
     let envCache = new Map();
     let disposeEnv;
@@ -126,21 +134,8 @@ export function installSkillEnvInjection(ctx, getScope) {
                 const occupied = new Set((shellEnv.list?.() ?? []).filter(e => e.contributor !== 'capability-catalog').map(e => e.key));
                 const keys = new Set();
                 const values = new Map();
-                for (const row of snapshot.skills) {
-                    // Only skills the model may invoke get their credentials injected —
-                    // a model-disabled (user-only) skill cannot be used by the model, so
-                    // putting its secret in the model shell would be pure exposure.
-                    if (row.invocation?.modelInvocable === false)
-                        continue;
-                    let def;
-                    try {
-                        def = await skills.get(row.name, snapshotOptions);
-                    }
-                    catch {
-                        continue;
-                    }
-                    if (def === undefined)
-                        continue;
+                /** Fold one definition's declared env keys into the contributor's set. */
+                const collectDecls = async (def) => {
                     const decls = mergeCredentialDecls(decodeCredentialDecls(def.metadata), decodeEnvDecls(def.content ?? ''));
                     for (const decl of decls) {
                         if (!ENV_KEY_SUFFIX.test(decl.key))
@@ -157,6 +152,32 @@ export function installSkillEnvInjection(ctx, getScope) {
                         if (resolved !== undefined && resolved.value.length > 0)
                             values.set(dshKey, resolved.value);
                     }
+                };
+                for (const row of snapshot.skills) {
+                    // Only skills the model may invoke get their credentials injected —
+                    // a model-disabled (user-only) skill cannot be used by the model, so
+                    // putting its secret in the model shell would be pure exposure.
+                    if (row.invocation?.modelInvocable === false)
+                        continue;
+                    let def;
+                    try {
+                        def = await skills.get(row.name, snapshotOptions);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (def === undefined)
+                        continue;
+                    await collectDecls(def);
+                }
+                // The registry read is scoped to the catalog's preset view: a skill
+                // scoped AWAY from that preset never appears in the snapshot, and its
+                // declared credentials would never be injected. Scan the managed root
+                // directly so a preset-scoped skill's keys are covered too.
+                for (const skill of await scanManagedSkills(scopedSkillsRoot(getDshHome())).catch(() => [])) {
+                    if (!skill.modelInvocable)
+                        continue;
+                    await collectDecls(definitionFor(skill));
                 }
                 if (disposed || gen !== refreshGen)
                     return; // stale or disposed — drop the commit

package/lib/types/skills.d.ts

@@ -79,15 +79,56 @@ export declare function resolveServices(ctx: Context): {
     registry: RegistrySlice | undefined;
     credentials: CredentialsSlice | undefined;
 };
+/**
+ * The health of one skills collection pass — the facts a completeness
+ * descriptor is built from. Counts only, never error text (which may carry
+ * paths). Filled by {@link collectSkills} when the caller passes a bag.
+ */
+export interface SkillsCollectionReport {
+    /** Scope reads attempted. */
+    attemptedScopes: number;
+    /** Scope reads whose `registry.snapshot()` threw (source class: registry read). */
+    failedScopes: number;
+    /** Reads the registry itself flagged as incomplete discovery (`complete: false`). */
+    incompleteReads: number;
+    /** Skills whose body could not be loaded while fingerprinting. */
+    unreadableBodies: number;
+}
 /**
  * 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.
+ *
+ * `report`, when given, is filled with the collection's health (see
+ * {@link SkillsCollectionReport}); the Remote verbs never pass one, so their
+ * rows — and their digests — are exactly what they were.
  */
 export declare function collectSkills(registry: RegistrySlice, workdir: string | undefined, scopes?: readonly unknown[], collectOptions?: {
     bodySha?: boolean;
+    report?: SkillsCollectionReport;
 }): Promise<CapabilityCatalogSnapshot>;
+/** Recursively collect a directory's file paths relative to `root`. */
+export declare function collectSkillFiles(dir: string, root: string, out: string[], depth: number): Promise<void>;
+/** Reject unsafe bundle-relative paths (absolute, drive-letter, or `..`). */
+export declare function sanitizeBundlePath(path: string): string | undefined;
+/**
+ * Resolve an already-sanitized bundle-relative path to its real on-disk
+ * target, refusing anything that escapes the bundle. {@link sanitizeBundlePath}
+ * has already removed the lexical escapes (absolute forms, drive letters,
+ * `..`); this closes what a lexical check cannot:
+ *
+ * - a symlink INSIDE the bundle whose target lives outside it (the bundle
+ *   directory is user content), and
+ * - a prefix collision — containment is a separator-terminated comparison on
+ *   realpaths, so `/root/foobar` never contain-matches `/root/foo`.
+ *
+ * @param bundleDir - the skill's bundle directory (its resource base).
+ * @param safe - a path that already passed {@link sanitizeBundlePath}.
+ * @returns the resolved absolute target, or undefined when the file is absent
+ *   or would escape the bundle.
+ */
+export declare function resolveBundleTarget(bundleDir: string, safe: string): Promise<string | undefined>;
 /** Read one skill-bundle file's text content, on demand. */
 export declare function readSkillFileContent(registry: RegistrySlice, name: string, filePath: string, workdir: string | undefined, scope?: unknown, fallback?: SkillDefinitionLike): Promise<CatalogSkillFileRead | undefined>;
 /** Delete a file skill's directory. Returns an error for built-in / plugin-provided

package/lib/types/skills.js

@@ -8,8 +8,8 @@
  * and reads credentials state through the optional `ctx.credentials` service.
  * @module @khorsheed/dsh-capability-catalog/skills
  */
-import { readFile, readdir, rm, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
 import { hashSkillBody } from './capabilities.js';
 /** POSIX identifier — the minimal shape a credential reference name must match
  * (the env keys the catalog handles are a strict subset of this). */
@@ -132,12 +132,18 @@ async function skillBodySha(registry, name, options) {
  *
  * `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.
+ *
+ * `report`, when given, is filled with the collection's health (see
+ * {@link SkillsCollectionReport}); the Remote verbs never pass one, so their
+ * rows — and their digests — are exactly what they were.
  */
 export async function collectSkills(registry, workdir, scopes = [undefined], collectOptions = {}) {
     const byName = new Map();
     for (const scope of scopes) {
         const base = workdir === undefined ? {} : { cwd: workdir };
         const options = scope === undefined ? base : { ...base, scope };
+        if (collectOptions.report !== undefined)
+            collectOptions.report.attemptedScopes += 1;
         let snapshot;
         try {
             snapshot = await registry.snapshot(options);
@@ -145,14 +151,22 @@ export async function collectSkills(registry, workdir, scopes = [undefined], col
         catch {
             // A single scope (e.g. one agent preset) failing must not blank the whole
             // catalog; skip it and keep the rest.
+            if (collectOptions.report !== undefined)
+                collectOptions.report.failedScopes += 1;
             continue;
         }
+        if (snapshot.complete === false && collectOptions.report !== undefined) {
+            collectOptions.report.incompleteReads += 1;
+        }
         for (const summary of snapshot.skills) {
             if (byName.has(summary.name))
                 continue;
             const bodySha = collectOptions.bodySha === true
                 ? await skillBodySha(registry, summary.name, options)
                 : undefined;
+            if (collectOptions.bodySha === true && bodySha === undefined && collectOptions.report !== undefined) {
+                collectOptions.report.unreadableBodies += 1;
+            }
             const row = skillRowFrom(summary, await skillUpdatedAt(summary), bodySha);
             byName.set(row.name, row);
         }
@@ -168,7 +182,7 @@ export async function collectSkills(registry, workdir, scopes = [undefined], col
 /** Directory names never listed as skill-bundle resources. */
 const SKIP_SKILL_DIRS = new Set(['.git', 'node_modules']);
 /** Recursively collect a directory's file paths relative to `root`. */
-async function collectSkillFiles(dir, root, out, depth) {
+export async function collectSkillFiles(dir, root, out, depth) {
     if (depth > 16 || out.length > 1000)
         return;
     let entries;
@@ -191,7 +205,7 @@ async function collectSkillFiles(dir, root, out, depth) {
     }
 }
 /** Reject unsafe bundle-relative paths (absolute, drive-letter, or `..`). */
-function sanitizeBundlePath(path) {
+export function sanitizeBundlePath(path) {
     if (path === '' || path.startsWith('/') || /^[a-zA-Z]:/.test(path))
         return undefined;
     const safe = [];
@@ -204,6 +218,29 @@ function sanitizeBundlePath(path) {
     }
     return safe.length === 0 ? undefined : safe.join('/');
 }
+/**
+ * Resolve an already-sanitized bundle-relative path to its real on-disk
+ * target, refusing anything that escapes the bundle. {@link sanitizeBundlePath}
+ * has already removed the lexical escapes (absolute forms, drive letters,
+ * `..`); this closes what a lexical check cannot:
+ *
+ * - a symlink INSIDE the bundle whose target lives outside it (the bundle
+ *   directory is user content), and
+ * - a prefix collision — containment is a separator-terminated comparison on
+ *   realpaths, so `/root/foobar` never contain-matches `/root/foo`.
+ *
+ * @param bundleDir - the skill's bundle directory (its resource base).
+ * @param safe - a path that already passed {@link sanitizeBundlePath}.
+ * @returns the resolved absolute target, or undefined when the file is absent
+ *   or would escape the bundle.
+ */
+export async function resolveBundleTarget(bundleDir, safe) {
+    const base = await realpath(bundleDir).catch(() => bundleDir);
+    const target = await realpath(join(bundleDir, safe)).catch(() => undefined);
+    if (target === undefined || (target !== base && !target.startsWith(base + sep)))
+        return undefined;
+    return target;
+}
 /** Read one skill-bundle file's text content, on demand. */
 export async function readSkillFileContent(registry, name, filePath, workdir, scope = undefined, fallback) {
     const base = workdir === undefined ? {} : { cwd: workdir };
@@ -218,11 +255,11 @@ export async function readSkillFileContent(registry, name, filePath, workdir, sc
     const safe = sanitizeBundlePath(filePath);
     if (safe === undefined)
         return undefined;
-    const full = join(bundleDir, safe);
-    if (!full.startsWith(bundleDir))
+    const target = await resolveBundleTarget(bundleDir, safe);
+    if (target === undefined)
         return undefined;
     try {
-        const buf = await readFile(full);
+        const buf = await readFile(target);
         return { content: buf.toString('utf8') };
     }
     catch {
@@ -259,9 +296,14 @@ export async function loadSkillDetail(ctx, registry, name, workdir, scope = unde
         return undefined;
     // metadata.credentials are the user-configurable secrets; env-var references
     // detected in the body are the agent's own runtime inputs (DSH_HOME etc.) and
-    // must NOT be offered as configurable credential forms — keep them apart.
+    // must NOT be offered as configurable credential forms — keep them apart. A
+    // body reference already declared as a credential renders in the credential
+    // form; repeating it as a read-only ref would show the same key twice.
     const metadataDecls = decodeCredentialDecls(def.metadata);
-    const environmentRefs = decodeEnvDecls(def.content).map((decl) => decl.key);
+    const declaredKeys = new Set(metadataDecls.map((decl) => decl.key));
+    const environmentRefs = decodeEnvDecls(def.content)
+        .map((decl) => decl.key)
+        .filter((key) => !declaredKeys.has(key));
     const { credentials } = resolveServices(ctx);
     let credentialStates = [];
     if (metadataDecls.length > 0 && credentials !== undefined) {