loadout-ai 0.1.2 → 0.2.1

package/dist/src/cli.js

@@ -68,6 +68,7 @@ import { applyUpgrade, formatUpgradePlan, planUpgrade, summarizeUpgradePlan, } f
 import { formatAgentVersions, inspectAgentVersions, } from "./core/agent-versions.js";
 import { formatAgentHealthScore } from "./core/agent-health-score.js";
 import { buildLocalAgentHealthScores } from "./core/health-score-evidence.js";
+import { interactiveModelApiAccess, parseModelApiAccess, } from "./core/access.js";
 import { discoverSkillsSh } from "./core/skills-sh-discovery.js";
 import { discoverOfficialMcpRegistry } from "./core/mcp-registry-discovery.js";
 import { createBenchmarkRun, formatBenchmarkCampaignSummary, parseBenchmarkCampaign, summarizeBenchmarkCampaign, } from "./core/benchmark-campaign.js";
@@ -82,6 +83,34 @@ const collectOption = (value, previous = []) => [
     ...previous,
     value,
 ];
+function parseMcpCredentialMappings(recipe, mappings, account) {
+    const references = {};
+    for (const mapping of mappings) {
+        const separator = mapping.indexOf("=");
+        if (separator <= 0)
+            throw new Error("Invalid --credential mapping; expected NAME=env:VARIABLE or NAME=keychain:SERVICE. Never pass a credential value.");
+        const name = mapping.slice(0, separator);
+        const value = mapping.slice(separator + 1);
+        if (!recipe.environment.includes(name))
+            throw new Error(`Credential '${name}' is not required by recipe '${recipe.id}'`);
+        if (references[name])
+            throw new Error(`Credential '${name}' was mapped more than once`);
+        if (value.startsWith("env:") && value.length > 4)
+            references[name] = {
+                kind: "environment",
+                name: value.slice(4),
+            };
+        else if (value.startsWith("keychain:") && value.length > 9)
+            references[name] = {
+                kind: "os-keychain",
+                service: value.slice(9),
+                ...(account ? { account } : {}),
+            };
+        else
+            throw new Error(`Invalid --credential mapping for '${name}'; use env:VARIABLE or keychain:SERVICE, never a credential value.`);
+    }
+    return references;
+}
 async function readCredentialFromStdin() {
     if (process.stdin.isTTY)
         throw new Error("Credential input must be piped on stdin; interactive echo is intentionally unsupported");
@@ -145,6 +174,9 @@ async function runSetup(options) {
     let mode = options.mode;
     let packageIds = options.package ?? [];
     let reader;
+    let access = options.apiAccess
+        ? parseModelApiAccess(options.apiAccess)
+        : undefined;
     try {
         if (!mode) {
             if (!interactive) {
@@ -172,11 +204,20 @@ async function runSetup(options) {
                     .filter(Boolean);
             }
         }
+        if (!access && interactive && !options.yes) {
+            reader ??= createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            access = interactiveModelApiAccess(await reader.question("Separately billed model API access (ChatGPT/Claude subscriptions do not count): [0] None, [1] OpenAI API, [2] Anthropic API, [3] Both, [4] OpenRouter, [5] Other: "));
+        }
+        access ??= { modelApis: [] };
         const selection = setupSelection(mode, packageIds);
         console.log("\nPreparing a read-only install plan from screened immutable commits…");
         const prepared = await prepareCatalogInstall(selection, {
             requestedAgents: parseAgentSelection(options.agents),
             onProgress: printSetupProgress,
+            access,
         });
         console.log(`\n${formatPreparedCatalogInstall(prepared)}\n`);
         const risky = riskyPackageSummary(prepared);
@@ -221,7 +262,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.1.2";
+const LOADOUT_VERSION = "0.2.1";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -250,6 +291,7 @@ program
     .option("--mode <mode>", "stable, power, maximum, or custom")
     .option("--agents <ids>", "comma-separated target agent ids")
     .option("--package <id>", "package id for custom mode", collectOption, [])
+    .option("--api-access <providers>", "separately billed model API access: none, openai, anthropic, openrouter, or other (comma-separated; never a key)")
     .option("-y, --yes", "install after preparing the screened plan")
     .option("--approve-risk", "approve reviewed safety findings in non-interactive mode")
     .action((options) => runSetup(options));
@@ -260,6 +302,7 @@ program
     .option("--project <path>", "project directory", process.cwd())
     .option("--agents <ids>", "comma-separated target agent ids")
     .option("--package <id>", "package id for custom mode", collectOption, [])
+    .option("--api-access <providers>", "separately billed model API access: none, openai, anthropic, openrouter, or other (comma-separated; never a key)")
     .option("--yes", "apply the exact displayed upgrade")
     .option("--approve-risk", "approve the displayed reviewed safety findings")
     .option("--json", "emit a machine-readable preview or result")
@@ -268,6 +311,7 @@ program
         projectPath: options.project,
         requestedAgents: parseAgentSelection(options.agents),
         onProgress: options.json ? undefined : printSetupProgress,
+        access: parseModelApiAccess(options.apiAccess),
     });
     if (!options.yes) {
         console.log(options.json
@@ -2081,31 +2125,7 @@ program
         if (options.verify || options.yes)
             throw new Error("--connect cannot be combined with --verify or --yes");
         const recipe = findMcpRecipe(id);
-        const credentialReferences = {};
-        for (const mapping of options.credential) {
-            const separator = mapping.indexOf("=");
-            if (separator <= 0)
-                throw new Error(`Invalid --credential '${mapping}'; expected NAME=env:VARIABLE or NAME=keychain:SERVICE`);
-            const name = mapping.slice(0, separator);
-            const value = mapping.slice(separator + 1);
-            if (!recipe.environment.includes(name))
-                throw new Error(`Credential '${name}' is not required by recipe '${id}'`);
-            if (value.startsWith("env:"))
-                credentialReferences[name] = {
-                    kind: "environment",
-                    name: value.slice(4),
-                };
-            else if (value.startsWith("keychain:"))
-                credentialReferences[name] = {
-                    kind: "os-keychain",
-                    service: value.slice(9),
-                    ...(options.credentialAccount
-                        ? { account: options.credentialAccount }
-                        : {}),
-                };
-            else
-                throw new Error(`Invalid --credential '${mapping}'; use env: or keychain:`);
-        }
+        const credentialReferences = parseMcpCredentialMappings(recipe, options.credential, options.credentialAccount);
         const timeoutMs = Number(options.timeout);
         const controller = new AbortController();
         const abort = () => controller.abort();
@@ -2141,7 +2161,12 @@ program
             process.exitCode = 1;
         return;
     }
-    const plan = await planMcpRecipe(id, options.config);
+    const recipe = findMcpRecipe(id);
+    const credentialReferences = parseMcpCredentialMappings(recipe, options.credential, options.credentialAccount);
+    const plan = await planMcpRecipe(id, options.config, {
+        credentialReferences,
+        requireResolvedCredentials: Boolean(options.yes),
+    });
     if (!options.yes) {
         console.log(options.json
             ? JSON.stringify(plan, null, 2)

package/dist/src/core/access.js

@@ -0,0 +1,42 @@
+export const MODEL_API_PROVIDERS = [
+    "openai",
+    "anthropic",
+    "openrouter",
+    "other",
+];
+export function parseModelApiAccess(input) {
+    if (!input || input.trim().toLowerCase() === "none")
+        return { modelApis: [] };
+    const values = [
+        ...new Set(input
+            .split(",")
+            .map((value) => value.trim().toLowerCase())
+            .filter(Boolean)),
+    ];
+    if (values.includes("none"))
+        throw new Error("--api-access 'none' cannot be combined with providers");
+    const supported = new Set(MODEL_API_PROVIDERS);
+    const unknown = values.filter((value) => !supported.has(value));
+    if (unknown.length)
+        throw new Error(`Unknown API provider selection. Supported values: none, ${MODEL_API_PROVIDERS.join(", ")}. Pass provider names only, never a key.`);
+    return { modelApis: values };
+}
+export function interactiveModelApiAccess(answer) {
+    const value = answer.trim().toLowerCase();
+    if (value === "1" || value === "openai")
+        return { modelApis: ["openai"] };
+    if (value === "2" || value === "anthropic")
+        return { modelApis: ["anthropic"] };
+    if (value === "3" || value === "both")
+        return { modelApis: ["openai", "anthropic"] };
+    if (value === "4" || value === "openrouter")
+        return { modelApis: ["openrouter"] };
+    if (value === "5" || value === "other")
+        return { modelApis: ["other"] };
+    return { modelApis: [] };
+}
+export function formatModelApiAccess(profile) {
+    return profile.modelApis.length
+        ? profile.modelApis.join(", ")
+        : "none declared";
+}

package/dist/src/core/catalog-install.js

@@ -4,6 +4,7 @@ import { isStableSkillSelected, isPowerSkillSelected, resolveCatalogProfile, } f
 import { applySkillLibraryBatch, applySkillInstallBatch, buildSkillPlan, installedAgents, } from "./install.js";
 import { fetchRepositorySnapshot, } from "./source.js";
 import { analyzeInstallPlanSafety, } from "./safety.js";
+import { formatModelApiAccess } from "./access.js";
 export const RECOMMENDED_ACTIVE_SKILL_LIMIT = 30;
 async function parallelMap(values, concurrency, worker) {
     const results = new Array(values.length);
@@ -40,6 +41,7 @@ export async function prepareCatalogInstall(selection, options = {}) {
     const fetchSnapshot = options.fetchSnapshot ?? fetchRepositorySnapshot;
     let completed = 0;
     const prepared = await parallelMap(installable, options.concurrency ?? 4, async (pkg) => {
+        const rejected = new Map();
         options.onProgress?.({
             packageId: pkg.id,
             completed,
@@ -60,7 +62,24 @@ export async function prepareCatalogInstall(selection, options = {}) {
                 : selection.mode === "power"
                     ? (skill) => isPowerSkillSelected(pkg.id, skill.name, skill.targetName)
                     : undefined;
-            const plan = await buildSkillPlan(fetched.path, pkg.id, agents, include ? { include } : {});
+            const quarantineOptions = selection.mode === "maximum" || selection.mode === "power"
+                ? {
+                    continueOnRejected: true,
+                    onRejected: (skill) => {
+                        const unitId = skill.name ?? skill.targetName;
+                        rejected.set(unitId, {
+                            packageId: pkg.id,
+                            unitId,
+                            kind: "quarantined",
+                            reason: skill.reason,
+                        });
+                    },
+                }
+                : {};
+            const plan = await buildSkillPlan(fetched.path, pkg.id, agents, {
+                ...(include ? { include } : {}),
+                ...quarantineOptions,
+            });
             if (selection.mode === "stable")
                 plan.files = plan.files.filter((file) => isStableSkillSelected(pkg.id, file.skillName, file.target.split(/[\\/]/).at(-1) ?? pkg.id));
             if (selection.mode === "power")
@@ -77,14 +96,27 @@ export async function prepareCatalogInstall(selection, options = {}) {
                 message: `${pkg.displayName} is ready (${plan.files.length} target directories)`,
             });
             return {
-                package: pkg,
-                plan,
-                metadata: {
-                    repository: fetched.repository,
-                    resolvedCommit: fetched.commit,
-                    reviewed: true,
+                result: {
+                    package: pkg,
+                    plan,
+                    metadata: {
+                        repository: fetched.repository,
+                        resolvedCommit: fetched.commit,
+                        reviewed: true,
+                        staticAssessment: {
+                            status: safety.approvalRequired
+                                ? "blocking"
+                                : safety.findings.length
+                                    ? "warning"
+                                    : "clear",
+                            findingCount: safety.findings.length,
+                            assessedAt: new Date().toISOString(),
+                            policy: "install-safety-v1",
+                        },
+                    },
+                    safety,
                 },
-                safety,
+                quarantined: [...rejected.values()],
             };
         }
         catch (error) {
@@ -97,11 +129,21 @@ export async function prepareCatalogInstall(selection, options = {}) {
                 status: "skipped",
                 message: `${pkg.displayName} could not be prepared: ${reason}`,
             });
-            return { packageId: pkg.id, reason, kind: "preparation-failed" };
+            if (rejected.size > 0 && /No SKILL\.md found/.test(reason))
+                return { quarantined: [...rejected.values()] };
+            return {
+                result: {
+                    packageId: pkg.id,
+                    reason,
+                    kind: "preparation-failed",
+                },
+                quarantined: [...rejected.values()],
+            };
         }
     });
-    const entries = prepared.filter((item) => "plan" in item);
-    skipped.push(...prepared.filter((item) => !("plan" in item)));
+    const preparedResults = prepared.flatMap((item) => item.result ? [item.result] : []);
+    const entries = preparedResults.filter((item) => "plan" in item);
+    skipped.push(...preparedResults.filter((item) => !("plan" in item)), ...prepared.flatMap((item) => item.quarantined));
     // Broad collections frequently publish the same conventional skill name.
     // Resolution order is already deterministic and evidence-ranked, so keep
     // the first source for a target and defer only the lower-ranked duplicate
@@ -140,6 +182,7 @@ export async function prepareCatalogInstall(selection, options = {}) {
         entries: usableEntries,
         skipped,
         collisions,
+        access: options.access ?? { modelApis: [] },
     };
 }
 export function formatPreparedCatalogInstall(prepared) {
@@ -150,17 +193,22 @@ export function formatPreparedCatalogInstall(prepared) {
     const risky = prepared.entries.filter((entry) => entry.safety.approvalRequired);
     const explicit = prepared.skipped.filter((item) => item.kind === "explicit-setup");
     const failures = prepared.skipped.filter((item) => item.kind === "preparation-failed");
+    const quarantined = prepared.skipped.filter((item) => item.kind === "quarantined");
     const lines = [
         `Loadout: ${prepared.selection.mode === "maximum" ? "Maximum Library" : prepared.selection.mode === "power" ? "Power Boost" : prepared.selection.mode === "stable" ? "Stable Boost" : "Custom"}`,
         `Detected agents: ${prepared.agents.map((agent) => agent.displayName).join(", ")}`,
         `Catalog selection: ${prepared.resolution.packages.length} repositories`,
         `Ready to install: ${prepared.entries.length} skill repositories (${targetDirectories} agent skill directories)`,
         `Explicit setup later: ${explicit.length} repository/repositories`,
+        `Separately billed model API access: ${formatModelApiAccess(prepared.access)} (ChatGPT and Claude subscriptions do not count as API access)`,
+        "Automatic skill setup does not require an OpenAI, Anthropic, or OpenRouter API key; credentialed MCP/runtime integrations remain explicit and deferred.",
     ];
     if (directoriesPerAgent > RECOMMENDED_ACTIVE_SKILL_LIMIT)
         lines.push(`Capacity warning: about ${directoriesPerAgent} skill directories per agent exceeds the recommended active-set limit of ${RECOMMENDED_ACTIVE_SKILL_LIMIT}.${prepared.selection.mode === "maximum" ? " Maximum stores these in the disabled library; use project activation to choose the working set." : " Prefer Stable or project-aware activation for smaller context."}`);
     if (failures.length)
         lines.push(`Preparation failures (installation will remain blocked): ${failures.map((item) => item.packageId).join(", ")}`);
+    if (quarantined.length)
+        lines.push(`Quarantined invalid skill units: ${quarantined.length} (safe siblings remain available)`);
     if (prepared.collisions.length)
         lines.push(`Overlapping skill targets resolved: ${prepared.collisions.length} lower-ranked duplicate directories deferred`);
     if (risky.length)
@@ -168,7 +216,7 @@ export function formatPreparedCatalogInstall(prepared) {
     for (const warning of prepared.resolution.warnings)
         lines.push(`Warning: ${warning}`);
     for (const item of prepared.skipped)
-        lines.push(`${item.kind === "preparation-failed" ? "Failed" : "Deferred"} ${item.packageId}: ${item.reason}`);
+        lines.push(`${item.kind === "preparation-failed" ? "Failed" : item.kind === "quarantined" ? "Quarantined" : "Deferred"} ${item.packageId}${item.unitId ? `/${item.unitId}` : ""}: ${item.reason}`);
     return lines.join("\n");
 }
 export async function applyPreparedCatalogInstall(prepared, options = {}) {
@@ -182,5 +230,7 @@ export async function applyPreparedCatalogInstall(prepared, options = {}) {
         throw new Error(`Additional risk approval is required for: ${risky.map((entry) => entry.package.id).join(", ")}. Review the plan, then use --approve-risk.`);
     return prepared.selection.mode === "maximum"
         ? applySkillLibraryBatch(prepared.entries)
-        : applySkillInstallBatch(prepared.entries);
+        : applySkillInstallBatch(prepared.entries, [], {
+            replaceManagedTargets: true,
+        });
 }

package/dist/src/core/health-score-evidence.js

@@ -103,6 +103,14 @@ export async function collectLocalAgentHealthEvidence(options = {}) {
                     ? "verified"
                     : "managed",
                 ...(pkg?.license ? { license: pkg.license } : {}),
+                ...(install.staticAssessment
+                    ? {
+                        staticRisk: {
+                            status: install.staticAssessment.status,
+                            findingCount: install.staticAssessment.findingCount,
+                        },
+                    }
+                    : {}),
                 ...(observedFreshness ? { freshness: observedFreshness } : {}),
             };
         });

package/dist/src/core/install.js

@@ -1,9 +1,9 @@
 import { existsSync } from "node:fs";
 import { cp, lstat, rm } from "node:fs/promises";
-import { basename, dirname, join, posix, relative, win32 } from "node:path";
+import { basename, dirname, isAbsolute, join, posix, relative, win32, } from "node:path";
 import { ensureDirectory, loadoutHome } from "./paths.js";
 import { planAdapterSkillInstall } from "./adapters.js";
-import { applySkillPlan, detectInstallConflicts, validateSkillDirectory, } from "./skills.js";
+import { applySkillPlan, detectInstallConflicts } from "./skills.js";
 import { activationLibraryPath, installStatePath, recordInstall, recordInstallBatch, recordLibraryInstallBatch, readInstallState, hashDirectory, } from "./state.js";
 import { runMutationTransaction } from "./transaction.js";
 export function installedAgents(agents, requested) {
@@ -17,6 +17,26 @@ export function installedAgents(agents, requested) {
     }
     return selected;
 }
+function relativeHashes(root, files) {
+    return files
+        .filter((file) => {
+        const child = relative(root, file.path);
+        return child !== "" && !child.startsWith("..") && !isAbsolute(child);
+    })
+        .map((file) => ({
+        path: relative(root, file.path),
+        sha256: file.sha256,
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+async function assertExactDirectoryCopy(source, target, label) {
+    const [expected, actual] = await Promise.all([
+        hashDirectory(source).then((files) => relativeHashes(source, files)),
+        hashDirectory(target).then((files) => relativeHashes(target, files)),
+    ]);
+    if (JSON.stringify(actual) !== JSON.stringify(expected))
+        throw new Error(`${label} for ${target}`);
+}
 async function assertActiveTargetsUnoccupied(plans, options = {}) {
     const occupied = [];
     for (const target of [
@@ -35,26 +55,40 @@ async function assertActiveTargetsUnoccupied(plans, options = {}) {
         }
     if (occupied.length && options.allowManagedReplacement) {
         const state = await readInstallState();
-        const allowed = new Set(plans.flatMap((plan) => {
+        const allowed = new Map();
+        for (const plan of plans) {
             const install = state.installs.find((record) => record.packageId === plan.packageId);
             const packageActivations = (state.activations ?? []).filter((record) => record.packageId === plan.packageId);
-            const active = packageActivations.length === 0 ||
-                packageActivations.some((record) => record.installationState === "installed" &&
-                    record.activationState === "active");
-            if (!install || !active)
-                return [];
+            if (!install)
+                continue;
+            const activeTargets = new Set(packageActivations
+                .filter((record) => record.installationState === "installed" &&
+                record.activationState === "active")
+                .flatMap((record) => record.targets.map((target) => target.activePath)));
             const recorded = install.files
                 .filter((file) => basename(file.path) === "SKILL.md")
-                .map((file) => dirname(file.path));
+                .map((file) => dirname(file.path))
+                .filter((target) => packageActivations.length === 0 || activeTargets.has(target));
             const legacy = packageActivations.length
                 ? []
                 : plan.files
                     .map((file) => file.target)
                     .filter((target) => basename(target) === plan.packageId);
-            return [...recorded, ...legacy];
-        }));
-        if (occupied.every((target) => allowed.has(target)))
+            for (const target of [...recorded, ...legacy])
+                if (plan.files.some((file) => file.target === target))
+                    allowed.set(target, install);
+        }
+        if (occupied.every((target) => allowed.has(target))) {
+            for (const target of occupied) {
+                const owner = allowed.get(target);
+                const expected = relativeHashes(target, owner?.files ?? []);
+                const actual = relativeHashes(target, await hashDirectory(target));
+                if (!expected.length ||
+                    JSON.stringify(actual) !== JSON.stringify(expected))
+                    throw new Error(`Installation refuses to replace drifted managed skill target: ${target}`);
+            }
             return;
+        }
     }
     if (occupied.length)
         throw new Error(`Installation refuses ${occupied.length} occupied skill target(s); scan, compare, or adopt them first. First target: ${occupied[0]}`);
@@ -66,15 +100,6 @@ export async function buildSkillPlan(source, packageId, agents, options = {}) {
     if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink()) {
         throw new Error(`Package source must be a real directory: ${source}`);
     }
-    // A repository may contain one skill at its root or several nested skills.
-    // Validate the root when present; planSkillInstall validates every nested skill.
-    if (existsSync(join(source, "SKILL.md")) &&
-        (!options.include ||
-            options.include({
-                path: source,
-                targetName: basename(source),
-            })))
-        await validateSkillDirectory(source);
     const plans = await Promise.all(agents.map((agent) => planAdapterSkillInstall(source, packageId, agent, options)));
     const files = plans.flatMap((plan) => plan.files);
     const conflicts = detectInstallConflicts([
@@ -115,20 +140,7 @@ export async function applySkillInstall(plan, metadata, options = {}) {
         await applySkillPlan(freshPlan);
         if (options.replaceManagedTargets)
             for (const file of freshPlan.files) {
-                const expected = (await hashDirectory(file.source))
-                    .map((entry) => ({
-                    path: relative(file.source, entry.path),
-                    sha256: entry.sha256,
-                }))
-                    .sort((left, right) => left.path.localeCompare(right.path));
-                const actual = (await hashDirectory(file.target))
-                    .map((entry) => ({
-                    path: relative(file.target, entry.path),
-                    sha256: entry.sha256,
-                }))
-                    .sort((left, right) => left.path.localeCompare(right.path));
-                if (JSON.stringify(actual) !== JSON.stringify(expected))
-                    throw new Error(`Exact update copy verification failed for ${file.target}`);
+                await assertExactDirectoryCopy(file.source, file.target, "Exact update copy verification failed");
             }
         await recordInstall(freshPlan, snapshot.id, metadata);
         await options.verifyBeforeCommit?.(snapshot.id);
@@ -136,7 +148,7 @@ export async function applySkillInstall(plan, metadata, options = {}) {
     return applied.snapshotId;
 }
 /** Apply all selected packages as one filesystem transaction and one state update. */
-export async function applySkillInstallBatch(entries, extraSnapshotPaths = []) {
+export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], options = {}) {
     if (!entries.length)
         throw new Error("Installation batch is empty");
     const conflicts = detectInstallConflicts(entries.map((entry) => entry.plan));
@@ -144,7 +156,7 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = []) {
     if (blocking.length)
         throw new Error(`Installation blocked by conflicts: ${blocking.map((item) => item.message).join("; ")}`);
     const applied = await runMutationTransaction(async () => {
-        await assertActiveTargetsUnoccupied(entries.map((entry) => entry.plan));
+        await assertActiveTargetsUnoccupied(entries.map((entry) => entry.plan), { allowManagedReplacement: options.replaceManagedTargets });
         for (const entry of entries) {
             entry.plan.conflicts = [
                 ...(entry.plan.conflicts ?? []),
@@ -169,8 +181,17 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = []) {
             value: entries,
         };
     }, async (freshEntries, snapshot) => {
+        if (options.replaceManagedTargets)
+            for (const target of [
+                ...new Set(freshEntries.flatMap((entry) => entry.plan.files.map((file) => file.target))),
+            ])
+                await rm(target, { recursive: true, force: true });
         for (const entry of freshEntries)
             await applySkillPlan(entry.plan);
+        if (options.replaceManagedTargets)
+            for (const entry of freshEntries)
+                for (const file of entry.plan.files)
+                    await assertExactDirectoryCopy(file.source, file.target, "Exact setup copy verification failed");
         await recordInstallBatch(freshEntries, snapshot.id);
     });
     return applied.snapshotId;
@@ -195,8 +216,20 @@ export async function applySkillLibraryBatch(entries) {
         const active = (state.activations ?? []).filter((record) => selected.has(record.packageId) &&
             record.installationState === "installed" &&
             record.activationState === "active");
-        if (active.length)
-            throw new Error(`Maximum Library will not relabel ${active.length} active managed skill(s) as disabled. Disable the selected packages first, then retry.`);
+        for (const activation of active) {
+            const current = state.installs.find((record) => record.packageId === activation.packageId);
+            const incoming = entries.find((entry) => entry.plan.packageId === activation.packageId);
+            if (!current?.resolvedCommit ||
+                !incoming?.metadata?.resolvedCommit ||
+                current.resolvedCommit.toLowerCase() !==
+                    incoming.metadata.resolvedCommit.toLowerCase())
+                throw new Error(`Maximum Library cannot preserve active '${activation.packageId}/${activation.unitId ?? "skill"}' because its reviewed revision differs or is unknown. Update or disable it explicitly first.`);
+            const includesActiveUnit = incoming.plan.files.some((file) => (file.targetAgent === activation.agent ||
+                (!file.targetAgent && incoming.plan.targetAgents.length === 1)) &&
+                basename(file.target) === activation.unitId);
+            if (!includesActiveUnit)
+                throw new Error(`Maximum Library cannot preserve active '${activation.packageId}/${activation.unitId ?? "skill"}' because that unit is absent from the prepared library.`);
+        }
         return {
             targets: [...libraryPaths, installStatePath()],
             value: entries,

package/dist/src/core/mcp-recipes.js

@@ -58,29 +58,57 @@ export function findMcpRecipe(id) {
     }
     return recipe;
 }
-function recipeServer(recipe, sourcePath) {
+function recipeServer(recipe, sourcePath, credentialEnvironment = {}) {
     return {
         name: recipe.serverName,
         command: recipe.command,
         args: recipe.args,
         // References retain variable names without storing or printing their values.
         env: Object.fromEntries([
-            ...recipe.environment.map((name) => [name, `\${${name}}`]),
+            ...recipe.environment.map((name) => [name, `\${${credentialEnvironment[name] ?? name}}`]),
             ...Object.entries(recipe.fixedEnvironment),
         ]),
         sourcePath,
         warnings: [],
     };
 }
-export async function planMcpRecipe(recipeId, configPath) {
+export async function planMcpRecipe(recipeId, configPath, options = {}) {
     const recipe = findMcpRecipe(recipeId);
-    const config = await planMcpConfig(configPath, recipeServer(recipe, recipe.source));
+    const environment = options.environment ?? process.env;
+    const credentialEnvironment = {};
+    for (const name of Object.keys(options.credentialReferences ?? {}))
+        if (!recipe.environment.includes(name))
+            throw new Error(`Credential '${name}' is not required by recipe '${recipeId}'`);
+    for (const name of recipe.environment) {
+        const reference = options.credentialReferences?.[name];
+        if (!reference) {
+            if (options.requireResolvedCredentials)
+                throw new Error(`Recipe '${recipeId}' requires a credential reference for ${name}; use ${name}=env:VARIABLE.`);
+            continue;
+        }
+        if (reference.kind !== "environment") {
+            if (options.requireResolvedCredentials)
+                throw new Error(`OS-keychain references are supported for explicit connection verification, but host MCP configuration requires an environment reference for ${name}.`);
+            continue;
+        }
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(reference.name))
+            throw new Error(`Invalid environment reference for ${name}; use an uppercase variable name, never a credential value.`);
+        if (!reference.name || !environment[reference.name]) {
+            if (options.requireResolvedCredentials)
+                throw new Error(`Environment credential reference '${reference.name || "(empty)"}' for ${name} did not resolve.`);
+            continue;
+        }
+        credentialEnvironment[name] = reference.name;
+    }
+    const config = await planMcpConfig(configPath, recipeServer(recipe, recipe.source, credentialEnvironment));
     return {
         recipe,
         config,
         authorization: recipe.environment.length
             ? [
-                `Set these environment variables outside Loadout before starting the host: ${recipe.environment.join(", ")}.`,
+                `Set these environment variables outside Loadout before starting the host: ${recipe.environment
+                    .map((name) => `${name}=${credentialEnvironment[name] ?? name} (reference only)`)
+                    .join(", ")}.`,
             ]
             : ["No credential reference is required by this recipe."],
         safety: [
@@ -375,8 +403,11 @@ export async function verifyMcpRecipe(recipeId, configPath) {
             warnings.push("configured arguments do not match recipe");
         const env = record.env;
         for (const name of recipe.environment) {
-            if (typeof env?.[name] === "string")
+            if (typeof env?.[name] === "string" &&
+                /^\$\{[A-Z_][A-Z0-9_]*\}$/.test(env[name]))
                 checks.push(`environment reference present: ${name}`);
+            else if (typeof env?.[name] === "string")
+                warnings.push(`configured environment entry is not a variable reference: ${name}`);
             else
                 warnings.push(`missing environment reference: ${name}`);
         }