@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/scoped-edits.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+/** Outcome of one write: a reason is present exactly when it failed. */
+export interface ScopedEditResult {
+    readonly ok: boolean;
+    readonly error?: string;
+}
+/** Where a managed skill came from, for the release path. */
+export interface ManagedSkillLocation {
+    readonly name: string;
+    /** The absolute `SKILL.md` path inside the managed root. */
+    readonly path: string;
+    /** Its directory (the bundle the release moves). */
+    readonly dir: string;
+}
+/**
+ * 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.
+ */
+export declare function withPresetScope(content: string, presets: readonly string[]): string;
+/** Find the managed entry for one skill name. */
+export declare function managedLocation(dshHome: string, name: string): Promise<ManagedSkillLocation | undefined>;
+/**
+ * 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.
+ */
+export declare function setManagedPresetScope(dshHome: string, name: string, presets: readonly string[]): Promise<ScopedEditResult>;
+/** The default root currently supplying one skill, with its shape. */
+export interface SkillSource {
+    readonly root: string;
+    readonly dir?: string;
+    readonly file?: string;
+}
+/**
+ * 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.
+ */
+export declare function findSkillSource(dshHome: string, workdir: string | undefined, name: string): SkillSource | undefined;
+/**
+ * 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.
+ */
+export declare function adoptManagedSkill(dshHome: string, name: string, presets: readonly string[], workdir?: string | undefined): Promise<ScopedEditResult>;
+/**
+ * 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.
+ */
+export declare function releaseManagedSkill(dshHome: string, name: string): Promise<ScopedEditResult>;
+/** Whether a path exists and is a directory. */
+export declare function isDirectory(path: string): Promise<boolean>;
+//# sourceMappingURL=scoped-edits.d.ts.map

package/lib/types/scoped-edits.js

@@ -0,0 +1,234 @@
+/**
+ * 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
+ */
+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';
+/** 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` };
+}
+/**
+ * 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.
+ */
+export function withPresetScope(content, presets) {
+    const split = splitFrontmatter(content);
+    if (split === undefined) {
+        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;
+        }
+        // Drop the key and any block-list items it owned.
+        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. */
+export async function managedLocation(dshHome, name) {
+    const root = scopedSkillsRoot(dshHome);
+    const skill = (await scanManagedSkills(root)).find(entry => entry.name === name);
+    if (skill === undefined)
+        return undefined;
+    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.
+ */
+export async function setManagedPresetScope(dshHome, name, presets) {
+    const badName = invalidName(name);
+    if (badName !== undefined)
+        return badName;
+    const location = await managedLocation(dshHome, name);
+    if (location === undefined) {
+        return { ok: false, error: `"${name}" is not a managed skill` };
+    }
+    try {
+        const content = await readFile(location.path, 'utf8');
+        const updated = withPresetScope(content, presets);
+        // Nothing to write is not a failure: the declared scope already matches.
+        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.
+ */
+export 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 };
+    }
+    return undefined;
+}
+/**
+ * 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.
+ */
+export async function adoptManagedSkill(dshHome, name, presets, workdir) {
+    const badName = invalidName(name);
+    if (badName !== undefined)
+        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 === undefined) {
+        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 !== undefined) {
+            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) };
+    }
+    // Committed: only now drop the default-root copy, and never fail the whole
+    // operation over it — the managed copy is already authoritative.
+    try {
+        if (source.dir !== undefined)
+            await rm(source.dir, { recursive: true, force: true });
+        else if (source.file !== undefined)
+            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.
+ */
+export async function releaseManagedSkill(dshHome, name) {
+    const badName = invalidName(name);
+    if (badName !== undefined)
+        return badName;
+    const location = await managedLocation(dshHome, name);
+    if (location === undefined) {
+        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. */
+export 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);
+}

package/lib/types/settings.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The capability-catalog row's plugin Config: the `mcp` block carries the
+ * persisted MCP management state (server configs, namespaced credential refs,
+ * and discovered tools) so MCP servers survive a restart. Credential values are
+ * stored here (the user's own config document) but are never exposed over the
+ * Remote — `mcpSnapshot` reports only `configured` state.
+ *
+ * Marked `.volatile()` so store mutations write through the SettingsForms
+ * service (host 0.1.7+) without a row reload, and external document updates
+ * reach the running fiber's Volatile reference. The block stays permissive
+ * (`z.any()`): the catalog card reads/writes it through the Remote, and a
+ * hand-typed schemastery shape for the nested config/tuple/secret structure is
+ * fragile.
+ *
+ * Dual-line: `.volatile()` exists only on schemastery 3.18.4+ (the 0.1.7 host
+ * line). On 0.1.5's schemastery the call is absent — the plain field then
+ * rides the legacy `settings.register` namespace path instead (see index.ts).
+ */
+import z from '@deepseek-ai/schemastery';
+/** The persisted MCP state block lives under this key of the plugin config. */
+export declare const MCP_SETTINGS_KEY = "mcp";
+/** Section shape: the MCP management state block (permissive) + nothing else. */
+export declare const CapabilityCatalogSettingsSchema: z<Schemastery.ObjectS<{
+    mcp: z<any, any>;
+}>, Schemastery.ObjectT<{
+    mcp: z<any, any>;
+}>>;
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/settings.js

@@ -0,0 +1,28 @@
+/**
+ * The capability-catalog row's plugin Config: the `mcp` block carries the
+ * persisted MCP management state (server configs, namespaced credential refs,
+ * and discovered tools) so MCP servers survive a restart. Credential values are
+ * stored here (the user's own config document) but are never exposed over the
+ * Remote — `mcpSnapshot` reports only `configured` state.
+ *
+ * Marked `.volatile()` so store mutations write through the SettingsForms
+ * service (host 0.1.7+) without a row reload, and external document updates
+ * reach the running fiber's Volatile reference. The block stays permissive
+ * (`z.any()`): the catalog card reads/writes it through the Remote, and a
+ * hand-typed schemastery shape for the nested config/tuple/secret structure is
+ * fragile.
+ *
+ * Dual-line: `.volatile()` exists only on schemastery 3.18.4+ (the 0.1.7 host
+ * line). On 0.1.5's schemastery the call is absent — the plain field then
+ * rides the legacy `settings.register` namespace path instead (see index.ts).
+ */
+import z from '@deepseek-ai/schemastery';
+/** The persisted MCP state block lives under this key of the plugin config. */
+export const MCP_SETTINGS_KEY = 'mcp';
+const mcpField = z.any().default({});
+/** Section shape: the MCP management state block (permissive) + nothing else. */
+export const CapabilityCatalogSettingsSchema = z.object({
+    [MCP_SETTINGS_KEY]: typeof mcpField.volatile === 'function'
+        ? mcpField.volatile()
+        : mcpField,
+});

package/lib/types/shellEnv.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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
+ */
+import type { Context } from '@deepseek-ai/cordis';
+declare const DSH_PREFIX = "DSH_";
+/** The `ctx.shellEnv` registry slice this module consumes (optional). */
+export interface ShellEnvRegistryLike {
+    register: (contributor: {
+        name: string;
+        variables: Record<string, {
+            description: string;
+        }>;
+        resolve: (execution: unknown) => Record<string, string>;
+    }) => () => void;
+    list: () => readonly {
+        readonly key: string;
+        readonly contributor: string;
+    }[];
+}
+/**
+ * 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.
+ */
+export declare function installSkillEnvInjection(ctx: Context, getScope: () => Promise<unknown | undefined>): () => void;
+export { DSH_PREFIX };
+//# sourceMappingURL=shellEnv.d.ts.map

package/lib/types/shellEnv.js

@@ -0,0 +1,232 @@
+/**
+ * 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
+ */
+import { decodeCredentialDecls, decodeEnvDecls, mergeCredentialDecls } from './skills.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
+ * (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 = 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.
+ */
+export function installSkillEnvInjection(ctx, getScope) {
+    let disposed = false;
+    let envCache = 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 !== undefined) {
+            clearTimeout(retryTimer);
+            retryTimer = undefined;
+        }
+    };
+    const scheduleRetry = () => {
+        if (disposed || retries >= MAX_RETRIES)
+            return;
+        cancelRetry();
+        retries++;
+        retryTimer = setTimeout(() => {
+            retryTimer = undefined;
+            if (!disposed)
+                void 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 !== undefined) {
+            // Bump the generation so the in-flight pass is now stale and will not
+            // commit the value it read before this update arrived (strict
+            // latest-wins); the queued pass re-reads + commits fresh.
+            refreshGen++;
+            queued = true;
+            return;
+        }
+        // Re-resolve the services FRESH on every pass (never across an `await`).
+        // `ctx.get` (strict) returns the implementation only while its providing
+        // fiber is active, so a reload/reorder that makes a previously-captured
+        // reference inactive is never called into here. If any service is not
+        // currently active, this is a transient boot window — retry.
+        const shellEnv = ctx.get?.('shellEnv');
+        const credentials = ctx.get?.('credentials');
+        const skills = ctx.get?.('skills');
+        if (shellEnv?.register === undefined || credentials === undefined || skills === undefined) {
+            scheduleRetry();
+            return;
+        }
+        const gen = ++refreshGen;
+        inFlight = (async () => {
+            const scope = await getScope().catch(() => undefined);
+            const snapshotOptions = scope === undefined ? {} : { scope };
+            try {
+                const snapshot = await skills.snapshot(snapshotOptions);
+                // Keys already owned by another contributor (must not redeclare).
+                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;
+                    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}${decl.key}`;
+                        // Never let a credential take over a reserved built-in DSH_* name
+                        // (DSH_HOME etc.). Declaring `HOME` maps to `DSH_HOME` and is
+                        // dropped here; declaring `DSH_HOME` maps to `DSH_DSH_HOME`, which
+                        // is not reserved and stays.
+                        if (RESERVED_ENV_KEYS.has(dshKey) || occupied.has(dshKey))
+                            continue;
+                        keys.add(decl.key);
+                        const resolved = await credentials.resolve(decl.key).catch(() => undefined);
+                        if (resolved !== undefined && resolved.value.length > 0)
+                            values.set(dshKey, resolved.value);
+                    }
+                }
+                if (disposed || gen !== refreshGen)
+                    return; // stale or disposed — drop the commit
+                envCache = values;
+                const keySet = [...keys].sort().join('\n');
+                if (keySet !== refreshKey) {
+                    disposeEnv?.();
+                    disposeEnv = undefined;
+                    refreshKey = undefined;
+                    const variables = {};
+                    for (const k of keys) {
+                        variables[`${DSH_PREFIX}${k}`] = { description: `Configured via the capability catalog for skill env \`${k}\`` };
+                    }
+                    // Re-resolve the registry immediately before `register` — never call
+                    // `ctx.effect` on a reference captured across an `await`. If the
+                    // service is inactive right now (boot reorder window), drop this pass
+                    // and retry; leave refreshKey unset so the next pass re-registers.
+                    const shellEnvNow = ctx.get?.('shellEnv');
+                    if (shellEnvNow?.register === undefined) {
+                        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) {
+                        // Register failed (e.g. a TOCTOU owner collision). Leave refreshKey
+                        // unset so the NEXT refresh retries regardless of the key set even
+                        // if the key set later returns to a previously-registered value.
+                        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 = undefined;
+                if (queued && !disposed) {
+                    queued = false;
+                    void refresh();
+                }
+            }
+        })();
+        await inFlight;
+    };
+    void refresh();
+    const offRecord = ctx.on('credentials/record-updated', () => { void refresh(); });
+    const offReference = ctx.on('credentials/reference-updated', () => { void refresh(); });
+    return () => {
+        disposed = true;
+        cancelRetry();
+        disposeEnv?.();
+        offRecord();
+        offReference();
+    };
+}
+export { DSH_PREFIX };